http.h docs.

src/http.h

@@ -14,38 +14,88 @@
 #include <stdbool.h>
 #include <stddef.h>
 
+/** An HTTP connection. */
 typedef struct _tf_http_connection_t tf_http_connection_t;
+
+/** An HTTP request. */
 typedef struct _tf_http_request_t tf_http_request_t;
+
+/** An HTTP instance. */
 typedef struct _tf_http_t tf_http_t;
+
+/** A TLS context. */
 typedef struct _tf_tls_context_t tf_tls_context_t;
+
+/** A trace instance. */
 typedef struct _tf_trace_t tf_trace_t;
+
+/** An event loop. */
 typedef struct uv_loop_s uv_loop_t;
 
+/**
+** A callback called when receiving a websocket message.
+** @param request The HTTP request.
+** @param op_code The type of websocket message.
+** @param data The payload.
+** @param size The size of the payload in bytes.
+*/
 typedef void(tf_http_message_callback)(tf_http_request_t* request, int op_code, const void* data, size_t size);
+
+/**
+** A callback called when a request closes.
+** @param request The HTTP request.
+*/
 typedef void(tf_http_close_callback)(tf_http_request_t* request);
 
+/**
+** A callback called when an HTTP request is received.
+** @param request The HTTP request.
+*/
+typedef void(tf_http_callback_t)(tf_http_request_t* request);
+
+/**
+** A callback called when the HTTP instance is destroyed.
+** @param user_data User data provided with the callback.
+*/
+typedef void(tf_http_cleanup_t)(void* user_data);
+
+/**
+** An HTTP request.
+*/
 typedef struct _tf_http_request_t
 {
+	/** The HTTP instance this request belongs to. */
 	tf_http_t* http;
+	/** The HTTP connection associated with this request. */
 	tf_http_connection_t* connection;
+	/** True if this is an HTTPS session. */
 	bool is_tls;
+	/** The HTTP method of the request (GET/POST/...). */
 	const char* method;
+	/** The HTTP request path. */
 	const char* path;
+	/** The raw HTTP query string. */
 	const char* query;
+	/** The HTTP request body. */
 	void* body;
+	/** The length of the HTTP request body. */
 	size_t content_length;
+	/** Header storage.  Can also be accessed with tf_http_request_get_header(). */
 	struct phr_header* headers;
+	/** The number of headers stored. */
 	int headers_count;
+	/** A callback to be called when receiving a websocket message. */
 	tf_http_message_callback* on_message;
+	/** A callback to be called when the connection is closed. */
 	tf_http_close_callback* on_close;
+	/** Extra storage for user data. */
 	void* context;
+	/** User data available to callbacks. */
 	void* user_data;
+	/** The number of times tf_http_request_ref() has been called without tf_http_request_unref(). */
 	int ref_count;
 } tf_http_request_t;
 
-typedef void(tf_http_callback_t)(tf_http_request_t* request);
-typedef void(tf_http_cleanup_t)(void* user_data);
-
 /**
 ** Create an HTTP server using the given libuv loop.
 ** @param loop A libuv loop to use.
@@ -53,22 +103,120 @@ typedef void(tf_http_cleanup_t)(void* user_data);
 */
 tf_http_t* tf_http_create(uv_loop_t* loop);
 
+/**
+** Register a trace instance with the HTTP instance to record the begin and end
+** time of request handlers.
+** @param http The HTTP instance to trace.
+** @param trace The trace instance to use, or NULL to disable.
+*/
 void tf_http_set_trace(tf_http_t* http, tf_trace_t* trace);
+
+/**
+** Begin listening for HTTP requests on a new port.  May be called multiple
+** times to listen on multiple ports.
+** @param http The HTTP instance.
+** @param port The port on which to listen, or 0 to assign a free port.
+** @param tls An optional TLS context to use for HTTPS requests.
+** @param cleanup A function called when the HTTP instance is being cleaned up.
+** @param user_data User data passed to the cleanup callback.
+** @return The port number on which the HTTP instance is now listening.
+*/
 int tf_http_listen(tf_http_t* http, int port, tf_tls_context_t* tls, tf_http_cleanup_t* cleanup, void* user_data);
+
+/**
+** Add an HTTP request handler.
+** @param http The HTTP instance.
+** @param pattern The prefix that the path of incoming requests must match to use this handler.
+** @param callback The function to be called to handle the request.
+** @param cleanup A function to be called when the request is complete.
+** @param user_data User data to pass to the callbacks.
+*/
 void tf_http_add_handler(tf_http_t* http, const char* pattern, tf_http_callback_t* callback, tf_http_cleanup_t* cleanup, void* user_data);
+
+/**
+** Respond to an HTTP request.
+** @param request The request.
+** @param status The HTTP status with which to respond.
+** @param headers Headers to include in the response.  Content-Length will be added internally.
+** @param headers_count The number of headers.  The headers array must have
+** twice as many entries as this value, since it is both keys and values.
+** @param body The response body or NULL.
+** @param content_length The length of the response body.
+*/
 void tf_http_respond(tf_http_request_t* request, int status, const char** headers, int headers_count, const void* body, size_t content_length);
+
+/**
+** Get the request body content.
+** @param request An incoming request.
+** @param out_data The request body content.  Valid until the request is completed.
+** @return The size of the request body content.
+*/
 size_t tf_http_get_body(const tf_http_request_t* request, const void** out_data);
+
+/**
+** Destroy an HTTP instance.
+** @param http The HTTP instance.
+*/
 void tf_http_destroy(tf_http_t* http);
 
+/**
+** Set instance-wide HTTP user data and a callback to clean it up.
+** @param http The HTTP instance.
+** @param user_data The user data.
+** @param cleanup The cleanup callback.
+*/
 void tf_http_set_user_data(tf_http_t* http, void* user_data, tf_http_cleanup_t* cleanup);
+
+/**
+** Get HTTP instance user data previous set with tf_http_set_user_data().
+** @param http The HTTP instance.
+** @return The user data.
+*/
 void* tf_http_get_user_data(tf_http_t* http);
 
+/**
+** Increment a requests refcount to keep it around after its callback.
+** tf_http_respond() may be called at a later time, and tf_http_request_unref()
+** must eventually be called in order to not leak the request.
+** @param request The request to retain.
+*/
 void tf_http_request_ref(tf_http_request_t* request);
+
+/**
+** Decrement a requests refcount.  tf_http_request_ref() must have been previously called.
+** @param request The request.
+*/
 void tf_http_request_unref(tf_http_request_t* request);
+
+/**
+** Get the value of a header from an HTTP request.
+** @param request The request.
+** @param name The header key.  Matched case insensitively.
+** @return The value or NULL.
+*/
 const char* tf_http_request_get_header(tf_http_request_t* request, const char* name);
+
+/**
+** Send a websocket message.
+** @param request The HTTP request which was previously updated to a websocket
+** session with tf_http_request_websocket_upgrade().
+** @param data The message data.
+** @param size The size of data.
+*/
 void tf_http_request_send(tf_http_request_t* request, const void* data, size_t size);
+
+/**
+** Upgrade an HTTP request to a websocket session.
+** @param request The HTTP request.
+*/
 void tf_http_request_websocket_upgrade(tf_http_request_t* request);
 
+/**
+** Get standard HTTP status text for common HTTP statuses.  200 = "OK", 404 =
+** "File not found", etc.
+** @param status The HTTP status.
+** @return The status text or NULL.
+*/
 const char* tf_http_status_text(int status);
 
 /** @} */