Commit 65486fd3 authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont

https: improve documentation

parent 7c664b97
......@@ -759,7 +759,8 @@ WARN_LOGFILE =
# Note: If this tag is empty the current directory is searched.
INPUT = @top_srcdir@/src \
@top_srcdir@/include
@top_srcdir@/include \
@top_srcdir@/modules/access/http
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
......
......@@ -18,6 +18,13 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup http_conn Connections
* HTTP connections
* \ingroup http_connmgr
* @{
*/
struct vlc_tls;
struct vlc_http_conn;
struct vlc_http_msg;
......@@ -47,8 +54,22 @@ static inline void vlc_http_conn_release(struct vlc_http_conn *conn)
conn->cbs->release(conn);
}
/**
* \defgroup http1 HTTP/1.x
* @{
*/
struct vlc_http_conn *vlc_h1_conn_create(struct vlc_tls *, bool proxy);
struct vlc_http_conn *vlc_h2_conn_create(struct vlc_tls *);
struct vlc_http_stream *vlc_chunked_open(struct vlc_http_stream *,
struct vlc_tls *);
/** @} */
/**
* \defgroup h2 HTTP/2.0
* @{
*/
struct vlc_http_conn *vlc_h2_conn_create(struct vlc_tls *);
/** @} */
/** @} */
......@@ -18,19 +18,63 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup http HTTP
* Hyper-Text Transfer Protocol
* \defgroup http_connmgr Connection manager
* HTTP connection management
* \ingroup http
* @{
* \file connmgr.h
*/
struct vlc_http_mgr;
struct vlc_http_msg;
struct vlc_http_cookie_jar_t;
/**
* Sends an HTTP request
*
* Sends an HTTP request, by either reusing an existing HTTP connection or
* establishing a new one. If succesful, the initial HTTP response header is
* returned.
*
* @param mgr HTTP connection manager
* @param https whether to use HTTPS (true) or unencrypted HTTP (false)
* @param host name of authoritative HTTP server to send the request to
* @param port TCP server port number, or 0 for the default port number
* @param req HTTP request header to send
*
* @return The initial HTTP response header, or NULL in case of failure.
*/
struct vlc_http_msg *vlc_http_mgr_request(struct vlc_http_mgr *mgr, bool https,
const char *host, unsigned port,
const struct vlc_http_msg *req);
int vlc_http_mgr_send_cookies(struct vlc_http_mgr *, struct vlc_http_msg *);
void vlc_http_mgr_recv_cookies(struct vlc_http_mgr *mgr, bool https,
const char *host, const char *path,
const struct vlc_http_msg *resp);
/**
* Creates an HTTP connection manager
*
* Allocates an HTTP client connections manager.
*
* @param obj parent VLC object
* @param jar HTTP cookies jar (NULL to disable cookies)
* @param h2c Favor unencrypted HTTP/2 over HTTP/1.1
*/
struct vlc_http_mgr *vlc_http_mgr_create(vlc_object_t *obj,
struct vlc_http_cookie_jar_t *jar,
bool h2c);
/**
* Destroys an HTTP connection manager
*
* Deallocates an HTTP client connections manager created by
* vlc_http_msg_destroy(). Any remaining connection is closed and destroyed.
*/
void vlc_http_mgr_destroy(struct vlc_http_mgr *mgr);
/** @} */
......@@ -20,20 +20,85 @@
#include <stdint.h>
/**
* \defgroup http_file Files
* HTTP read-only files
* \ingroup http_res
* @{
*/
struct vlc_http_file;
struct vlc_http_mgr;
struct block_t;
/**
* Creates an HTTP file.
*
* Allocates a structure for a remote HTTP-served read-only file.
*
* @param url URL of the file to read
* @param ua user agent string (or NULL to ignore)
* @param ref referral URL (or NULL to ignore)
*/
struct vlc_http_file *vlc_http_file_create(struct vlc_http_mgr *mgr,
const char *url, const char *ua,
const char *ref);
void vlc_http_file_destroy(struct vlc_http_file *file);
int vlc_http_file_get_status(struct vlc_http_file *file);
char *vlc_http_file_get_redirect(struct vlc_http_file *file);
/**
* Destroys an HTTP file.
*
* Releases all resources allocated or held by the HTTP file object.
*/
void vlc_http_file_destroy(struct vlc_http_file *);
int vlc_http_file_get_status(struct vlc_http_file *);
/**
* Gets redirection URL.
*
* Checks if the file URL lead to a redirection. If so, return the redirect
* location.
*
* @return Heap-allocated URL or NULL if no redirection.
*/
char *vlc_http_file_get_redirect(struct vlc_http_file *);
/**
* Gets file size.
*
* Determines the file size in bytes.
*
* @return Bytes count or (uintmax_t)-1 if unknown.
*/
uintmax_t vlc_http_file_get_size(struct vlc_http_file *);
/**
* Checks seeking support.
*
* @retval true if file supports seeking
* @retval false if file does not support seeking
*/
bool vlc_http_file_can_seek(struct vlc_http_file *);
/**
* Gets MIME type.
*
* @return Heap-allocated MIME type string, or NULL if unknown.
*/
char *vlc_http_file_get_type(struct vlc_http_file *);
/**
* Sets the read offset.
*
* @param offset byte offset of next read
* @retval 0 if seek succeeded
* @retval -1 if seek failed
*/
int vlc_http_file_seek(struct vlc_http_file *, uintmax_t offset);
/**
* Reads data.
*/
struct block_t *vlc_http_file_read(struct vlc_http_file *);
uintmax_t vlc_http_file_get_size(struct vlc_http_file *file);
bool vlc_http_file_can_seek(struct vlc_http_file *file);
char *vlc_http_file_get_type(struct vlc_http_file *file);
int vlc_http_file_seek(struct vlc_http_file *file, uintmax_t offset);
struct block_t *vlc_http_file_read(struct vlc_http_file *file);
/** @} */
......@@ -21,6 +21,12 @@
#include <stdbool.h>
#include <stdint.h>
/**
* \defgroup h2_frames HTTP/2 frames
* \ingroup h2
* @{
*/
struct vlc_h2_frame
{
struct vlc_h2_frame *next;
......@@ -128,3 +134,5 @@ const uint8_t *vlc_h2_frame_data_get(const struct vlc_h2_frame *f,
const struct vlc_h2_frame *: (vlc_h2_frame_data_get)(f, l), \
struct vlc_h2_frame *: (uint8_t *)(vlc_h2_frame_data_get)(f, l))
#endif
/** @} */
......@@ -18,6 +18,12 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup h2_output HTTP/2 output
* \ingroup h2
* @{
*/
struct vlc_h2_output;
struct vlc_h2_frame;
struct vlc_tls;
......@@ -27,3 +33,5 @@ int vlc_h2_output_send(struct vlc_h2_output *, struct vlc_h2_frame *);
struct vlc_h2_output *vlc_h2_output_create(struct vlc_tls *, bool client);
void vlc_h2_output_destroy(struct vlc_h2_output *);
/** @} */
......@@ -18,6 +18,13 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup hpack HPACK compression
* HTTP/2 header compression (HPACK)
* \ingroup h2
* @{
*/
struct hpack_decoder;
struct hpack_decoder *hpack_decode_init(size_t header_table_size);
......@@ -30,3 +37,5 @@ size_t hpack_encode_hdr_neverindex(uint8_t *restrict buf, size_t size,
const char *name, const char *value);
size_t hpack_encode(uint8_t *restrict buf, size_t size,
const char *const headers[][2], unsigned count);
/** @} */
......@@ -18,6 +18,13 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup http_live Live streams
* Trivial HTTP-based live streams
* \ingroup http_res
* @{
*/
struct vlc_http_live;
struct block_t;
......@@ -30,3 +37,5 @@ int vlc_http_live_get_status(struct vlc_http_live *live);
char *vlc_http_live_get_redirect(struct vlc_http_live *live);
char *vlc_http_live_get_type(struct vlc_http_live *live);
block_t *vlc_http_live_read(struct vlc_http_live *live);
/** @} */
......@@ -20,6 +20,14 @@
#include <stdint.h>
/**
* \defgroup http_msg Messages
* HTTP messages, header formatting and parsing
* \ingroup http
* @{
* \file message.h
*/
struct vlc_http_msg;
struct block_t;
struct vlc_http_cookie_jar_t;
......@@ -52,51 +60,57 @@ struct vlc_http_msg *vlc_http_resp_create(unsigned status) VLC_USED;
/**
* Destroys an HTTP message.
*/
void vlc_http_msg_destroy(struct vlc_http_msg *m);
void vlc_http_msg_destroy(struct vlc_http_msg *);
/**
* Formats a header.
* 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.
*
* @param name header name
* @param name header field name
* @param fmt printf-style format string
* @return 0 on success, -1 on error (out of memory)
*/
int vlc_http_msg_add_header(struct vlc_http_msg *m, const char *name,
int vlc_http_msg_add_header(struct vlc_http_msg *, const char *name,
const char *fmt, ...) VLC_FORMAT(3,4);
/**
* Sets the agent header.
* Sets the agent field.
*
* Sets the User-Agent or Server header.
* Sets the User-Agent or Server header field.
*/
int vlc_http_msg_add_agent(struct vlc_http_msg *m, const char *str);
int vlc_http_msg_add_agent(struct vlc_http_msg *, const char *);
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.
*/
const char *vlc_http_msg_get_agent(const struct vlc_http_msg *);
/**
* Parses a timestamp header.
* Parses a timestamp header field.
*
* @param name header field name
* @return a timestamp value, or -1 on error.
*/
time_t vlc_http_msg_get_time(const struct vlc_http_msg *m, const char *name);
time_t vlc_http_msg_get_time(const struct vlc_http_msg *, const char *name);
/**
* Adds a timestamp header.
* Adds a timestamp header field.
*
* @param name header field name
* @param t pointer to timestamp
* @return 0 on success, -1 on error (errno is set accordingly)
*/
int vlc_http_msg_add_time(struct vlc_http_msg *m, const char *name,
int vlc_http_msg_add_time(struct vlc_http_msg *, const char *name,
const time_t *t);
/**
* Adds a Date header.
* Adds a Date header field.
*/
int vlc_http_msg_add_atime(struct vlc_http_msg *m);
int vlc_http_msg_add_atime(struct vlc_http_msg *);
/**
* Gets message date.
......@@ -105,7 +119,7 @@ int vlc_http_msg_add_atime(struct vlc_http_msg *m);
*
* @return a time value on success, -1 on error.
*/
time_t vlc_http_msg_get_atime(const struct vlc_http_msg *m);
time_t vlc_http_msg_get_atime(const struct vlc_http_msg *);
/**
* Gets resource date.
......@@ -115,7 +129,7 @@ time_t vlc_http_msg_get_atime(const struct vlc_http_msg *m);
*
* @return a time value on success, -1 on error.
*/
time_t vlc_http_msg_get_mtime(const struct vlc_http_msg *m);
time_t vlc_http_msg_get_mtime(const struct vlc_http_msg *);
/**
* Gets retry timeout.
......@@ -126,7 +140,7 @@ time_t vlc_http_msg_get_mtime(const struct vlc_http_msg *m);
*
* @return the time in seconds, zero if the date is overdue or on error.
*/
unsigned vlc_http_msg_get_retry_after(const struct vlc_http_msg *m);
unsigned vlc_http_msg_get_retry_after(const struct vlc_http_msg *);
void vlc_http_msg_get_cookies(const struct vlc_http_msg *,
struct vlc_http_cookie_jar_t *, bool secure,
......@@ -135,23 +149,53 @@ int vlc_http_msg_add_cookies(struct vlc_http_msg *,
struct vlc_http_cookie_jar_t *);
/**
* Looks up an HTTP header.
* Looks up an header field.
*
* Finds an HTTP header by (case-insensitive) name inside an HTTP message.
* If the message has more than one matching header, their value are folded
* (as permitted by specifications).
* 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).
*
* @return header value (valid until message is destroyed),
* or NULL if no headers matched
* @return header field value (valid until message is destroyed),
* or NULL if no fields matched
*/
const char *vlc_http_msg_get_header(const struct vlc_http_msg *m,
const char *vlc_http_msg_get_header(const struct vlc_http_msg *,
const char *name);
/**
* Gets response status code.
*
* @return status code (e.g. 404), or negative if request
*/
int vlc_http_msg_get_status(const struct vlc_http_msg *m);
const char *vlc_http_msg_get_method(const struct vlc_http_msg *m);
const char *vlc_http_msg_get_scheme(const struct vlc_http_msg *m);
const char *vlc_http_msg_get_authority(const struct vlc_http_msg *m);
const char *vlc_http_msg_get_path(const struct vlc_http_msg *m);
/**
* Gets request method.
*
* @return request method (e.g. "GET"), or NULL if response
*/
const char *vlc_http_msg_get_method(const struct vlc_http_msg *);
/**
* Gets request scheme.
*
* @return request scheme (e.g. "https"), or NULL if absent
*/
const char *vlc_http_msg_get_scheme(const struct vlc_http_msg *);
/**
* Gets request authority.
*
* @return request authority (e.g. "www.example.com:8080"),
* or NULL if response
*/
const char *vlc_http_msg_get_authority(const struct vlc_http_msg *);
/**
* Gets request absolute path.
*
* @return request absolute path (e.g. "/index.html"), or NULL if absent
*/
const char *vlc_http_msg_get_path(const struct vlc_http_msg *);
/**
* Looks up a token in a header field.
......@@ -168,16 +212,22 @@ const char *vlc_http_msg_get_token(const struct vlc_http_msg *,
/**
* Finds next token.
*
* Finds the following token in a HTTP field value.
* Finds the following token in a HTTP header field value.
*
* @return First character of the following token,
* or NULL if there are no further tokens
*/
const char *vlc_http_next_token(const char *);
/**
* Gets HTTP payload length.
*
* Determines the total length (in bytes) of the payload associated with the
* HTTP message.
*
* @return byte length, or (uintmax_t)-1 if unknown.
*/
uintmax_t vlc_http_msg_get_size(const struct vlc_http_msg *m);
uintmax_t vlc_http_msg_get_size(const struct vlc_http_msg *);
/**
* Gets next response headers.
......@@ -188,9 +238,9 @@ uintmax_t vlc_http_msg_get_size(const struct vlc_http_msg *m);
*
* @param m current response headers (destroyed by the call)
*
* @return next response headers or NULL on error.
* @return next response headers or NULL on error
*/
struct vlc_http_msg *vlc_http_msg_iterate(struct vlc_http_msg *m) VLC_USED;
struct vlc_http_msg *vlc_http_msg_iterate(struct vlc_http_msg *) VLC_USED;
/**
* Gets final response headers.
......@@ -202,9 +252,9 @@ struct vlc_http_msg *vlc_http_msg_iterate(struct vlc_http_msg *m) VLC_USED;
* @param m current response headers or NULL
*
* @return the final response headers (m if it was already final),
* NULL if the parameter was NULL, or NULL on error.
* NULL if the parameter was NULL, or NULL on error
*/
struct vlc_http_msg *vlc_http_msg_get_final(struct vlc_http_msg *m) VLC_USED;
struct vlc_http_msg *vlc_http_msg_get_final(struct vlc_http_msg *) VLC_USED;
/**
* Receives HTTP data.
......@@ -215,15 +265,38 @@ struct vlc_http_msg *vlc_http_msg_get_final(struct vlc_http_msg *m) VLC_USED;
*
* @return data block, or NULL on end-of-stream or error
*/
struct block_t *vlc_http_msg_read(struct vlc_http_msg *m) VLC_USED;
struct block_t *vlc_http_msg_read(struct vlc_http_msg *) VLC_USED;
/** @} */
/**
* \defgroup http_stream Streams
* \ingroup http_connmgr
*
* HTTP request/response streams
*
* A stream is initiated by a client-side request header. It includes a
* final response header, possibly preceded by one or more continuation
* response headers. After the response header, a stream usually carries
* a response payload.
*
* A stream may also carry a request payload (this is not supported so far).
*
* The HTTP stream constitutes the interface between an HTTP connection and
* the higher-level HTTP messages layer.
* @{
*/
/* Interfaces to lower layers */
struct vlc_http_stream;
void vlc_http_msg_attach(struct vlc_http_msg *m, struct vlc_http_stream *s);
struct vlc_http_msg *vlc_http_msg_get_initial(struct vlc_http_stream *s)
VLC_USED;
/** HTTP stream callbacks
*
* Connection-specific callbacks for stream manipulation
*/
struct vlc_http_stream_cbs
{
struct vlc_http_msg *(*read_headers)(struct vlc_http_stream *);
......@@ -231,34 +304,83 @@ struct vlc_http_stream_cbs
void (*close)(struct vlc_http_stream *, bool abort);
};
/** HTTP stream */
struct vlc_http_stream
{
const struct vlc_http_stream_cbs *cbs;
};
/**
* Reads one message header.
*
* Reads the next message header of an HTTP stream from the network.
* There is always exactly one request header per stream. There is usually
* one response header per stream, except for continuation (1xx) headers.
*
* @warning The caller is responsible for reading headers at appropriate
* times as intended by the protocol. Failure to do so may result in protocol
* dead lock, and/or (HTTP 1.x) connection failure.
*/
static inline
struct vlc_http_msg *vlc_http_stream_read_headers(struct vlc_http_stream *s)
{
return s->cbs->read_headers(s);
}
/**
* Reads message payload data.
*
* Reads the next block of data from the message payload of an HTTP stream.
*/
static inline struct block_t *vlc_http_stream_read(struct vlc_http_stream *s)
{
return s->cbs->read(s);
}
/**
* Closes an HTTP stream.
*
* Releases all resources associated or held by an HTTP stream. Any unread
* header or data is discarded.
*/
static inline void vlc_http_stream_close(struct vlc_http_stream *s, bool abort)
{
s->cbs->close(s, abort);
}
/** @} */
/**
* Formats an HTTP 1.1 message header.
*
* Formats an message header in HTTP 1.x format, using HTTP version 1.1.
*
* @param m message to format/serialize
* @param lenp location to write the length of the formatted message in bytes
* [OUT]
* @param proxied whether the message is meant for sending to a proxy rather
* than an origin (only relevant for requests)
* @return A heap-allocated nul-terminated string or *lenp bytes,
* or NULL on error
*/
char *vlc_http_msg_format(const struct vlc_http_msg *m, size_t *restrict lenp,
bool proxied) VLC_USED;
/**
* Parses an HTTP 1.1 message header.
*/
struct vlc_http_msg *vlc_http_msg_headers(const char *msg) VLC_USED;
struct vlc_h2_frame;
/**
* Formats an HTTP 2.0 HEADER frame.
*/
struct vlc_h2_frame *vlc_http_msg_h2_frame(const struct vlc_http_msg *m,
uint_fast32_t stream_id, bool eos);
/**
* Parses an HTTP 2.0 header table.
*/
struct vlc_http_msg *vlc_http_msg_h2_headers(unsigned count,
const char *const headers[][2]);
......@@ -18,6 +18,13 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup http_res Resources
* Remote HTTP resources identified by a URL
* \ingroup http
* @{
*/
struct vlc_http_msg;
struct vlc_http_mgr;
......@@ -44,3 +51,5 @@ char *vlc_http_res_get_redirect(const struct vlc_http_resource *,
const struct vlc_http_msg *resp);
char *vlc_http_res_get_type(const struct vlc_http_msg *resp);
struct block_t *vlc_http_res_read(struct vlc_http_msg *resp);
/** @} */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment