From 066daf21efef7fa4952d97d239bb5624318dbf6e Mon Sep 17 00:00:00 2001
From: goldsimon <goldsimon>
Date: Sat, 16 Jun 2007 14:33:37 +0000
Subject: [PATCH] Added comments for the callback functions included in structs
 tcp_pcb, udp_pcb and raw_pcb.

---
 src/include/lwip/raw.h | 11 ++++++++++
 src/include/lwip/tcp.h | 47 ++++++++++++++++++++++++++++++++++++------
 src/include/lwip/udp.h | 13 +++++++++++-
 3 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/src/include/lwip/raw.h b/src/include/lwip/raw.h
index 62a545ba..69c027b0 100644
--- a/src/include/lwip/raw.h
+++ b/src/include/lwip/raw.h
@@ -50,8 +50,19 @@ struct raw_pcb {
 
   u8_t protocol;
 
+  /* receive callback function
+   * @param arg user supplied argument (raw_pcb.recv_arg)
+   * @param pcb the raw_pcb which received data
+   * @param p the packet buffer that was received
+   * @param addr the remote IP address from which the packet was received
+   * @return 1 if the packet was 'eaten' (aka. deleted),
+   *         0 if the packet lives on
+   * If returning 1, the callback is responsible for freeing the pbuf
+   * if it's not used any more.
+   */
   u8_t (* recv)(void *arg, struct raw_pcb *pcb, struct pbuf *p,
     struct ip_addr *addr);
+  /* user-supplied argument for the recv callback */
   void *recv_arg;
 };
 
diff --git a/src/include/lwip/tcp.h b/src/include/lwip/tcp.h
index 3e4fdf78..c300681d 100644
--- a/src/include/lwip/tcp.h
+++ b/src/include/lwip/tcp.h
@@ -302,22 +302,57 @@ struct tcp_pcb {
 #endif /* TCP_QUEUE_OOSEQ */
 
 #if LWIP_CALLBACK_API
-  /* Function to be called when more send buffer space is available. */
+  /* Function to be called when more send buffer space is available.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param pcb the tcp_pcb which has send buffer space available
+   * @param space the amount of bytes available
+   * @return ERR_OK: try to send some data by calling tcp_output
+   */
   err_t (* sent)(void *arg, struct tcp_pcb *pcb, u16_t space);
   
-  /* Function to be called when (in-sequence) data has arrived. */
+  /* Function to be called when (in-sequence) data has arrived.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param pcb the tcp_pcb for which data has arrived
+   * @param p the packet buffer which arrived
+   * @param err an error argument (TODO: that is current always ERR_OK?)
+   * @return ERR_OK: try to send some data by calling tcp_output
+   */
   err_t (* recv)(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err);
 
-  /* Function to be called when a connection has been set up. */
+  /* Function to be called when a connection has been set up.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param pcb the tcp_pcb that now is connected
+   * @param err an error argument (TODO: that is current always ERR_OK?)
+   * @return value is currently ignored
+   */
   err_t (* connected)(void *arg, struct tcp_pcb *pcb, err_t err);
 
-  /* Function to call when a listener has been connected. */
+  /* Function to call when a listener has been connected.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param pcb a new tcp_pcb that now is connected
+   * @param err an error argument (TODO: that is current always ERR_OK?)
+   * @return ERR_OK: accept the new connection,
+   *                 any other err_t abortsthe new connection
+   */
   err_t (* accept)(void *arg, struct tcp_pcb *newpcb, err_t err);
 
-  /* Function which is called periodically. */
+  /* Function which is called periodically.
+   * The period can be adjusted in multiples of the TCP slow timer interval
+   * by changing tcp_pcb.polltmr.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param pcb the tcp_pcb to poll for
+   * @return ERR_OK: try to send some data by calling tcp_output
+   */
   err_t (* poll)(void *arg, struct tcp_pcb *pcb);
 
-  /* Function to be called whenever a fatal error occurs. */
+  /* Function to be called whenever a fatal error occurs.
+   * There is no pcb parameter since most of the times, the pcb is
+   * already deallocated (or there is no pcb) when this function is called.
+   * @param arg user-supplied argument (tcp_pcb.callback_arg)
+   * @param err an indication why the error callback is called:
+   *            ERR_ABRT: aborted through tcp_abort or by a TCP timer
+   *            ERR_RST: the connection was reset by the remote host
+   */
   void (* errf)(void *arg, err_t err);
 #endif /* LWIP_CALLBACK_API */
 
diff --git a/src/include/lwip/udp.h b/src/include/lwip/udp.h
index 5b7cd5d5..5a5bcb32 100644
--- a/src/include/lwip/udp.h
+++ b/src/include/lwip/udp.h
@@ -73,9 +73,20 @@ struct udp_pcb {
   u16_t chksum_len_rx, chksum_len_tx;
 #endif /* LWIP_UDPLITE */
 
-  /* addr and port are in same byte order as in the pcb */
+  /* receive callback function
+   * addr and port are in same byte order as in the pcb
+   * The callback is responsible for freeing the pbuf
+   * if it's not used any more.
+   *
+   * @param arg user supplied argument (udp_pcb.recv_arg)
+   * @param pcb the udp_pcb which received data
+   * @param p the packet buffer that was received
+   * @param addr the remote IP address from which the packet was received
+   * @param port the remote port from which the packet was received
+   */
   void (* recv)(void *arg, struct udp_pcb *pcb, struct pbuf *p,
     struct ip_addr *addr, u16_t port);
+  /* user-supplied argument for the recv callback */
   void *recv_arg;  
 };
 /* udp_pcbs export for exernal reference (e.g. SNMP agent) */