uri.h revision cad7466b8b302baa2f6a79abb9b7da2912cf43db
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * IPRT - Uniform Resource Identifier handling.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Copyright (C) 2011 Oracle Corporation
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * available from http://www.virtualbox.org. This file is free software;
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * you can redistribute it and/or modify it under the terms of the GNU
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * General Public License (GPL) as published by the Free Software
10cdf5733351fdcd857d439ca32189e812f18682vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
df03c5ed15c9b5bf6d75fedcdf5057d3ffce8577vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
92a27575521748a392dcd1b996fce55b87411a00vboxsync * The contents of this file may alternatively be used under the terms
92a27575521748a392dcd1b996fce55b87411a00vboxsync * of the Common Development and Distribution License Version 1.0
92a27575521748a392dcd1b996fce55b87411a00vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
92a27575521748a392dcd1b996fce55b87411a00vboxsync * VirtualBox OSE distribution, in which case the provisions of the
92a27575521748a392dcd1b996fce55b87411a00vboxsync * CDDL are applicable instead of those of the GPL.
92a27575521748a392dcd1b996fce55b87411a00vboxsync * You may elect to license modified versions of this file under the
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * terms and conditions of either the GPL or the CDDL or both.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync/** @defgroup grp_rt_uri RTUri - Uri parsing and creation
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * URI parsing and creation based on RFC 3986.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * See http://datatracker.ietf.org/doc/rfc3986/ for the full specification.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @note Currently it isn't the full specification implemented.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @note Currently only some generic URI support and a minimum File(file:) URI
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * support is implemented. Other specific scheme support, like html:, ldap:,
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * data:, ..., is missing.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @see grp_rt_uri_file
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @ingroup grp_rt
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Creates a generic URI. The returned pointer must be freed
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * using RTStrFree().
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the new URI on success, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszScheme The URI scheme.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszAuthority The authority part of the URI (optional).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszPath The path part of the URI (optional).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszQuery The query part of the URI (optional).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszFragment The fragment part of the URI (optional).
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(char *) RTUriCreate(const char *pszScheme, const char *pszAuthority, const char *pszPath, const char *pszQuery, const char *pszFragment);
c9dbeac49601b9e10f0941b1c8e4f97853d4fab5vboxsync * Check an string for a specific URI scheme.
c9dbeac49601b9e10f0941b1c8e4f97853d4fab5vboxsync * @returns true if the scheme match, false if not.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to check.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszScheme The scheme to compare with.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(bool) RTUriHasScheme(const char *pszUri, const char *pszScheme);
b8908d384db2324f04a2f68a13e67ea32ebf609avboxsync * Extract the scheme out of an URI.
fadf3b452e8a0c58afb43fd56f445fa8583d9d0cvboxsync * @returns the scheme if the URI is valid, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Extract the authority out of an URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the authority if the URI contains one, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(char *) RTUriAuthority(const char *pszUri);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Extract the path out of an URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the path if the URI contains one, NULL otherwise.
583008eb7eb336e25724785bc04833bd33271fd6vboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Extract the query out of an URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the query if the URI contains one, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Extract the fragment out of an URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the fragment if the URI contains one, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync/** @defgroup grp_rt_uri_file RTUriFile - Uri file parsing and creation
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Adds file: scheme support to the generic RTUri interface. This is partly
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * documented in http://datatracker.ietf.org/doc/rfc1738/.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @ingroup grp_rt_uri
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync/** Auto detect in which format a path is returned. */
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync/** Return a path in UNIX format style. */
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync/** Return a path in Windows format style. */
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Creates a file URI. The returned pointer must be freed
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * using RTStrFree().
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @see RTUriCreate
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the new URI on success, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszPath The path of the URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(char *) RTUriFileCreate(const char *pszPath);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Returns the file path encoded in the URI.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the path if the URI contains one, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param uFormat In which format should the path returned.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(char *) RTUriFilePath(const char *pszUri, uint32_t uFormat);
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * Returns the file path encoded in the URI, given a max string length.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @returns the path if the URI contains one, NULL otherwise.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param pszUri The URI to extract from.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param uFormat In which format should the path returned.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsync * @param cbMax The max string length to inspect.
db3dbd0ed7eb69f804a8921fa23a1267ea01f46evboxsyncRTR3DECL(char *) RTUriFileNPath(const char *pszUri, uint32_t uFormat, size_t cchMax);