VirtualBox

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

Last change on this file since 47006 was 39447, checked in by vboxsync, 13 years ago

Runtime: add Uniform Resource Identifier handling support

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.0 KB
Line 
1/** @file
2 * IPRT - Uniform Resource Identifier handling.
3 */
4
5/*
6 * Copyright (C) 2011 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_uri_h
27#define ___iprt_uri_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_uri RTUri - Uri parsing and creation
35 * URI parsing and creation based on RFC 3986.
36 * See http://datatracker.ietf.org/doc/rfc3986/ for the full specification.
37 * @note Currently it isn't the full specification implemented.
38 * @note Currently only some generic URI support and a minimum File(file:) URI
39 * support is implemented. Other specific scheme support, like html:, ldap:,
40 * data:, ..., is missing.
41 * @see grp_rt_uri_file
42 * @ingroup grp_rt
43 * @{
44 */
45
46/**
47 * Creates a generic URI.
48 *
49 * @returns the new URI on success, NULL otherwise.
50 * @param pszScheme The URI scheme.
51 * @param pszAuthority The authority part of the URI (optional).
52 * @param pszPath The path part of the URI (optional).
53 * @param pszQuery The query part of the URI (optional).
54 * @param pszFragment The fragment part of the URI (optional).
55 */
56RTR3DECL(char *) RTUriCreate(const char *pszScheme, const char *pszAuthority, const char *pszPath, const char *pszQuery, const char *pszFragment);
57
58/**
59 * Check an string for a specific URI scheme.
60 *
61 * @returns true if the scheme match, false if not.
62 * @param pszUri The URI to check.
63 * @param pszScheme The scheme to compare with.
64 */
65RTR3DECL(bool) RTUriHasScheme(const char *pszUri, const char *pszScheme);
66
67/**
68 * Extract the scheme out of an URI.
69 *
70 * @returns the scheme if the URI is valid, NULL otherwise.
71 * @param pszUri The URI to extract from.
72 */
73RTR3DECL(char *) RTUriScheme(const char *pszUri);
74
75/**
76 * Extract the authority out of an URI.
77 *
78 * @returns the authority if the URI contains one, NULL otherwise.
79 * @param pszUri The URI to extract from.
80 */
81RTR3DECL(char *) RTUriAuthority(const char *pszUri);
82
83/**
84 * Extract the path out of an URI.
85 *
86 * @returns the path if the URI contains one, NULL otherwise.
87 * @param pszUri The URI to extract from.
88 */
89RTR3DECL(char *) RTUriPath(const char *pszUri);
90
91/**
92 * Extract the query out of an URI.
93 *
94 * @returns the query if the URI contains one, NULL otherwise.
95 * @param pszUri The URI to extract from.
96 */
97RTR3DECL(char *) RTUriQuery(const char *pszUri);
98
99/**
100 * Extract the fragment out of an URI.
101 *
102 * @returns the fragment if the URI contains one, NULL otherwise.
103 * @param pszUri The URI to extract from.
104 */
105RTR3DECL(char *) RTUriFragment(const char *pszUri);
106
107/** @defgroup grp_rt_uri_file RTUriFile - Uri file parsing and creation
108 * Adds file: scheme support to the generic RTUri interface. This is partly
109 * documented in http://datatracker.ietf.org/doc/rfc1738/.
110 * @ingroup grp_rt_uri
111 * @{
112 */
113
114/** Auto detect in which format a path is returned. */
115#define URI_FILE_FORMAT_AUTO UINT32_C(0)
116/** Return a path in UNIX format style. */
117#define URI_FILE_FORMAT_UNIX UINT32_C(1)
118/** Return a path in Windows format style. */
119#define URI_FILE_FORMAT_WIN UINT32_C(2)
120
121/**
122 * Creates a file URI.
123 *
124 * @see RTUriCreate
125 *
126 * @returns the new URI on success, NULL otherwise.
127 * @param pszPath The path of the URI.
128 */
129RTR3DECL(char *) RTUriFileCreate(const char *pszPath);
130
131/**
132 * Returns the file path encoded in the URI.
133 *
134 * @returns the path if the URI contains one, NULL otherwise.
135 * @param pszUri The URI to extract from.
136 * @param uFormat In which format should the path returned.
137 */
138RTR3DECL(char *) RTUriFilePath(const char *pszUri, uint32_t uFormat);
139
140/**
141 * Returns the file path encoded in the URI, given a max string length.
142 *
143 * @returns the path if the URI contains one, NULL otherwise.
144 * @param pszUri The URI to extract from.
145 * @param uFormat In which format should the path returned.
146 * @param cbMax The max string length to inspect.
147 */
148RTR3DECL(char *) RTUriFileNPath(const char *pszUri, uint32_t uFormat, size_t cchMax);
149
150/** @} */
151
152/** @} */
153
154RT_C_DECLS_END
155
156#endif
157
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