From 65486fd385c449b9d5a2725b0ffaef15b2abe4fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Denis-Courmont?= Date: Tue, 5 Jan 2016 21:54:40 +0200 Subject: [PATCH] https: improve documentation --- doc/Doxyfile.in | 3 +- modules/access/http/conn.h | 25 ++++- modules/access/http/connmgr.h | 44 ++++++++ modules/access/http/file.h | 81 ++++++++++++-- modules/access/http/h2frame.h | 8 ++ modules/access/http/h2output.h | 8 ++ modules/access/http/hpack.h | 9 ++ modules/access/http/live.h | 9 ++ modules/access/http/message.h | 194 +++++++++++++++++++++++++++------ modules/access/http/resource.h | 9 ++ 10 files changed, 343 insertions(+), 47 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index fe8582ca4a..302a10bff7 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -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 diff --git a/modules/access/http/conn.h b/modules/access/http/conn.h index 0b9aa8c5b9..59aa8c9370 100644 --- a/modules/access/http/conn.h +++ b/modules/access/http/conn.h @@ -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 *); + +/** @} */ + +/** @} */ diff --git a/modules/access/http/connmgr.h b/modules/access/http/connmgr.h index 81d8a34e0b..32b67ff031 100644 --- a/modules/access/http/connmgr.h +++ b/modules/access/http/connmgr.h @@ -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); + +/** @} */ diff --git a/modules/access/http/file.h b/modules/access/http/file.h index 5a27f9b254..f47795d76a 100644 --- a/modules/access/http/file.h +++ b/modules/access/http/file.h @@ -20,20 +20,85 @@ #include +/** + * \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); +/** @} */ diff --git a/modules/access/http/h2frame.h b/modules/access/http/h2frame.h index 49a5c1fbdf..f7902429fe 100644 --- a/modules/access/http/h2frame.h +++ b/modules/access/http/h2frame.h @@ -21,6 +21,12 @@ #include #include +/** + * \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 + +/** @} */ diff --git a/modules/access/http/h2output.h b/modules/access/http/h2output.h index dcbd491d2a..1717d20b91 100644 --- a/modules/access/http/h2output.h +++ b/modules/access/http/h2output.h @@ -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 *); + +/** @} */ diff --git a/modules/access/http/hpack.h b/modules/access/http/hpack.h index 6d42908ee8..df375d0894 100644 --- a/modules/access/http/hpack.h +++ b/modules/access/http/hpack.h @@ -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); + +/** @} */ diff --git a/modules/access/http/live.h b/modules/access/http/live.h index deaae86406..a81e9e26a9 100644 --- a/modules/access/http/live.h +++ b/modules/access/http/live.h @@ -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); + +/** @} */ diff --git a/modules/access/http/message.h b/modules/access/http/message.h index eebe7f71d2..08284a6cea 100644 --- a/modules/access/http/message.h +++ b/modules/access/http/message.h @@ -20,6 +20,14 @@ #include +/** + * \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]); diff --git a/modules/access/http/resource.h b/modules/access/http/resource.h index 3990921462..91e4f11c47 100644 --- a/modules/access/http/resource.h +++ b/modules/access/http/resource.h @@ -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); + +/** @} */