vlc_url.h 6.74 KB
Newer Older
1 2 3
/*****************************************************************************
 * vlc_url.h: URL related macros
 *****************************************************************************
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
4
 * Copyright (C) 2002-2006 VLC authors and VideoLAN
5 6 7 8 9
 * $Id$
 *
 * Authors: Christophe Massiot <massiot@via.ecp.fr>
 *          Rémi Denis-Courmont <rem # videolan.org>
 *
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
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
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's avatar
Jean-Baptiste Kempf committed
17 18
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
19
 *
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
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.
23 24
 *****************************************************************************/

25 26
#ifndef VLC_URL_H
# define VLC_URL_H
27

28 29 30
/**
 * \file
 * This file defines functions for manipulating URL in vlc
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)
45
 */
46
VLC_API char *vlc_path2uri(const char *path, const char *scheme) VLC_MALLOC;
47

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;
59

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 <b>This function does NOT decode entire URIs.</b>
 * 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 <b>different</b> 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;

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;

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;

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;

145
struct vlc_url_t
146 147 148 149 150
{
    char *psz_protocol;
    char *psz_username;
    char *psz_password;
    char *psz_host;
151
    unsigned i_port;
152 153 154 155
    char *psz_path;
    char *psz_option;

    char *psz_buffer; /* to be freed */
156
    char *psz_pathbuffer; /* to be freed */
157
};
158

159
/**
160
 * Parses an URI or IRI.
161
 *
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 '?').
 *
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.
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.
 *
188 189
 * \param url structure of URL parts [OUT]
 * \param str nul-terminated URL string to split
190 191
 * \retval 0 success
 * \retval -1 failure
192
 */
193
VLC_API int vlc_UrlParse(vlc_url_t *url, const char *str);
194

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);

203 204 205 206 207 208
/**
 * Releases resources allocated by vlc_UrlParse().
 */
VLC_API void vlc_UrlClean(vlc_url_t *);

/** @} */
209

210
#endif