VirtualBox

source: vbox/trunk/include/iprt/uri.h@ 103224

Last change on this file since 103224 was 102554, checked in by vboxsync, 10 months ago

IPRT/uri.h: Improved docs.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.9 KB
Line 
1/** @file
2 * IPRT - Uniform Resource Identifier handling.
3 */
4
5/*
6 * Copyright (C) 2011-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_uri_h
37#define IPRT_INCLUDED_uri_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt_uri RTUri - Uri parsing and creation
48 *
49 * URI parsing and creation based on RFC-3986.
50 *
51 * @remarks The whole specification isn't implemented and we only provide scheme
52 * specific special APIs for "file://".
53 *
54 * @ingroup grp_rt
55 * @{
56 */
57
58
59/**
60 * Parsed URI.
61 *
62 * @remarks This structure is subject to change.
63 */
64typedef struct RTURIPARSED
65{
66 /** Magic value (for internal use only). */
67 uint32_t u32Magic;
68 /** RTURIPARSED_F_XXX. */
69 uint32_t fFlags;
70
71 /** The length of the scheme. */
72 size_t cchScheme;
73
74 /** The offset into the string of the authority. */
75 size_t offAuthority;
76 /** The authority length.
77 * @remarks The authority component can be zero length, so to check whether
78 * it's there or not consult RTURIPARSED_F_HAVE_AUTHORITY. */
79 size_t cchAuthority;
80
81 /** The offset into the string of the path. */
82 size_t offPath;
83 /** The length of the path. */
84 size_t cchPath;
85
86 /** The offset into the string of the query. */
87 size_t offQuery;
88 /** The length of the query. */
89 size_t cchQuery;
90
91 /** The offset into the string of the fragment. */
92 size_t offFragment;
93 /** The length of the fragment. */
94 size_t cchFragment;
95
96 /** @name Authority subdivisions
97 * @{ */
98 /** If there is a userinfo part, this is the start of it. Otherwise it's the
99 * same as offAuthorityHost. */
100 size_t offAuthorityUsername;
101 /** The length of the username (zero if not present). */
102 size_t cchAuthorityUsername;
103 /** If there is a userinfo part containing a password, this is the start of it.
104 * Otherwise it's the same as offAuthorityHost. */
105 size_t offAuthorityPassword;
106 /** The length of the password (zero if not present). */
107 size_t cchAuthorityPassword;
108 /** The offset of the host part of the authority. */
109 size_t offAuthorityHost;
110 /** The length of the host part of the authority. */
111 size_t cchAuthorityHost;
112 /** The authority port number, UINT32_MAX if not present or empty. */
113 uint32_t uAuthorityPort;
114 /** @} */
115} RTURIPARSED;
116/** Pointer to a parsed URI. */
117typedef RTURIPARSED *PRTURIPARSED;
118/** Pointer to a const parsed URI. */
119typedef RTURIPARSED const *PCRTURIPARSED;
120
121/** @name RTURIPARSED_F_XXX - RTURIPARSED::fFlags
122 * @{ */
123/** Set if the URI contains escaped characters. */
124#define RTURIPARSED_F_CONTAINS_ESCAPED_CHARS UINT32_C(0x00000001)
125/** Set if the URI has an authority component. Necessary since the authority
126 * component can have a zero length. */
127#define RTURIPARSED_F_HAS_AUTHORITY UINT32_C(0x00000002)
128/** Set if there is a port component. */
129#define RTURIPARSED_F_HAS_PORT UINT32_C(0x00000004)
130/** @} */
131
132/**
133 * Parses a URI.
134 *
135 * @returns IPRT status code.
136 * @param pszUri The URI to parse.
137 * @param pParsed Where to return the details. This can be handed
138 * to the RTUriParsed* APIs for retriving
139 * information.
140 */
141RTDECL(int) RTUriParse(const char *pszUri, PRTURIPARSED pParsed);
142
143/**
144 * Extract the scheme out of a parsed URI.
145 *
146 * @returns The allocated scheme if the URI is valid, NULL otherwise. Must be free'd via RTStrFree().
147 * @param pszUri The URI passed to RTUriParse when producing the
148 * info in @a pParsed.
149 * @param pParsed Pointer to the RTUriParse output.
150 */
151RTDECL(char *) RTUriParsedScheme(const char *pszUri, PCRTURIPARSED pParsed);
152
153/**
154 * Extract the authority out of a parsed URI.
155 *
156 * @returns The allocated authority if the URI contains one, NULL otherwise. Must be free'd via RTStrFree().
157 * @param pszUri The URI passed to RTUriParse when producing the
158 * info in @a pParsed.
159 * @param pParsed Pointer to the RTUriParse output.
160 * @remarks The authority can have a zero length.
161 */
162RTDECL(char *) RTUriParsedAuthority(const char *pszUri, PCRTURIPARSED pParsed);
163
164/**
165 * Extract the username out of the authority component in a parsed URI.
166 *
167 * @returns The allocated username if the URI contains one, otherwise NULL. Must be free'd via RTStrFree().
168 * @param pszUri The URI passed to RTUriParse when producing the
169 * info in @a pParsed.
170 * @param pParsed Pointer to the RTUriParse output.
171 *
172 * @todo This may currently be returning NULL when it maybe would be more
173 * appropriate to return an empty string...
174 */
175RTDECL(char *) RTUriParsedAuthorityUsername(const char *pszUri, PCRTURIPARSED pParsed);
176
177/**
178 * Extract the password out of the authority component in a parsed URI.
179 *
180 * @returns The allocated password if the URI contains one, otherwise NULL. Must be free'd via RTStrFree().
181 * @param pszUri The URI passed to RTUriParse when producing the
182 * info in @a pParsed.
183 * @param pParsed Pointer to the RTUriParse output.
184 *
185 * @todo This may currently be returning NULL when it maybe would be more
186 * appropriate to return an empty string...
187 */
188RTDECL(char *) RTUriParsedAuthorityPassword(const char *pszUri, PCRTURIPARSED pParsed);
189
190/**
191 * Extract the host out of the authority component in a parsed URI.
192 *
193 * @returns The allocated host if the URI contains one, otherwise NULL. Must be free'd via RTStrFree().
194 * @param pszUri The URI passed to RTUriParse when producing the
195 * info in @a pParsed.
196 * @param pParsed Pointer to the RTUriParse output.
197 *
198 * @todo This may currently be returning NULL when it maybe would be more
199 * appropriate to return an empty string...
200 */
201RTDECL(char *) RTUriParsedAuthorityHost(const char *pszUri, PCRTURIPARSED pParsed);
202
203/**
204 * Extract the port number out of the authority component in a parsed URI.
205 *
206 * @returns The port number if the URI contains one, otherwise UINT32_MAX.
207 * @param pszUri The URI passed to RTUriParse when producing the
208 * info in @a pParsed.
209 * @param pParsed Pointer to the RTUriParse output.
210 */
211RTDECL(uint32_t) RTUriParsedAuthorityPort(const char *pszUri, PCRTURIPARSED pParsed);
212
213/**
214 * Extract the path out of a parsed URI.
215 *
216 * @returns The allocated path if the URI contains one, NULL otherwise. Must be free'd via RTStrFree().
217 * @param pszUri The URI passed to RTUriParse when producing the
218 * info in @a pParsed.
219 * @param pParsed Pointer to the RTUriParse output.
220 */
221RTDECL(char *) RTUriParsedPath(const char *pszUri, PCRTURIPARSED pParsed);
222
223/**
224 * Extract the query out of a parsed URI.
225 *
226 * @returns The allocated query if the URI contains one, NULL otherwise. Must be free'd via RTStrFree().
227 * @param pszUri The URI passed to RTUriParse when producing the
228 * info in @a pParsed.
229 * @param pParsed Pointer to the RTUriParse output.
230 */
231RTDECL(char *) RTUriParsedQuery(const char *pszUri, PCRTURIPARSED pParsed);
232
233/**
234 * Extract the fragment out of a parsed URI.
235 *
236 * @returns The allocated fragment if the URI contains one, NULL otherwise. Must be free'd via RTStrFree().
237 * @param pszUri The URI passed to RTUriParse when producing the
238 * info in @a pParsed.
239 * @param pParsed Pointer to the RTUriParse output.
240 */
241RTDECL(char *) RTUriParsedFragment(const char *pszUri, PCRTURIPARSED pParsed);
242
243
244
245/**
246 * Creates a generic URI.
247 *
248 * @returns The allocated URI on success, NULL otherwise. Must be free'd via RTStrFree().
249 * @param pszScheme The URI scheme.
250 * @param pszAuthority The authority part of the URI (optional).
251 * @param pszPath The path part of the URI (optional).
252 * @param pszQuery The query part of the URI (optional).
253 * @param pszFragment The fragment part of the URI (optional).
254 */
255RTDECL(char *) RTUriCreate(const char *pszScheme, const char *pszAuthority, const char *pszPath, const char *pszQuery,
256 const char *pszFragment);
257
258/**
259 * Check whether the given scheme matches that of the URI.
260 *
261 * This does not validate the URI, it just compares the scheme, no more, no
262 * less. Thus it's much faster than using RTUriParsedScheme.
263 *
264 * @returns true if the scheme match, false if not.
265 * @param pszUri The URI to check.
266 * @param pszScheme The scheme to compare with.
267 */
268RTDECL(bool) RTUriIsSchemeMatch(const char *pszUri, const char *pszScheme);
269
270/** @defgroup grp_rt_uri_file RTUriFile - Uri file parsing and creation
271 *
272 * Implements basic "file:" scheme support to the generic RTUri interface. This
273 * is partly documented in RFC-1738.
274 *
275 * @{
276 */
277
278/**
279 * Creates a file URI.
280 *
281 * The returned pointer must be freed using RTStrFree().
282 *
283 * @returns The new URI on success, NULL otherwise. Free With RTStrFree.
284 * @param pszPath The path to create an 'file://' URI for. This is
285 * assumed to be using the default path style of the
286 * system.
287 *
288 * @sa RTUriFileCreateEx, RTUriCreate
289 */
290RTDECL(char *) RTUriFileCreate(const char *pszPath);
291
292/**
293 * Creates an file URL for the given path.
294 *
295 * This API works like RTStrToUtf16Ex with regard to result allocation or
296 * buffering (i.e. it's a bit complicated but very flexible).
297 *
298 * @returns iprt status code.
299 * @param pszPath The path to convert to a file:// URL.
300 * @param fPathStyle The input path style, exactly one of
301 * RTPATH_STR_F_STYLE_HOST, RTPATH_STR_F_STYLE_DOS and
302 * RTPATH_STR_F_STYLE_UNIX. Must include iprt/path.h.
303 * @param ppszUri If cbUri is non-zero, this must either be pointing
304 * to pointer to a buffer of the specified size, or
305 * pointer to a NULL pointer. If *ppszUri is NULL or
306 * cbUri is zero a buffer of at least cbUri chars will
307 * be allocated to hold the URI. If a buffer was
308 * requested it must be freed using RTStrFree().
309 * @param cbUri The buffer size in bytes (includes terminator).
310 * @param pcchUri Where to store the length of the URI string,
311 * excluding the terminator. (Optional)
312 *
313 * This may be set under some error conditions,
314 * however, only for VERR_BUFFER_OVERFLOW and
315 * VERR_NO_STR_MEMORY will it contain a valid string
316 * length that can be used to resize the buffer.
317 * @sa RTUriCreate, RTUriFileCreate
318 */
319RTDECL(int) RTUriFileCreateEx(const char *pszPath, uint32_t fPathStyle, char **ppszUri, size_t cbUri, size_t *pcchUri);
320
321/**
322 * Returns the file path encoded in the file URI.
323 *
324 * This differs a quite a bit from RTUriParsedPath in that it tries to be
325 * compatible with URL produced by older windows version. This API is basically
326 * producing the same results as the PathCreateFromUrl API on Windows.
327 *
328 * @returns The path if the URI contains one, system default path style,
329 * otherwise NULL.
330 * @param pszUri The alleged 'file://' URI to extract the path from.
331 *
332 * @sa RTUriParsedPath, RTUriFilePathEx
333 */
334RTDECL(char *) RTUriFilePath(const char *pszUri);
335
336/**
337 * Queries the file path for the given file URI.
338 *
339 * This API works like RTStrToUtf16Ex with regard to result allocation or
340 * buffering (i.e. it's a bit complicated but very flexible).
341 *
342 * This differs a quite a bit from RTUriParsedPath in that it tries to be
343 * compatible with URL produced by older windows version. This API is basically
344 * producing the same results as the PathCreateFromUrl API on Windows.
345 *
346 * @returns IPRT status code.
347 * @retval VERR_URI_NOT_FILE_SCHEME if not file scheme.
348 *
349 * @param pszUri The alleged file:// URI to extract the path from.
350 * @param fPathStyle The output path style, exactly one of
351 * RTPATH_STR_F_STYLE_HOST, RTPATH_STR_F_STYLE_DOS and
352 * RTPATH_STR_F_STYLE_UNIX. Must include iprt/path.h.
353 * @param ppszPath If cbPath is non-zero, this must either be pointing
354 * to pointer to a buffer of the specified size, or
355 * pointer to a NULL pointer. If *ppszPath is NULL or
356 * cbPath is zero a buffer of at least cbPath chars
357 * will be allocated to hold the path. If a buffer was
358 * requested it must be freed using RTStrFree().
359 * @param cbPath The buffer size in bytes (includes terminator).
360 * @param pcchPath Where to store the length of the path string,
361 * excluding the terminator. (Optional)
362 *
363 * This may be set under some error conditions,
364 * however, only for VERR_BUFFER_OVERFLOW and
365 * VERR_NO_STR_MEMORY will it contain a valid string
366 * length that can be used to resize the buffer.
367 * @sa RTUriParsedPath, RTUriFilePath
368 */
369RTDECL(int) RTUriFilePathEx(const char *pszUri, uint32_t fPathStyle, char **ppszPath, size_t cbPath, size_t *pcchPath);
370
371/** @} */
372
373/** @} */
374
375RT_C_DECLS_END
376
377#endif /* !IPRT_INCLUDED_uri_h */
378
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette