VirtualBox

Changeset 57723 in vbox for trunk/include


Ignore:
Timestamp:
Sep 11, 2015 8:02:15 PM (10 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
102638
Message:

RTUri: Reworked the API to a one time parsing and make sure we get UTF-8 clean strings from it.

Location:
trunk/include/iprt
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/err.h

    r57720 r57723  
    25062506/** Invalid port number.  */
    25072507#define VERR_URI_INVALID_PORT_NUMBER                (-24603)
     2508/** Invalid escape sequence.  */
     2509#define VERR_URI_INVALID_ESCAPE_SEQ                 (-24604)
     2510/** Escape URI char decodes as zero (the C string terminator). */
     2511#define VERR_URI_ESCAPED_ZERO                       (-24605)
     2512/** Escaped URI characters does not decode to valid UTF-8. */
     2513#define VERR_URI_ESCAPED_CHARS_NOT_VALID_UTF8       (-24606)
     2514/** Escaped URI character is not a valid UTF-8 lead byte. */
     2515#define VERR_URI_INVALID_ESCAPED_UTF8_LEAD_BYTE     (-24607)
     2516/** Escaped URI character sequence with invalid UTF-8 continutation byte. */
     2517#define VERR_URI_INVALID_ESCAPED_UTF8_CONTINUATION_BYTE (-24608)
     2518/** Missing UTF-8 continutation in escaped URI character sequence. */
     2519#define VERR_URI_MISSING_UTF8_CONTINUATION_BYTE     (-24609)
    25082520/** @} */
    25092521

  • trunk/include/iprt/mangling.h

    r57720 r57723  
    18581858# define RTUdpWrite                                     RT_MANGLER(RTUdpWrite)
    18591859# define RTUniFree                                      RT_MANGLER(RTUniFree)
    1860 # define RTUriAuthority                                 RT_MANGLER(RTUriAuthority)
    1861 # define RTUriAuthorityPassword                         RT_MANGLER(RTUriAuthorityPassword)
    1862 # define RTUriAuthorityPort                             RT_MANGLER(RTUriAuthorityPort)
    1863 # define RTUriAuthorityUsername                         RT_MANGLER(RTUriAuthorityUsername)
    18641860# define RTUriCreate                                    RT_MANGLER(RTUriCreate)
    18651861# define RTUriFileCreate                                RT_MANGLER(RTUriFileCreate)
    18661862# define RTUriFileNPath                                 RT_MANGLER(RTUriFileNPath)
    18671863# define RTUriFilePath                                  RT_MANGLER(RTUriFilePath)
    1868 # define RTUriFragment                                  RT_MANGLER(RTUriFragment)
    1869 # define RTUriHasScheme                                 RT_MANGLER(RTUriHasScheme)
     1864# define RTUriParse                                     RT_MANGLER(RTUriParse)
     1865# define RTUriParsedAuthority                           RT_MANGLER(RTUriParsedAuthority)
     1866# define RTUriParsedAuthorityHost                       RT_MANGLER(RTUriParsedAuthorityHost)
     1867# define RTUriParsedAuthorityPassword                   RT_MANGLER(RTUriParsedAuthorityPassword)
     1868# define RTUriParsedAuthorityPort                       RT_MANGLER(RTUriParsedAuthorityPort)
     1869# define RTUriParsedAuthorityUsername                   RT_MANGLER(RTUriParsedAuthorityUsername)
     1870# define RTUriParsedFragment                            RT_MANGLER(RTUriParsedFragment)
     1871# define RTUriParsedPath                                RT_MANGLER(RTUriParsedPath)
     1872# define RTUriParsedScheme                              RT_MANGLER(RTUriParsedScheme)
     1873# define RTUriParsedQuery                               RT_MANGLER(RTUriParsedQuery)
     1874# define RTUriIsSchemeMatch                             RT_MANGLER(RTUriIsSchemeMatch)
    18701875# define RTUriPath                                      RT_MANGLER(RTUriPath)
    1871 # define RTUriQuery                                     RT_MANGLER(RTUriQuery)
    1872 # define RTUriScheme                                    RT_MANGLER(RTUriScheme)
    18731876# define RTUtf16AllocTag                                RT_MANGLER(RTUtf16AllocTag)
    18741877# define RTUtf16CalcLatin1Len                           RT_MANGLER(RTUtf16CalcLatin1Len)

  • trunk/include/iprt/uri.h

    r57720 r57723  
    3333
    3434/** @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
     35 *
     36 * URI parsing and creation based on RFC-3986.
     37 *
     38 * @remarks The whole specification isn't implemented and we only provide scheme
     39 *          specific special APIs for "file://".
     40 *
    4241 * @ingroup grp_rt
    4342 * @{
    4443 */
    4544
    46 /**
    47  * Creates a generic URI. The returned pointer must be freed
    48  * using RTStrFree().
     45
     46/**
     47 * Parsed URI.
     48 *
     49 * @remarks This structure is subject to change.
     50 */
     51typedef struct RTURIPARSED
     52{
     53    /** Magic value (for internal use only). */
     54    uint32_t    u32Magic;
     55    /** RTURIPARSED_F_XXX. */
     56    uint32_t    fFlags;
     57
     58    /** The length of the scheme. */
     59    size_t      cchScheme;
     60
     61    /** The offset into the string of the authority. */
     62    size_t      offAuthority;
     63    /** The authority length.
     64     * @remarks The authority component can be zero length, so to check whether
     65     *          it's there or not consult RTURIPARSED_F_HAVE_AUTHORITY. */
     66    size_t      cchAuthority;
     67
     68    /** The offset into the string of the path. */
     69    size_t      offPath;
     70    /** The length of the path. */
     71    size_t      cchPath;
     72
     73    /** The offset into the string of the query. */
     74    size_t      offQuery;
     75    /** The length of the query. */
     76    size_t      cchQuery;
     77
     78    /** The offset into the string of the fragment. */
     79    size_t      offFragment;
     80    /** The length of the fragment. */
     81    size_t      cchFragment;
     82
     83    /** @name Authority subdivisions
     84     * @{ */
     85    /** If there is a userinfo part, this is the start of it. Otherwise it's the
     86     * same as offAuthorityHost. */
     87    size_t      offAuthorityUsername;
     88    /** The length of the username (zero if not present). */
     89    size_t      cchAuthorityUsername;
     90    /** If there is a userinfo part containing a password, this is the start of it.
     91     * Otherwise it's the same as offAuthorityHost. */
     92    size_t      offAuthorityPassword;
     93    /** The length of the password (zero if not present). */
     94    size_t      cchAuthorityPassword;
     95    /** The offset of the host part of the authority. */
     96    size_t      offAuthorityHost;
     97    /** The length of the host part of the authority. */
     98    size_t      cchAuthorityHost;
     99    /** The authority port number, UINT32_MAX if not present. */
     100    uint32_t    uAuthorityPort;
     101    /** @} */
     102} RTURIPARSED;
     103/** Pointer to a parsed URI. */
     104typedef RTURIPARSED *PRTURIPARSED;
     105/** Pointer to a const parsed URI. */
     106typedef RTURIPARSED const *PCRTURIPARSED;
     107
     108/** @name  RTURIPARSED_F_XXX - RTURIPARSED::fFlags
     109 * @{  */
     110/** Set if the URI contains escaped characters. */
     111#define RTURIPARSED_F_CONTAINS_ESCAPED_CHARS        UINT32_C(0x00000001)
     112/** Set if the URI have an authority component.  Necessary since the authority
     113 * component can have a zero length. */
     114#define RTURIPARSED_F_HAVE_AUTHORITY                UINT32_C(0x00000002)
     115/** @} */
     116
     117/**
     118 * Parses a URI.
     119 *
     120 * @returns IPRT status code.
     121 * @param   pszUri              The URI to parse.
     122 * @param   pParsed             Where to return the details.  This can be handed
     123 *                              to the RTUriParsed* APIs for retriving
     124 *                              information.
     125 */
     126RTDECL(int) RTUriParse(const char *pszUri, PRTURIPARSED pParsed);
     127
     128/**
     129 * Extract the scheme out of a parsed URI.
     130 *
     131 * @returns the scheme if the URI is valid, NULL otherwise.
     132 * @param   pszUri              The URI passed to RTUriParse when producing the
     133 *                              info in @a pParsed.
     134 * @param   pParsed             Pointer to the RTUriParse output.
     135 */
     136RTDECL(char *) RTUriParsedScheme(const char *pszUri, PCRTURIPARSED pParsed);
     137
     138/**
     139 * Extract the authority out of a parsed URI.
     140 *
     141 * @returns the authority if the URI contains one, NULL otherwise.
     142 * @param   pszUri              The URI passed to RTUriParse when producing the
     143 *                              info in @a pParsed.
     144 * @param   pParsed             Pointer to the RTUriParse output.
     145 * @remarks The authority can have a zero length.
     146 */
     147RTDECL(char *) RTUriParsedAuthority(const char *pszUri, PCRTURIPARSED pParsed);
     148
     149/**
     150 * Extract the username out of the authority component in a parsed URI.
     151 *
     152 * @returns The username if the URI contains one, otherwise NULL.
     153 * @param   pszUri              The URI passed to RTUriParse when producing the
     154 *                              info in @a pParsed.
     155 * @param   pParsed             Pointer to the RTUriParse output.
     156 *
     157 * @todo    This may currently be returning NULL when it maybe would be more
     158 *          appropriate to return an empty string...
     159 */
     160RTDECL(char *) RTUriParsedAuthorityUsername(const char *pszUri, PCRTURIPARSED pParsed);
     161
     162/**
     163 * Extract the password out of the authority component in a parsed URI.
     164 *
     165 * @returns The password if the URI contains one, otherwise NULL.
     166 * @param   pszUri              The URI passed to RTUriParse when producing the
     167 *                              info in @a pParsed.
     168 * @param   pParsed             Pointer to the RTUriParse output.
     169 *
     170 * @todo    This may currently be returning NULL when it maybe would be more
     171 *          appropriate to return an empty string...
     172 */
     173RTDECL(char *) RTUriParsedAuthorityPassword(const char *pszUri, PCRTURIPARSED pParsed);
     174
     175/**
     176 * Extract the host out of the authority component in a parsed URI.
     177 *
     178 * @returns The host if the URI contains one, otherwise NULL.
     179 * @param   pszUri              The URI passed to RTUriParse when producing the
     180 *                              info in @a pParsed.
     181 * @param   pParsed             Pointer to the RTUriParse output.
     182 *
     183 * @todo    This may currently be returning NULL when it maybe would be more
     184 *          appropriate to return an empty string...
     185 */
     186RTDECL(char *) RTUriParsedAuthorityHost(const char *pszUri, PCRTURIPARSED pParsed);
     187
     188/**
     189 * Extract the port number out of the authority component in a parsed URI.
     190 *
     191 * @returns The port number if the URI contains one, otherwise UINT32_MAX.
     192 * @param   pszUri              The URI passed to RTUriParse when producing the
     193 *                              info in @a pParsed.
     194 * @param   pParsed             Pointer to the RTUriParse output.
     195 */
     196RTDECL(uint32_t) RTUriParsedAuthorityPort(const char *pszUri, PCRTURIPARSED pParsed);
     197
     198/**
     199 * Extract the path out of a parsed URI.
     200 *
     201 * @returns the path if the URI contains one, NULL otherwise.
     202 * @param   pszUri              The URI passed to RTUriParse when producing the
     203 *                              info in @a pParsed.
     204 * @param   pParsed             Pointer to the RTUriParse output.
     205 */
     206RTDECL(char *) RTUriParsedPath(const char *pszUri, PCRTURIPARSED pParsed);
     207
     208/**
     209 * Extract the query out of a parsed URI.
     210 *
     211 * @returns the query if the URI contains one, NULL otherwise.
     212 * @param   pszUri              The URI passed to RTUriParse when producing the
     213 *                              info in @a pParsed.
     214 * @param   pParsed             Pointer to the RTUriParse output.
     215 */
     216RTDECL(char *) RTUriParsedQuery(const char *pszUri, PCRTURIPARSED pParsed);
     217
     218/**
     219 * Extract the fragment out of a parsed URI.
     220 *
     221 * @returns the fragment if the URI contains one, NULL otherwise.
     222 * @param   pszUri              The URI passed to RTUriParse when producing the
     223 *                              info in @a pParsed.
     224 * @param   pParsed             Pointer to the RTUriParse output.
     225 */
     226RTDECL(char *) RTUriParsedFragment(const char *pszUri, PCRTURIPARSED pParsed);
     227
     228
     229
     230/**
     231 * Creates a generic URI.
     232 *
     233 * The returned pointer must be freed using RTStrFree().
    49234 *
    50235 * @returns the new URI on success, NULL otherwise.
    … …  
    55240 * @param   pszFragment         The fragment part of the URI (optional).
    56241 */
    57 RTR3DECL(char *) RTUriCreate(const char *pszScheme, const char *pszAuthority, const char *pszPath, const char *pszQuery,
    58                              const char *pszFragment);
    59 
    60 /**
    61  * Check an string for a specific URI scheme.
     242RTDECL(char *) RTUriCreate(const char *pszScheme, const char *pszAuthority, const char *pszPath, const char *pszQuery,
     243                           const char *pszFragment);
     244
     245/**
     246 * Check whether the given scheme matches that of the URI.
     247 *
     248 * This does not validate the URI, it just compares the scheme, no more, no
     249 * less.  Thus it's much faster than using RTUriParsedScheme.
    62250 *
    63251 * @returns true if the scheme match, false if not.
    … …  
    65253 * @param   pszScheme           The scheme to compare with.
    66254 */
    67 RTR3DECL(bool)   RTUriHasScheme(const char *pszUri, const char *pszScheme);
    68 
    69 /**
    70  * Extract the scheme out of an URI.
    71  *
    72  * @returns the scheme if the URI is valid, NULL otherwise.
    73  * @param   pszUri              The URI to extract from.
    74  */
    75 RTR3DECL(char *) RTUriScheme(const char *pszUri);
    76 
    77 /**
    78  * Extract the authority out of an URI.
    79  *
    80  * @returns the authority if the URI contains one, NULL otherwise.
    81  * @param   pszUri              The URI to extract from.
    82  * @remarks The authority can have a zero length.
    83  */
    84 RTR3DECL(char *) RTUriAuthority(const char *pszUri);
    85 
    86 /**
    87  * Extract the username out of the authority component in an URI.
    88  *
    89  * @returns The username if the URI contains one, otherwise NULL.
    90  * @param   pszUri              The URI to extract from.
    91  */
    92 RTR3DECL(char *) RTUriAuthorityUsername(const char *pszUri);
    93 
    94 /**
    95  * Extract the password out of the authority component in an URI.
    96  *
    97  * @returns The password if the URI contains one, otherwise NULL.
    98  * @param   pszUri              The URI to extract from.
    99  */
    100 RTR3DECL(char *) RTUriAuthorityPassword(const char *pszUri);
    101 
    102 /**
    103  * Extract the port number out of the authority component in an URI.
    104  *
    105  * @returns The port number if the URI contains one, otherwise UINT32_MAX.
    106  * @param   pszUri              The URI to extract from.
    107  */
    108 RTR3DECL(uint32_t) RTUriAuthorityPort(const char *pszUri);
     255RTDECL(bool)   RTUriIsSchemeMatch(const char *pszUri, const char *pszScheme);
    109256
    110257/**
    … …  
    113260 * @returns the path if the URI contains one, NULL otherwise.
    114261 * @param   pszUri              The URI to extract from.
    115  */
    116 RTR3DECL(char *) RTUriPath(const char *pszUri);
    117 
    118 /**
    119  * Extract the query out of an URI.
    120  *
    121  * @returns the query if the URI contains one, NULL otherwise.
    122  * @param   pszUri              The URI to extract from.
    123  */
    124 RTR3DECL(char *) RTUriQuery(const char *pszUri);
    125 
    126 /**
    127  * Extract the fragment out of an URI.
    128  *
    129  * @returns the fragment if the URI contains one, NULL otherwise.
    130  * @param   pszUri              The URI to extract from.
    131  */
    132 RTR3DECL(char *) RTUriFragment(const char *pszUri);
     262 * @deprecated
     263 */
     264RTDECL(char *) RTUriPath(const char *pszUri);
     265
    133266
    134267/** @defgroup grp_rt_uri_file   RTUriFile - Uri file parsing and creation
    135  * Adds file: scheme support to the generic RTUri interface. This is partly
    136  * documented in http://datatracker.ietf.org/doc/rfc1738/.
     268 *
     269 * Implements basic "file:" scheme support to the generic RTUri interface.  This
     270 * is partly documented in RFC-1738.
     271 *
    137272 * @{
    138273 */
    139274
    140 /** Auto detect in which format a path is returned. */
     275/** Return the host format. */
    141276#define URI_FILE_FORMAT_AUTO  UINT32_C(0)
    142277/** Return a path in UNIX format style. */
    … …  
    155290 * @param   pszPath             The path of the URI.
    156291 */
    157 RTR3DECL(char *) RTUriFileCreate(const char *pszPath);
     292RTDECL(char *) RTUriFileCreate(const char *pszPath);
    158293
    159294/**
    … …  
    164299 * @param   uFormat             In which format should the path returned.
    165300 */
    166 RTR3DECL(char *) RTUriFilePath(const char *pszUri, uint32_t uFormat);
     301RTDECL(char *) RTUriFilePath(const char *pszUri, uint32_t uFormat);
    167302
    168303/**
    … …  
    174309 * @param   cbMax               The max string length to inspect.
    175310 */
    176 RTR3DECL(char *) RTUriFileNPath(const char *pszUri, uint32_t uFormat, size_t cchMax);
     311RTDECL(char *) RTUriFileNPath(const char *pszUri, uint32_t uFormat, size_t cchMax);
    177312
    178313/** @} */
Note: See TracChangeset for help on using the changeset viewer.

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