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