diff --git a/src/api/api_lib.c b/src/api/api_lib.c index 82da791a..03f083dd 100644 --- a/src/api/api_lib.c +++ b/src/api/api_lib.c @@ -1,7 +1,6 @@ /** * @file * Sequential API External module - * */ /* @@ -33,7 +32,29 @@ * This file is part of the lwIP TCP/IP stack. * * Author: Adam Dunkels - * + */ + +/** + * @defgroup netconn Netconn API + * Thread-safe, to be called from non-TCPIP threads only. + * TX/RX handling based on @ref netbuf (containing @ref pbuf) + * to avoid copying data around. + * + * @defgroup netconn_common Common functions + * @ingroup netconn + * For use with TCP and UDP + * + * @defgroup netconn_tcp TCP only + * @ingroup netconn + * TCP only functions + * + * @defgroup netconn_udp UDP only + * @ingroup netconn + * UDP only functions + * + * @defgroup netconn_dns DNS + * @ingroup netconn + * DNS lookup */ /* This is the part of the API that is linked with @@ -94,6 +115,7 @@ netconn_apimsg(tcpip_callback_fn fn, struct api_msg *apimsg) } /** + * @ingroup netconn_common * Create a new netconn (of a specific type) that has a callback function. * The corresponding pcb is also created. * @@ -138,6 +160,7 @@ netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, netconn_cal } /** + * @ingroup netconn_common * Close a netconn 'connection' and free its resources. * UDP and RAW connection are completely closed, TCP pcbs might still be in a waitstate * after this returns. @@ -181,6 +204,7 @@ netconn_delete(struct netconn *conn) } /** + * @ingroup netconn_tcp * Get the local or remote IP address and port of a netconn. * For RAW netconns, this returns the protocol instead of a port! * @@ -219,6 +243,7 @@ netconn_getaddr(struct netconn *conn, ip_addr_t *addr, u16_t *port, u8_t local) } /** + * @ingroup netconn_common * Bind a netconn to a specific local IP address and port. * Binding one netconn twice might not always be checked correctly! * @@ -252,6 +277,7 @@ netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port) } /** + * @ingroup netconn_common * Connect a netconn to a specific remote IP address and port. * * @param conn the netconn to connect @@ -283,6 +309,7 @@ netconn_connect(struct netconn *conn, const ip_addr_t *addr, u16_t port) } /** + * @ingroup netconn_udp * Disconnect a netconn from its current peer (only valid for UDP netconns). * * @param conn the netconn to disconnect @@ -305,6 +332,7 @@ netconn_disconnect(struct netconn *conn) } /** + * @ingroup netconn_tcp * Set a TCP netconn into listen mode * * @param conn the tcp netconn to set to listen mode @@ -341,6 +369,7 @@ netconn_listen_with_backlog(struct netconn *conn, u8_t backlog) } /** + * @ingroup netconn_tcp * Accept a new connection on a TCP listening netconn. * * @param conn the TCP listen netconn @@ -429,6 +458,7 @@ netconn_accept(struct netconn *conn, struct netconn **new_conn) } /** + * @ingroup netconn_common * Receive data: actual implementation that doesn't care whether pbuf or netbuf * is received * @@ -553,6 +583,7 @@ netconn_recv_data(struct netconn *conn, void **new_buf) } /** + * @ingroup netconn_tcp * Receive data (in form of a pbuf) from a TCP netconn * * @param conn the netconn from which to receive data @@ -571,6 +602,7 @@ netconn_recv_tcp_pbuf(struct netconn *conn, struct pbuf **new_buf) } /** + * @ingroup netconn_common * Receive data (in form of a netbuf containing a packet buffer) from a netconn * * @param conn the netconn from which to receive data @@ -630,6 +662,7 @@ netconn_recv(struct netconn *conn, struct netbuf **new_buf) } /** + * @ingroup netconn_udp * Send data (in form of a netbuf) to a specific remote IP address and port. * Only to be used for UDP and RAW netconns (not TCP). * @@ -651,6 +684,7 @@ netconn_sendto(struct netconn *conn, struct netbuf *buf, const ip_addr_t *addr, } /** + * @ingroup netconn_udp * Send data over a UDP or RAW netconn (that is already connected). * * @param conn the UDP or RAW netconn over which to send data @@ -676,6 +710,7 @@ netconn_send(struct netconn *conn, struct netbuf *buf) } /** + * @ingroup netconn_tcp * Send data over a TCP netconn. * * @param conn the TCP netconn over which to send data @@ -747,6 +782,7 @@ netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size, } /** + * @ingroup netconn_tcp * Close or shutdown a TCP netconn (doesn't delete it). * * @param conn the TCP netconn to close or shutdown @@ -783,6 +819,7 @@ netconn_close_shutdown(struct netconn *conn, u8_t how) } /** + * @ingroup netconn_tcp * Close a TCP netconn (doesn't delete it). * * @param conn the TCP netconn to close @@ -796,6 +833,7 @@ netconn_close(struct netconn *conn) } /** + * @ingroup netconn_tcp * Shut down one or both sides of a TCP netconn (doesn't delete it). * * @param conn the TCP netconn to shut down @@ -811,6 +849,7 @@ netconn_shutdown(struct netconn *conn, u8_t shut_rx, u8_t shut_tx) #if LWIP_IGMP || (LWIP_IPV6 && LWIP_IPV6_MLD) /** + * @ingroup netconn_udp * Join multicast groups for UDP netconns. * * @param conn the UDP netconn for which to change multicast addresses @@ -854,6 +893,7 @@ netconn_join_leave_group(struct netconn *conn, #if LWIP_DNS /** + * @ingroup netconn_dns * Execute a DNS query, only one IP address is returned * * @param name a string representation of the DNS host name to query diff --git a/src/api/netbuf.c b/src/api/netbuf.c index 9ab76a46..119ddafc 100644 --- a/src/api/netbuf.c +++ b/src/api/netbuf.c @@ -36,6 +36,13 @@ * */ +/** + * @defgroup netbuf Network buffers + * @ingroup netconn + * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally + * to avoid copying data around. + */ + #include "lwip/opt.h" #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */ @@ -46,6 +53,7 @@ #include /** + * @ingroup netbuf * Create (allocate) and initialize a new netbuf. * The netbuf doesn't yet contain a packet buffer! * @@ -79,6 +87,7 @@ netbuf *netbuf_new(void) } /** + * @ingroup netbuf * Deallocate a netbuf allocated by netbuf_new(). * * @param buf pointer to a netbuf allocated by netbuf_new() @@ -96,6 +105,7 @@ netbuf_delete(struct netbuf *buf) } /** + * @ingroup netbuf * Allocate memory for a packet buffer for a given netbuf. * * @param buf the netbuf for which to allocate a packet buffer @@ -123,6 +133,7 @@ netbuf_alloc(struct netbuf *buf, u16_t size) } /** + * @ingroup netbuf * Free the packet buffer included in a netbuf * * @param buf pointer to the netbuf which contains the packet buffer to free @@ -138,6 +149,7 @@ netbuf_free(struct netbuf *buf) } /** + * @ingroup netbuf * Let a netbuf reference existing (non-volatile) data. * * @param buf netbuf which should reference the data @@ -165,6 +177,7 @@ netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size) } /** + * @ingroup netbuf * Chain one netbuf to another (@see pbuf_chain) * * @param head the first netbuf @@ -181,6 +194,7 @@ netbuf_chain(struct netbuf *head, struct netbuf *tail) } /** + * @ingroup netbuf * Get the data pointer and length of the data inside a netbuf. * * @param buf netbuf to get the data from @@ -205,6 +219,7 @@ netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len) } /** + * @ingroup netbuf * Move the current data pointer of a packet buffer contained in a netbuf * to the next part. * The packet buffer itself is not modified. @@ -229,6 +244,7 @@ netbuf_next(struct netbuf *buf) } /** + * @ingroup netbuf * Move the current data pointer of a packet buffer contained in a netbuf * to the beginning of the packet. * The packet buffer itself is not modified. diff --git a/src/core/netif.c b/src/core/netif.c index f7cf758b..7d368e9f 100644 --- a/src/core/netif.c +++ b/src/core/netif.c @@ -35,7 +35,7 @@ */ /** - * @defgroup netif Network interface + * @defgroup netif Network interface (NETIF) */ #include "lwip/opt.h" diff --git a/src/core/pbuf.c b/src/core/pbuf.c index 9d9d6b86..26d7c875 100644 --- a/src/core/pbuf.c +++ b/src/core/pbuf.c @@ -4,7 +4,7 @@ */ /** - * @defgroup pbuf PBUF + * @defgroup pbuf Payload buffers (PBUF) * * Packets are built from the pbuf data structure. It supports dynamic * memory allocation for packet contents or can reference externally diff --git a/src/include/lwip/api.h b/src/include/lwip/api.h index c24db85a..a919a2d1 100644 --- a/src/include/lwip/api.h +++ b/src/include/lwip/api.h @@ -81,7 +81,7 @@ extern "C" { #endif /* LWIP_IPV6 */ - /* Helpers to process several netconn_types by the same code */ +/* Helpers to process several netconn_types by the same code */ #define NETCONNTYPE_GROUP(t) ((t)&0xF0) #define NETCONNTYPE_DATAGRAM(t) ((t)&0xE0) #if LWIP_IPV6 @@ -94,7 +94,9 @@ extern "C" { #define NETCONNTYPE_ISUDPNOCHKSUM(t) ((t) == NETCONN_UDPNOCHKSUM) #endif /* LWIP_IPV6 */ -/** Protocol family and type of the netconn */ +/** @ingroup netconn_common + * Protocol family and type of the netconn + */ enum netconn_type { NETCONN_INVALID = 0, /* NETCONN_TCP Group */ @@ -252,7 +254,10 @@ struct netconn { }} while(0); /* Network connection functions: */ + +/** @ingroup netconn_common */ #define netconn_new(t) netconn_new_with_proto_and_callback(t, 0, NULL) +/** @ingroup netconn_common */ #define netconn_new_with_callback(t, c) netconn_new_with_proto_and_callback(t, 0, c) struct netconn *netconn_new_with_proto_and_callback(enum netconn_type t, u8_t proto, netconn_callback callback); @@ -262,7 +267,9 @@ err_t netconn_delete(struct netconn *conn); err_t netconn_getaddr(struct netconn *conn, ip_addr_t *addr, u16_t *port, u8_t local); +/** @ingroup netconn_common */ #define netconn_peer(c,i,p) netconn_getaddr(c,i,p,0) +/** @ingroup netconn_common */ #define netconn_addr(c,i,p) netconn_getaddr(c,i,p,1) err_t netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port); @@ -278,6 +285,7 @@ err_t netconn_sendto(struct netconn *conn, struct netbuf *buf, err_t netconn_send(struct netconn *conn, struct netbuf *buf); err_t netconn_write_partly(struct netconn *conn, const void *dataptr, size_t size, u8_t apiflags, size_t *bytes_written); +/** @ingroup netconn_tcp */ #define netconn_write(conn, dataptr, size, apiflags) \ netconn_write_partly(conn, dataptr, size, apiflags, NULL) err_t netconn_close(struct netconn *conn);