mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2024-10-04 05:39:53 +00:00
Document netconn API in doxygen module style
This commit is contained in:
Dirk Ziegelmeier
parent
ce19c59bb2
commit
0fea2bc02e
@ -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 <adam@sics.se>
|
||||
*/
|
||||
|
||||
/**
|
||||
* @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
|
||||
|
||||
@ -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 <string.h>
|
||||
|
||||
/**
|
||||
* @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.
|
||||
|
||||
@ -35,7 +35,7 @@
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup netif Network interface
|
||||
* @defgroup netif Network interface (NETIF)
|
||||
*/
|
||||
|
||||
#include "lwip/opt.h"
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user