vlc_url.h 6.74 KB
 Rémi Denis-Courmont committed Feb 27, 2006 1 2 3 /***************************************************************************** * vlc_url.h: URL related macros *****************************************************************************  Jean-Baptiste Kempf committed Nov 27, 2011 4  * Copyright (C) 2002-2006 VLC authors and VideoLAN  Rémi Denis-Courmont committed Feb 27, 2006 5 6 7 8 9  * $Id$ * * Authors: Christophe Massiot * Rémi Denis-Courmont *  Jean-Baptiste Kempf committed Nov 27, 2011 10 11 12  * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation; either version 2.1 of the License, or  Rémi Denis-Courmont committed Feb 27, 2006 13 14 15 16  * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of  Jean-Baptiste Kempf committed Nov 27, 2011 17 18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details.  Rémi Denis-Courmont committed Feb 27, 2006 19  *  Jean-Baptiste Kempf committed Nov 27, 2011 20 21 22  * You should have received a copy of the GNU Lesser General Public License * along with this program; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.  Rémi Denis-Courmont committed Feb 27, 2006 23 24  *****************************************************************************/  Rémi Denis-Courmont committed Aug 11, 2008 25 26 #ifndef VLC_URL_H # define VLC_URL_H  Rémi Denis-Courmont committed Feb 27, 2006 27   Jean-Paul Saman committed Aug 13, 2008 28 29 30 /** * \file * This file defines functions for manipulating URL in vlc  Rémi Denis-Courmont committed Nov 29, 2015 31 32 33 34 35 36 37 38 39 40 41 42 43 44  * * \ingroup strings * @{ */ /** * Converts local path to URL. * * Builds a URL representation from a local UTF-8 null-terminated file path. * * @param path file path * @param scheme URI scheme to use (default is auto: "file", "fd" or "smb") * @return a heap-allocated URI string on success * or NULL in case of error (errno will be set accordingly)  Jean-Paul Saman committed Aug 13, 2008 45  */  Rémi Denis-Courmont committed Nov 29, 2015 46 VLC_API char *vlc_path2uri(const char *path, const char *scheme) VLC_MALLOC;  Jean-Paul Saman committed Aug 13, 2008 47   Rémi Denis-Courmont committed Nov 29, 2015 48 49 50 51 52 53 54 55 56 57 58 /** * Converts a URI to a local path. * * Builds a local path (UTF-8-encoded null-terminated string) from a URI if * the URI scheme allows. * * @param url URI * @return a heap-allocated string or success * or NULL on error */ VLC_API char *vlc_uri2path(const char *url) VLC_MALLOC;  Rémi Denis-Courmont committed Aug 20, 2012 59   Rémi Denis-Courmont committed Nov 29, 2015 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 /** * Decodes an URI component in place. * * Decodes one null-terminated UTF-8 URI component to aa null-terminated UTF-8 * string in place. * * See also vlc_uri_decode_duplicate() for the not-in-place variant. * * \warning This function does NOT decode entire URIs. * URI can only be decoded (and encoded) one component at a time * (e.g. the host name, one directory, the file name). * Complete URIs are always "encoded" (or they are syntaxically invalid). * See IETF RFC3986, especially §2.4 for details. * * \note URI encoding is different from Javascript escaping. Especially, * white spaces and Unicode non-ASCII code points are encoded differently. * * \param str null-terminated component * \return str is returned on success. NULL if str was not properly encoded. */ VLC_API char *vlc_uri_decode(char *str); /** * Decodes an URI component. * * See also vlc_uri_decode() for the in-place variant. * * \return a heap-allocated string on success or NULL on error. */ VLC_API char *vlc_uri_decode_duplicate(const char *str) VLC_MALLOC; /** * Encodes a URI component. * * Substitutes URI-unsafe, URI delimiters and non-ASCII characters into their * URI-encoded URI-safe representation. See also IETF RFC3986 §2. * * @param str nul-terminated UTF-8 representation of the component. * @note Obviously, a URI containing nul bytes cannot be passed. * @return heap-allocated string, or NULL if out of memory. */ VLC_API char *vlc_uri_encode(const char *str) VLC_MALLOC;  Rémi Denis-Courmont committed Jul 17, 2016 103 104 105 106 107 108 109 110 111 112 113 114 115 116 /** * Composes an URI. * * Converts a decomposed/parsed URI structure (\ref vlc_url_t) into a * nul-terminated URI literal string. * * See also IETF RFC3986 section 5.3 for details. * * \bug URI fragments (i.e. HTML anchors) are not handled * * \return a heap-allocated nul-terminated string or NULL if out of memory */ VLC_API char *vlc_uri_compose(const vlc_url_t *) VLC_MALLOC;  Rémi Denis-Courmont committed Jul 17, 2016 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 /** * Resolves an URI reference. * * Resolves an URI reference relative to a base URI. * If the reference is an absolute URI, then this function simply returns a * copy of the URI reference. * * \param base base URI (as a nul-terminated string) * \param ref URI reference (also as a nul-terminated string) * * \return a heap-allocated nul-terminated string representing the resolved * absolute URI, or NULL if out of memory. */ VLC_API char *vlc_uri_resolve(const char *base, const char *ref) VLC_MALLOC;  Rémi Denis-Courmont committed Jul 12, 2016 132 133 134 135 136 137 138 139 140 141 142 143 144 /** * Fixes up a URI string. * * Attempts to convert a nul-terminated string into a syntactically valid URI. * If the string is, or may be, a syntactically valid URI, an exact copy is * returned. In any case, the result will only contain URI-safe and URI * delimiter characters (generic delimiters or sub-delimiters) and all percent * signs will be followed by two hexadecimal characters. * * @return a heap-allocated string, or NULL if on out of memory. */ VLC_API char *vlc_uri_fixup(const char *) VLC_MALLOC;  Rémi Denis-Courmont committed Dec 13, 2007 145 struct vlc_url_t  Rémi Denis-Courmont committed Feb 27, 2006 146 147 148 149 150 { char *psz_protocol; char *psz_username; char *psz_password; char *psz_host;  Rémi Denis-Courmont committed Aug 20, 2012 151  unsigned i_port;  Rémi Denis-Courmont committed Feb 27, 2006 152 153 154 155  char *psz_path; char *psz_option; char *psz_buffer; /* to be freed */  Thomas Guillem committed Dec 06, 2017 156  char *psz_pathbuffer; /* to be freed */  Rémi Denis-Courmont committed Dec 13, 2007 157 };  Rémi Denis-Courmont committed Feb 27, 2006 158   Rémi Denis-Courmont committed Oct 15, 2016 159 /**  Rémi Denis-Courmont committed Oct 19, 2016 160  * Parses an URI or IRI.  Rémi Denis-Courmont committed Oct 15, 2016 161  *  Rémi Denis-Courmont committed Oct 15, 2016 162 163 164 165 166 167 168 169 170  * Extracts the following parts from an URI string: * - scheme (i.e. protocol), * - user (deprecated), * - password (also deprecated), * - host name or IP address literal, * - port number, * - path (including the filename preceded by any and all directories) * - request parameters (excluding the leading question mark '?'). *  Rémi Denis-Courmont committed Oct 19, 2016 171 172 173 174  * The function accepts URIs, as well as UTF-8-encoded IRIs. For IRIs, the hier * part (specifically, the host name) is assumed to be an IDN and is decoded to * ASCII according, so it can be used for DNS resolution. If the host is an * IPv6 address literal, brackets are stripped.  Rémi Denis-Courmont committed Oct 15, 2016 175 176 177 178 179 180 181 182 183 184 185 186 187  * * Any missing part is set to nul. For historical reasons, the target structure * is always initialized, even if parsing the URI string fails. * * On error, errno is set to one of the following value: * - ENOMEM in case of memory allocation failure, * - EINVAL in case of syntax error in the input string. * * \bug The URI fragment is discarded if present. * * \note This function allocates memory. vlc_UrlClean() must be used free * associated the allocations, even if the function fails. *  Rémi Denis-Courmont committed Oct 15, 2016 188 189  * \param url structure of URL parts [OUT] * \param str nul-terminated URL string to split  Rémi Denis-Courmont committed Oct 15, 2016 190 191  * \retval 0 success * \retval -1 failure  Rémi Denis-Courmont committed Oct 15, 2016 192  */  Rémi Denis-Courmont committed Oct 15, 2016 193 VLC_API int vlc_UrlParse(vlc_url_t *url, const char *str);  Rémi Denis-Courmont committed Oct 15, 2016 194   Thomas Guillem committed Dec 06, 2017 195 196 197 198 199 200 201 202 /** * Parses an URI or IRI and fix up the path part. * * \see vlc_UrlParse * \see vlc_uri_fixup */ VLC_API int vlc_UrlParseFixup(vlc_url_t *url, const char *str);  Rémi Denis-Courmont committed Oct 15, 2016 203 204 205 206 207 208 /** * Releases resources allocated by vlc_UrlParse(). */ VLC_API void vlc_UrlClean(vlc_url_t *); /** @} */  Rémi Denis-Courmont committed Nov 29, 2015 209   Rémi Denis-Courmont committed Feb 27, 2006 210 #endif