Uniform Resource Locator (URL)

Collaboration diagram for Uniform Resource Locator (URL):

Files
file	vlc_url.h

Data Structures
struct	vlc_url_t

Functions
VLC_EXPORT char *	vlc_path2uri (const char *path, const char *scheme)
	Converts local path to URL. More...
VLC_EXPORT char *	vlc_uri2path (const char *url)
	Converts a URI to a local path. More...
VLC_EXPORT char *	vlc_uri_decode (char *str)
	Decodes an URI component in place. More...
VLC_EXPORT char *	vlc_uri_decode_duplicate (const char *str)
	Decodes an URI component. More...
VLC_EXPORT char *	vlc_uri_encode (const char *str)
	Encodes a URI component. More...
VLC_EXPORT char *	vlc_uri_compose (const vlc_url_t *)
	Composes an URI. More...
VLC_EXPORT char *	vlc_uri_resolve (const char *base, const char *ref)
	Resolves an URI reference. More...
VLC_EXPORT char *	vlc_uri_fixup (const char *)
	Fixes up a URI string. More...
VLC_EXPORT int	vlc_UrlParse (vlc_url_t *url, const char *str)
	Parses an URI or IRI. More...
VLC_EXPORT int	vlc_UrlParseFixup (vlc_url_t *url, const char *str)
	Parses an URI or IRI and fix up the path part. More...
VLC_EXPORT void	vlc_UrlClean (vlc_url_t *)
	Releases resources allocated by vlc_UrlParse(). More...

Detailed Description

Function Documentation

vlc_path2uri()

VLC_EXPORT char* vlc_path2uri	(	const char *	path,
		const char *	scheme
	)

Converts local path to URL.

Builds a URL representation from a local UTF-8 null-terminated file path.

Parameters

path	file path
scheme	URI scheme to use (default is auto: "file", "fd" or "smb")

Returns

a heap-allocated URI string on success or NULL in case of error (errno will be set accordingly)

References asprintf(), DIR_SEP, DIR_SEP_CHAR, encode_URI_bytes(), p, strdup(), unlikely, vlc_getcwd(), and vlc_path2uri().

Referenced by GetDefaultArtUri(), GetFilenames(), GetVarSlaves(), input_FindArtInCache(), input_SaveArt(), input_SubtitleFile2Uri(), InputGetExtraFilesPattern(), subtitles_Detect(), system_Configure(), system_ConfigureDbus(), vlc_path2uri(), and vlm_ControlMediaInstanceStart().

vlc_uri2path()

VLC_EXPORT char* vlc_uri2path

(

const char *

url

)

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.

Parameters

url

URI

Returns

a heap-allocated string or success or NULL on error

References asprintf(), p, strdup(), strndup(), unlikely, and vlc_uri_decode().

Referenced by get_path(), input_item_WriteMeta(), and subtitles_Detect().

vlc_uri_compose()

VLC_EXPORT char* vlc_uri_compose

(

const vlc_url_t *

)

Composes an URI.

Converts a decomposed/parsed URI structure (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

Returns

a heap-allocated nul-terminated string or NULL if out of memory

References vlc_memstream::error, vlc_url_t::i_port, vlc_url_t::psz_fragment, vlc_url_t::psz_host, vlc_url_t::psz_option, vlc_url_t::psz_password, vlc_url_t::psz_path, vlc_url_t::psz_protocol, vlc_url_t::psz_username, vlc_memstream::stream, unlikely, vlc_memstream_close(), vlc_memstream_open(), vlc_memstream_printf(), vlc_memstream_putc(), vlc_memstream_puts(), vlc_memstream_write(), and vlc_uri_encode().

Referenced by vlc_getProxyUrl(), and vlc_uri_resolve().

vlc_uri_decode()

VLC_EXPORT char* vlc_uri_decode

(

char *

str

)

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.

Parameters

str	null-terminated component

Returns

str is returned on success. NULL if str was not properly encoded.

Referenced by input_item_SetURI(), mrl_FragmentSplit(), vlc_uri2path(), vlc_uri_decode_duplicate(), and vlc_UrlParseInner().

vlc_uri_decode_duplicate()

VLC_EXPORT char* vlc_uri_decode_duplicate

(

const char *

str

)

Decodes an URI component.

See also vlc_uri_decode() for the in-place variant.

Returns

a heap-allocated string on success or NULL on error.

References strdup(), and vlc_uri_decode().

Referenced by find_closest_path(), and vlc_credential_store().

vlc_uri_encode()

VLC_EXPORT char* vlc_uri_encode

(

const char *

str

)

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.

Parameters

str	nul-terminated UTF-8 representation of the component.

Note

Obviously, a URI containing nul bytes cannot be passed.

Returns

heap-allocated string, or NULL if out of memory.

References encode_URI_bytes(), and likely.

Referenced by vlc_uri_compose().

vlc_uri_fixup()

VLC_EXPORT char* vlc_uri_fixup

(

const char *

)

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.

Returns

a heap-allocated string, or NULL if on out of memory.

References isurialnum(), isurihex(), p, vlc_memstream::stream, vlc_memstream_close(), vlc_memstream_open(), vlc_memstream_putc(), vlc_memstream_write(), and vlc_uri_putc().

Referenced by vlc_http_res_get_redirect().

vlc_uri_resolve()

VLC_EXPORT char* vlc_uri_resolve	(	const char *	base,
		const char *	ref
	)

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.

Parameters

base	base URI (as a nul-terminated string)
ref	URI reference (also as a nul-terminated string)

Returns

a heap-allocated nul-terminated string representing the resolved absolute URI, or NULL if out of memory.

References vlc_memstream::error, vlc_url_t::i_port, vlc_url_t::psz_host, vlc_url_t::psz_option, vlc_url_t::psz_password, vlc_url_t::psz_path, vlc_url_t::psz_protocol, vlc_url_t::psz_username, strdup(), unlikely, vlc_uri_compose(), vlc_uri_merge_paths(), vlc_uri_remove_dot_segments(), vlc_UrlClean(), and vlc_UrlParse().

Referenced by vlc_http_res_get_redirect().

vlc_UrlClean()

VLC_EXPORT void vlc_UrlClean

(

vlc_url_t *

)

Releases resources allocated by vlc_UrlParse().

vlc_UrlParse()

VLC_EXPORT int vlc_UrlParse	(	vlc_url_t *	url,
		const char *	str
	)

Parses an URI or IRI.

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 '?').

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.

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.

Parameters

url	structure of URL parts [OUT]
str	nul-terminated URL string to split

Return values

0	success
-1	failure

References vlc_url_t::psz_path, vlc_uri_path_validate(), and vlc_UrlParseInner().

Referenced by GetVarSlaves(), input_item_SetURI(), Open(), vlc_getProxyUrl(), vlc_http_outfile_create(), vlc_http_request(), vlc_http_res_init(), vlc_https_connect_proxy(), and vlc_uri_resolve().

vlc_UrlParseFixup()

VLC_EXPORT int vlc_UrlParseFixup	(	vlc_url_t *	url,
		const char *	str
	)

Parses an URI or IRI and fix up the path part.

See also

vlc_UrlParse

vlc_uri_fixup

References vlc_url_t::psz_path, vlc_url_t::psz_pathbuffer, vlc_uri_component_validate(), vlc_uri_fixup_inner(), vlc_uri_path_validate(), and vlc_UrlParseInner().