https: improve documentation

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

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 *);
+
+/** @} */
+
+/** @} */

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);
+
+/** @} */

modules/access/http/file.h

@@ -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);
+/** @} */

modules/access/http/h2frame.h

@@ -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
+
+/** @} */

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 *);
+
+/** @} */

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);
+
+/** @} */

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);
+
+/** @} */

modules/access/http/message.h

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

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);
+
+/** @} */