VirtualBox

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

Last change on this file since 91991 was 82968, checked in by vboxsync, 5 years ago

Copyright year updates by scm.

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