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