From 5b33d33e3417a78f2c0f2707f1b39ea7ef118fbc Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Mon, 19 Feb 2018 09:01:44 +0100 Subject: [PATCH] Add HTTP client to documentation --- src/apps/http/http_client.c | 34 ++++++++++++++++++++++------- src/include/lwip/apps/http_client.h | 24 +++++++++++++++----- 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/src/apps/http/http_client.c b/src/apps/http/http_client.c index 88213a0f..3db772d8 100644 --- a/src/apps/http/http_client.c +++ b/src/apps/http/http_client.c @@ -32,7 +32,11 @@ * This file is part of the lwIP TCP/IP stack. * * Author: Simon Goldschmidt - * + */ + +/** + * @defgroup httpc HTTP client + * @ingroup apps * @todo: * - persistent connections * - select outgoing http version @@ -475,7 +479,7 @@ httpc_create_request_string(const httpc_connection_t *settings, const char* serv } /** Initialize the connection struct */ -err_t +static err_t httpc_init_connection_common(httpc_state_t **connection, const httpc_connection_t *settings, const char* server_name, u16_t server_port, const char* uri, altcp_recv_fn recv_fn, void* callback_arg, int use_host) { @@ -569,7 +573,10 @@ httpc_init_connection_common(httpc_state_t **connection, const httpc_connection_ return ERR_OK; } -/** Initialize the connection struct */ +/** + * @ingroup httpc + * Initialize the connection struct + */ err_t httpc_init_connection(httpc_state_t **connection, const httpc_connection_t *settings, const char* server_name, u16_t server_port, const char* uri, altcp_recv_fn recv_fn, void* callback_arg) @@ -578,7 +585,10 @@ httpc_init_connection(httpc_state_t **connection, const httpc_connection_t *sett } -/** Initialize the connection struct (from IP address) */ +/** + * @ingroup httpc + * Initialize the connection struct (from IP address) + */ err_t httpc_init_connection_addr(httpc_state_t **connection, const httpc_connection_t *settings, const ip_addr_t* server_addr, u16_t server_port, const char* uri, @@ -592,7 +602,9 @@ httpc_init_connection_addr(httpc_state_t **connection, const httpc_connection_t recv_fn, callback_arg, 1); } -/** HTTP client API: get a file by passing server IP address +/** + * @ingroup httpc + * HTTP client API: get a file by passing server IP address * * @param server_addr IP address of the server to connect * @param port tcp port of the server @@ -635,7 +647,9 @@ httpc_get_file(const ip_addr_t* server_addr, u16_t port, const char* uri, const return ERR_OK; } -/** HTTP client API: get a file by passing server name as string (DNS name or IP address string) +/** + * @ingroup httpc + * HTTP client API: get a file by passing server name as string (DNS name or IP address string) * * @param server_name server name as string (DNS name or IP address string) * @param port tcp port of the server @@ -775,7 +789,9 @@ httpc_fs_tcp_recv(void *arg, struct altcp_pcb *pcb, struct pbuf *p, err_t err) return ERR_OK; } -/** HTTP client API: get a file to disk by passing server IP address +/** + * @ingroup httpc + * HTTP client API: get a file to disk by passing server IP address * * @param server_addr IP address of the server to connect * @param port tcp port of the server @@ -825,7 +841,9 @@ httpc_get_file_to_disk(const ip_addr_t* server_addr, u16_t port, const char* uri return ERR_OK; } -/** HTTP client API: get a file to disk by passing server name as string (DNS name or IP address string) +/** + * @ingroup httpc + * HTTP client API: get a file to disk by passing server name as string (DNS name or IP address string) * * @param server_name server name as string (DNS name or IP address string) * @param port tcp port of the server diff --git a/src/include/lwip/apps/http_client.h b/src/include/lwip/apps/http_client.h index 26385124..899f47ac 100644 --- a/src/include/lwip/apps/http_client.h +++ b/src/include/lwip/apps/http_client.h @@ -42,12 +42,15 @@ #include "lwip/ip_addr.h" #include "lwip/err.h" #include "lwip/altcp.h" +#include "lwip/prot/iana.h" #ifdef __cplusplus extern "C" { #endif -/** HTTPC_HAVE_FILE_IO: define this to 1 to have functions dowloading directly +/** + * @ingroup httpc + * HTTPC_HAVE_FILE_IO: define this to 1 to have functions dowloading directly * to disk via fopen/fwrite. * These functions are example implementations of the interface only. */ @@ -55,9 +58,16 @@ extern "C" { #define LWIP_HTTPC_HAVE_FILE_IO 0 #endif -/** The default TCP port used for HTTP */ -#define HTTP_DEFAULT_PORT 80 +/** + * @ingroup httpc + * The default TCP port used for HTTP + */ +#define HTTP_DEFAULT_PORT LWIP_IANA_PORT_HTTP +/** + * @ingroup httpc + * HTTP client result codes + */ typedef enum ehttpc_result { /** File successfully received */ HTTPC_RESULT_OK = 0, @@ -81,7 +91,9 @@ typedef enum ehttpc_result { typedef struct _httpc_state httpc_state_t; -/** Prototype of a http client callback function +/** + * @ingroup httpc + * Prototype of a http client callback function * * @param arg argument specified when initiating the request * @param http_result result of the mail transfer (see enum httpc_result_t) @@ -92,7 +104,9 @@ typedef struct _httpc_state httpc_state_t; */ typedef void (*httpc_result_fn)(void *arg, httpc_result_t httpc_result, u32_t rx_content_len, u32_t srv_res, err_t err); -/** Prototype of http client callback: called when the headers are received +/** + * @ingroup httpc + * Prototype of http client callback: called when the headers are received * * @param connection http client connection * @param arg argument specified when initiating the request