Messages

HTTP messages, header formatting and parsing. More...

Collaboration diagram for Messages:

Files
file	message.h

Functions
struct vlc_http_msg *	vlc_http_req_create (const char *method, const char *scheme, const char *authority, const char *path) VLC_USED
	Creates an HTTP request.
struct vlc_http_msg *	vlc_http_resp_create (unsigned status) VLC_USED
	Creates an HTTP response.
void	vlc_http_msg_destroy (struct vlc_http_msg *)
	Destroys an HTTP message.
int	vlc_http_msg_add_header (struct vlc_http_msg *, const char *name, const char *fmt,...) VLC_FORMAT(3
	Formats a header field.
int char *	vlc_http_authority (const char *host, unsigned port)
	Formats an authority.
int	vlc_http_msg_add_agent (struct vlc_http_msg *, const char *)
	Sets the agent field.
const char *	vlc_http_msg_get_agent (const struct vlc_http_msg *)
	Gets the agent field.
time_t	vlc_http_msg_get_time (const struct vlc_http_msg *msg, const char *name)
	Parses a timestamp header field.
int	vlc_http_msg_add_time (struct vlc_http_msg *msg, const char *name, const time_t *t)
	Adds a timestamp header field.
int	vlc_http_msg_add_atime (struct vlc_http_msg *)
	Adds a Date header field.
time_t	vlc_http_msg_get_atime (const struct vlc_http_msg *)
	Gets message date.
time_t	vlc_http_msg_get_mtime (const struct vlc_http_msg *)
	Gets resource date.
unsigned	vlc_http_msg_get_retry_after (const struct vlc_http_msg *)
	Gets retry timeout.
void	vlc_http_msg_get_cookies (const struct vlc_http_msg *, struct vlc_http_cookie_jar_t *, const char *host, const char *path)
int	vlc_http_msg_add_cookies (struct vlc_http_msg *, struct vlc_http_cookie_jar_t *)
char *	vlc_http_msg_get_basic_realm (const struct vlc_http_msg *)
int	vlc_http_msg_add_creds_basic (struct vlc_http_msg *msg, bool proxy, const char *username, const char *password)
	Adds Basic credentials.
const char *	vlc_http_msg_get_header (const struct vlc_http_msg *, const char *name)
	Looks up an header field.
int	vlc_http_msg_get_status (const struct vlc_http_msg *m)
	Gets response status code.
const char *	vlc_http_msg_get_method (const struct vlc_http_msg *)
	Gets request method.
const char *	vlc_http_msg_get_scheme (const struct vlc_http_msg *)
	Gets request scheme.
const char *	vlc_http_msg_get_authority (const struct vlc_http_msg *)
	Gets request authority.
const char *	vlc_http_msg_get_path (const struct vlc_http_msg *)
	Gets request absolute path.
const char *	vlc_http_msg_get_token (const struct vlc_http_msg *msg, const char *field, const char *token)
	Looks up a token in a header field.
const char *	vlc_http_next_token (const char *)
	Finds next token.
uintmax_t	vlc_http_msg_get_size (const struct vlc_http_msg *)
	Gets HTTP payload length.
struct vlc_http_msg *	vlc_http_msg_iterate (struct vlc_http_msg *) VLC_USED
	Gets next response headers.
struct vlc_http_msg *	vlc_http_msg_get_final (struct vlc_http_msg *) VLC_USED
	Gets final response headers.
block_t *	vlc_http_msg_read (struct vlc_http_msg *) VLC_USED
	Receives HTTP data.
int	vlc_http_msg_write (struct vlc_http_msg *msg, block_t *b, bool eos)
	Sends HTTP data.

Detailed Description

HTTP messages, header formatting and parsing.

Function Documentation

vlc_http_authority()

int char * vlc_http_authority	(	const char *	host,
		unsigned	port
	)

Formats an authority.

Parameters

host	host name (cannot be NULL)
port	port number (0 for unspecified)

Returns

the formatted authority as a heap-allocated nul-terminated string, or NULL on allocation failure

References asprintf(), vlc_http_msg::authority, and unlikely.

Referenced by vlc_http_outfile_create(), vlc_http_res_init(), and vlc_http_tunnel_open().

vlc_http_msg_add_agent()

int vlc_http_msg_add_agent	(	struct vlc_http_msg *	m,
		const char *	str
	)

Sets the agent field.

Sets the User-Agent or Server header field.

References vlc_http_msg::status, vlc_http_is_agent(), and vlc_http_msg_add_header().

Referenced by vlc_http_outfile_create(), vlc_http_res_req(), and vlc_http_tunnel_open().

vlc_http_msg_add_atime()

int vlc_http_msg_add_atime

(

struct vlc_http_msg *

m

)

Adds a Date header field.

References vlc_http_msg_add_time().

vlc_http_msg_add_cookies()

int vlc_http_msg_add_cookies	(	struct vlc_http_msg *	m,
		struct vlc_http_cookie_jar_t *	jar
	)

References vlc_http_msg::authority, vlc_http_msg::path, vlc_http_msg::scheme, strcasecmp(), strndup(), unlikely, vlc_http_cookies_fetch(), and vlc_http_msg_add_header().

Referenced by vlc_http_outfile_create(), and vlc_http_res_req().

vlc_http_msg_add_creds_basic()

int vlc_http_msg_add_creds_basic	(	struct vlc_http_msg *	msg,
		bool	proxy,
		const char *	username,
		const char *	password
	)

Adds Basic credentials.

Formats a plain username and password pair using HTTP Basic (RFC7617) syntax.

Parameters

msg	the request to add the credentials to
proxy	true for proxy authentication, false for origin server authentication
username	null-terminated username
password	null-terminated password

Returns

0 on success, -1 on out-of-memory (ENOMEM) or if username or password are invalid (EINVAL).

References asprintf(), unlikely, vlc_b64_encode_binary(), and vlc_http_msg_add_header().

Referenced by vlc_http_outfile_create(), vlc_http_res_req(), and vlc_http_tunnel_open().

vlc_http_msg_add_header()

int vlc_http_msg_add_header	(	struct vlc_http_msg *	,
		const char *	name,
		const char *	fmt,
			...
	)

Formats a header field.

Adds an HTTP message header to an HTTP request or response. All headers must be formatted before the message is sent.

Parameters

name	header field name
fmt	printf-style format string

Returns

0 on success, -1 on error (out of memory)

vlc_http_msg_add_time()

int vlc_http_msg_add_time	(	struct vlc_http_msg *	msg,
		const char *	name,
		const time_t *	t
	)

Adds a timestamp header field.

Parameters

msg	the request to add the header to
name	header field name
t	pointer to timestamp

Returns

0 on success, -1 on error (errno is set accordingly)

References gmtime_r(), vlc_http_days, vlc_http_months, and vlc_http_msg_add_header().

Referenced by vlc_http_file_req(), and vlc_http_msg_add_atime().

vlc_http_msg_destroy()

void vlc_http_msg_destroy

(

struct vlc_http_msg *

m

)

Destroys an HTTP message.

References vlc_http_msg::authority, vlc_http_msg::count, vlc_http_msg::headers, vlc_http_msg::method, vlc_http_msg::path, vlc_http_msg::payload, vlc_http_msg::scheme, and vlc_http_stream_close().

Referenced by vlc_h1_stream_wait(), vlc_h2_stream_close(), vlc_h2_stream_headers(), vlc_http_file_seek(), vlc_http_live_read(), vlc_http_msg_h2_headers(), vlc_http_msg_headers(), vlc_http_msg_iterate(), vlc_http_outfile_close(), vlc_http_outfile_create(), vlc_http_req_create(), vlc_http_res_deinit(), vlc_http_res_open(), vlc_http_res_req(), vlc_http_res_set_login(), and vlc_http_tunnel_open().

vlc_http_msg_get_agent()

const char * vlc_http_msg_get_agent

(

const struct vlc_http_msg *

m

)

Gets the agent field.

Gets the User-Agent or Server header field.

References vlc_http_msg::status, vlc_http_is_agent(), and vlc_http_msg_get_header().

vlc_http_msg_get_atime()

time_t vlc_http_msg_get_atime

(

const struct vlc_http_msg *

m

)

Gets message date.

Extracts the original date of the message from the HTTP Date header.

Returns

a time value on success, -1 on error.

References vlc_http_msg_get_time().

vlc_http_msg_get_authority()

const char * vlc_http_msg_get_authority

(

const struct vlc_http_msg *

m

)

Gets request authority.

Returns

request authority (e.g. "www.example.com:8080"), or NULL if response

References vlc_http_msg::authority.

vlc_http_msg_get_basic_realm()

char * vlc_http_msg_get_basic_realm

(

const struct vlc_http_msg *

m

)

References vlc_http_get_token_value(), and vlc_http_msg_get_token().

Referenced by vlc_http_res_get_basic_realm().

vlc_http_msg_get_cookies()

void vlc_http_msg_get_cookies	(	const struct vlc_http_msg *	m,
		struct vlc_http_cookie_jar_t *	jar,
		const char *	host,
		const char *	path
	)

References vlc_http_msg::count, vlc_http_msg::headers, strcasecmp(), and vlc_http_cookies_store().

Referenced by vlc_http_res_open().

vlc_http_msg_get_final()

struct vlc_http_msg * vlc_http_msg_get_final

(

struct vlc_http_msg *

m

)

Gets final response headers.

Skips HTTP 1xx continue headers until a final set of response headers is received. This is a convenience wrapper around vlc_http_msg_iterate() for use when continuation headers are not useful (e.g. GET or CONNECT).

Parameters

m	current response headers or NULL

Returns

the final response headers (m if it was already final), NULL if the parameter was NULL, or NULL on error

References vlc_http_msg_get_status(), and vlc_http_msg_iterate().

Referenced by vlc_http_res_open(), and vlc_http_tunnel_open().

vlc_http_msg_get_header()

const char * vlc_http_msg_get_header	(	const struct vlc_http_msg *	m,
		const char *	name
	)

Looks up an header field.

Finds an HTTP header field by (case-insensitive) name inside an HTTP message header. If the message has more than one matching field, their value are folded (as permitted by protocol specifications).

Returns

header field value (valid until message is destroyed), or NULL if no fields matched

References vlc_http_msg::headers, name, and vlc_http_msg_find_header().

Referenced by vlc_http_file_req(), vlc_http_file_resp(), vlc_http_msg_get_agent(), vlc_http_msg_get_file_size(), vlc_http_msg_get_retry_after(), vlc_http_msg_get_size(), vlc_http_msg_get_time(), vlc_http_msg_get_token(), vlc_http_res_get_redirect(), and vlc_http_res_get_type().

vlc_http_msg_get_method()

const char * vlc_http_msg_get_method

(

const struct vlc_http_msg *

m

)

Gets request method.

Returns

request method (e.g. "GET"), or NULL if response

References vlc_http_msg::method.

vlc_http_msg_get_mtime()

time_t vlc_http_msg_get_mtime

(

const struct vlc_http_msg *

m

)

Gets resource date.

Extracts the last modification date of the message content from the HTTP Last-Modified header.

Returns

a time value on success, -1 on error.

References vlc_http_msg_get_time().

Referenced by vlc_http_file_req().

vlc_http_msg_get_path()

const char * vlc_http_msg_get_path

(

const struct vlc_http_msg *

m

)

Gets request absolute path.

Returns

request absolute path (e.g. "/index.html"), or NULL if absent

References vlc_http_msg::path.

vlc_http_msg_get_retry_after()

unsigned vlc_http_msg_get_retry_after

(

const struct vlc_http_msg *

m

)

Gets retry timeout.

Extracts the time (in seconds) until the expiration of the "retry-after" time-out in the HTTP message. If the header value is an absolute date, it is converted relative to the current time.

Returns

the time in seconds, zero if the date is overdue or on error.

References vlc_http_mktime(), and vlc_http_msg_get_header().

vlc_http_msg_get_scheme()

const char * vlc_http_msg_get_scheme

(

const struct vlc_http_msg *

m

)

Gets request scheme.

Returns

request scheme (e.g. "https"), or NULL if absent

References vlc_http_msg::scheme.

vlc_http_msg_get_size()

uintmax_t vlc_http_msg_get_size

(

const struct vlc_http_msg *

m

)

Gets HTTP payload length.

Determines the total length (in bytes) of the payload associated with the HTTP message.

Returns

byte length, or (uintmax_t)-1 if unknown.

References vlc_http_msg::status, and vlc_http_msg_get_header().

Referenced by vlc_h1_stream_wait(), and vlc_http_file_get_size().

vlc_http_msg_get_status()

int vlc_http_msg_get_status

(

const struct vlc_http_msg *

m

)

Gets response status code.

Returns

status code (e.g. 404), or negative if request

References vlc_http_msg::status.

Referenced by vlc_http_file_resp(), vlc_http_file_seek(), vlc_http_msg_can_seek(), vlc_http_msg_get_file_size(), vlc_http_msg_get_final(), vlc_http_outfile_close(), vlc_http_outfile_create(), vlc_http_res_get_status(), vlc_http_res_open(), vlc_http_res_set_login(), and vlc_http_tunnel_open().

vlc_http_msg_get_time()

time_t vlc_http_msg_get_time	(	const struct vlc_http_msg *	msg,
		const char *	name
	)

Parses a timestamp header field.

w*

Parameters

msg	the response to get the timestamp header from
name	header field name

Returns

a timestamp value, or -1 on error.

References name, vlc_http_mktime(), and vlc_http_msg_get_header().

Referenced by vlc_http_msg_get_atime(), and vlc_http_msg_get_mtime().

vlc_http_msg_get_token()

const char * vlc_http_msg_get_token	(	const struct vlc_http_msg *	msg,
		const char *	field,
		const char *	token
	)

Looks up a token in a header field.

Finds the first occurrence of a token within a HTTP field header.

Parameters

msg	the request to get the token from
field	HTTP header field name
token	HTTP token name

Returns

the first byte of the token if found, NULL if not found.

References vlc_http_get_token(), and vlc_http_msg_get_header().

Referenced by vlc_h1_stream_wait(), vlc_http_msg_can_seek(), and vlc_http_msg_get_basic_realm().

vlc_http_msg_iterate()

struct vlc_http_msg * vlc_http_msg_iterate

(

struct vlc_http_msg *

m

)

Gets next response headers.

Discards the current response headers and gets the next set of response headers for the same request. This is intended for HTTP 1xx continuation responses and for message trailers.

Parameters

m	current response headers (destroyed by the call)

Returns

next response headers or NULL on error

References vlc_http_msg::payload, vlc_http_msg_destroy(), and vlc_http_stream_read_headers().

Referenced by vlc_http_msg_get_final(), and vlc_http_outfile_close().

vlc_http_msg_read()

block_t * vlc_http_msg_read

(

struct vlc_http_msg *

m

)

Receives HTTP data.

Dequeues the next block of data from an HTTP message. If no pending data has been received, waits until data is received, the stream ends or the underlying connection fails.

Returns

data block

Return values

NULL	on end-of-stream
vlc_http_error	on fatal error

References vlc_http_msg::payload, and vlc_http_stream_read().

Referenced by vlc_http_res_read().

vlc_http_msg_write()

int vlc_http_msg_write	(	struct vlc_http_msg *	msg,
		block_t *	b,
		bool	eos
	)

Sends HTTP data.

Queues the next block of data for an HTTP message payload.

Note

This function takes ownership of the passed data block(s).

Parameters

msg	the request to append the data block to
b	chain of block of data to be sent
eos	true to indicate the end of the payload

Return values

0	success
-1	fatal error

References block_ChainRelease, block_Release, vlc_frame_t::i_buffer, vlc_frame_t::p_buffer, vlc_frame_t::p_next, vlc_http_msg::payload, and vlc_http_stream_write().

Referenced by vlc_http_outfile_close(), and vlc_http_outfile_write().

vlc_http_next_token()

const char * vlc_http_next_token

(

const char *

value

)

Finds next token.

Finds the following token in a HTTP header field value.

Returns

First character of the following token, or NULL if there are no further tokens

References vlc_http_quoted_length().

Referenced by vlc_h1_stream_wait(), and vlc_http_get_token().

vlc_http_req_create()

struct vlc_http_msg * vlc_http_req_create	(	const char *	method,
		const char *	scheme,
		const char *	authority,
		const char *	path
	)

Creates an HTTP request.

Allocates an HTTP request message.

Parameters

method	request method (e.g. "GET")
scheme	protocol scheme (e.g. "https")
authority	target host (e.g. "www.example.com:8080")
path	request path (e.g. "/dir/page.html")

Returns

an HTTP stream or NULL on allocation failure

References vlc_http_msg::authority, vlc_http_msg::count, vlc_http_msg::headers, vlc_http_msg::method, vlc_http_msg::path, vlc_http_msg::payload, vlc_http_msg::scheme, vlc_http_msg::status, strdup(), unlikely, and vlc_http_msg_destroy().

Referenced by vlc_http_outfile_create(), vlc_http_res_req(), and vlc_http_tunnel_open().

vlc_http_resp_create()

struct vlc_http_msg * vlc_http_resp_create

(

unsigned

status

)

Creates an HTTP response.

Allocates an HTTP response message.

Parameters

status

HTTP status code

Returns

an HTTP stream or NULL on allocation failure

References vlc_http_msg::authority, vlc_http_msg::count, vlc_http_msg::headers, vlc_http_msg::method, vlc_http_msg::path, vlc_http_msg::payload, vlc_http_msg::scheme, vlc_http_msg::status, and unlikely.

Referenced by vlc_http_msg_h2_headers(), and vlc_http_msg_headers().