include/vlc_url.h

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