doc/rawapi.txt

   1 Raw TCP/IP interface for lwIP 0.5
   2
   3 Author: Adam Dunkels
   4
   5 lwIP provides two Application Program's Interfaces (APIs) for programs
   6 to use for communication with the TCP/IP code: the sequential API
   7 (often just called "the API") and the raw TCP/IP interface. This
   8 document is intended as a description of the latter. For lwIP versions
   9 lower than 0.5, this API was not documented.
  10
  11 The sequential API provides a way for ordinary, sequential, programs
  12 to use the lwIP stack. It is quite similar to the BSD socket API. The
  13 model of execution is based on the open-read-write-close
  14 paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
  15 code and the application program must reside in different execution
  16 contexts (threads).
  17
  18 The raw TCP/IP interface allows the application program to integrate
  19 better with the TCP/IP code. Program execution is event based by
  20 having callback functions being called from within the TCP/IP
  21 code. The TCP/IP code and the application program both run in the same
  22 thread. The sequential API has a much higher overhead and is not very
  23 well suited for small systems since it forces a multithreaded paradigm
  24 on the application.
  25
  26 The raw TCP/IP interface is not only faster in terms of code execution
  27 time but is also less memory intensive. The drawback is that program
  28 development is somewhat harder and application programs written for
  29 the raw TCP/IP interface are more difficult to understand. Still, this
  30 is the preferred way of writing applications that should be small in
  31 code size and memory usage.
  32
  33 Both APIs can be used simultaneously by different application
  34 programs. In fact, the sequential API is implemented as an application
  35 program using the raw TCP/IP interface.
  36
  37
  38 --- Callbacks
  39
  40 Program execution is driven by callbacks. Each callback is an ordinary
  41 C function that is called from within the TCP/IP code. Every callback
  42 function is passed the current TCP or UDP connection state as an
  43 argument. Also, in order to be able to keep program specific state,
  44 the callback functions are called with a program specified argument
  45 that is independent of the TCP/IP state.
  46
  47 The function for setting the application connection state is:
  48
  49 - void tcp_arg(struct tcp_pcb *pcb, void *arg)
  50
  51   Specifies the program specific state that should be passed to all
  52   other callback functions. The "pcb" argument is the current TCP
  53   connection control block, and the "arg" argument is the argument
  54   that will be passed to the callbacks.
  55
  56
  57 --- TCP connection setup
  58
  59 The functions used for setting up connections is similar to that of
  60 the sequential API and of the BSD socket API. A new TCP connection
  61 identifier (i.e., a protocol control block - PCB) is created with the
  62 tcp_new() function. This PCB can then be either set to listen for new
  63 incoming connections or be explicitly connected to another host.
  64
  65 - struct tcp_pcb *tcp_new(void)
  66
  67   Creates a new connection identifier (PCB). If memory is not
  68   available for creating the new pcb, NULL is returned.
  69
  70 - err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
  71                  u16_t port)
  72
  73   Binds the pcb to a local IP address and port number. The IP address
  74   can be specified as IP_ADDR_ANY in order to bind the connection to
  75   all local IP addresses.
  76
  77   If another connection is bound to the same port, the function will
  78   return ERR_USE, otherwise ERR_OK is returned.
  79
  80 - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
  81
  82   Commands a pcb to start listening for incoming connections. When an
  83   incoming connection is accepted, the function specified with the
  84   tcp_accept() function will be called. The pcb will have to be bound
  85   to a local port with the tcp_bind() function.
  86
  87   The tcp_listen() function returns a new connection identifier, and
  88   the one passed as an argument to the function will be
  89   deallocated. The reason for this behavior is that less memory is
  90   needed for a connection that is listening, so tcp_listen() will
  91   reclaim the memory needed for the original connection and allocate a
  92   new smaller memory block for the listening connection.
  93
  94   tcp_listen() may return NULL if no memory was available for the
  95   listening connection. If so, the memory associated with the pcb
  96   passed as an argument to tcp_listen() will not be deallocated.
  97
  98 - void tcp_accept(struct tcp_pcb *pcb,
  99                   err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
 100                                    err_t err))
 101
 102   Specified the callback function that should be called when a new
 103   connection arrives on a listening connection.
 104
 105 - err_t tcp_connect(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
 106                     u16_t port, err_t (* connected)(void *arg,
 107                                                     struct tcp_pcb *tpcb,
 108                                                     err_t err));
 109
 110   Sets up the pcb to connect to the remote host and sends the
 111   initial SYN segment which opens the connection.
 112
 113   The tcp_connect() function returns immediately; it does not wait for
 114   the connection to be properly setup. Instead, it will call the
 115   function specified as the fourth argument (the "connected" argument)
 116   when the connection is established. If the connection could not be
 117   properly established, either because the other host refused the
 118   connection or because the other host didn't answer, the "connected"
 119   function will be called with an the "err" argument set accordingly.
 120
 121   The tcp_connect() function can return ERR_MEM if no memory is
 122   available for enqueueing the SYN segment. If the SYN indeed was
 123   enqueued successfully, the tcp_connect() function returns ERR_OK.
 124
 125
 126 --- Sending TCP data
 127
 128 TCP data is sent by enqueueing the data with a call to
 129 tcp_write(). When the data is successfully transmitted to the remote
 130 host, the application will be notified with a call to a specified
 131 callback function.
 132
 133 - err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len,
 134                   u8_t copy)
 135
 136   Enqueues the data pointed to by the argument dataptr. The length of
 137   the data is passed as the len parameter. The copy argument is either
 138   0 or 1 and indicates whether the new memory should be allocated for
 139   the data to be copied into. If the argument is 0, no new memory
 140   should be allocated and the data should only be referenced by
 141   pointer.
 142
 143   The tcp_write() function will fail and return ERR_MEM if the length
 144   of the data exceeds the current send buffer size or if the length of
 145   the queue of outgoing segment is larger than the upper limit defined
 146   in lwipopts.h. The number of bytes available in the output queue can
 147   be retrieved with the tcp_sndbuf() function.
 148
 149   The proper way to use this function is to call the function with at
 150   most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
 151   the application should wait until some of the currently enqueued
 152   data has been successfully received by the other host and try again.
 153
 154 - void tcp_sent(struct tcp_pcb *pcb,
 155                 err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
 156                                u16_t len))
 157
 158   Specifies the callback function that should be called when data has
 159   successfully been received (i.e., acknowledged) by the remote
 160   host. The len argument passed to the callback function gives the
 161   amount bytes that was acknowledged by the last acknowledgment.
 162
 163
 164 --- Receiving TCP data
 165
 166 TCP data reception is callback based - an application specified
 167 callback function is called when new data arrives. When the
 168 application has taken the data, it has to call the tcp_recved()
 169 function to indicate that TCP can advertise increase the receive
 170 window.
 171
 172 - void tcp_recv(struct tcp_pcb *pcb,
 173                 err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
 174                                struct pbuf *p, err_t err))
 175
 176   Sets the callback function that will be called when new data
 177   arrives. The callback function will be passed a NULL pbuf to
 178   indicate that the remote host has closed the connection.
 179
 180 - void tcp_recved(struct tcp_pcb *pcb, u16_t len)
 181
 182   Must be called when the application has received the data. The len
 183   argument indicates the length of the received data.
 184
 185
 186 --- Application polling
 187
 188 When a connection is idle (i.e., no data is either transmitted or
 189 received), lwIP will repeatedly poll the application by calling a
 190 specified callback function. This can be used either as a watchdog
 191 timer for killing connections that have stayed idle for too long, or
 192 as a method of waiting for memory to become available. For instance,
 193 if a call to tcp_write() has failed because memory wasn't available,
 194 the application may use the polling functionality to call tcp_write()
 195 again when the connection has been idle for a while.
 196
 197 - void tcp_poll(struct tcp_pcb *pcb, u8_t interval,
 198                 err_t (* poll)(void *arg, struct tcp_pcb *tpcb))
 199
 200   Specifies the polling interval and the callback function that should
 201   be called to poll the application. The interval is specified in
 202   number of TCP coarse grained timer shots, which typically occurs
 203   twice a second. An interval of 10 means that the application would
 204   be polled every 5 seconds.
 205
 206
 207 --- Closing and aborting connections
 208
 209 - err_t tcp_close(struct tcp_pcb *pcb)
 210
 211   Closes the connection. The function may return ERR_MEM if no memory
 212   was available for closing the connection. If so, the application
 213   should wait and try again either by using the acknowledgment
 214   callback or the polling functionality. If the close succeeds, the
 215   function returns ERR_OK.
 216
 217   The pcb is deallocated by the TCP code after a call to tcp_close().
 218
 219 - void tcp_abort(struct tcp_pcb *pcb)
 220
 221   Aborts the connection by sending a RST (reset) segment to the remote
 222   host. The pcb is deallocated. This function never fails.
 223
 224 If a connection is aborted because of an error, the application is
 225 alerted of this event by the err callback. Errors that might abort a
 226 connection are when there is a shortage of memory. The callback
 227 function to be called is set using the tcp_err() function.
 228
 229 - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,
 230                err_t err))
 231
 232   The error callback function does not get the pcb passed to it as a
 233   parameter since the pcb may already have been deallocated.
 234
 235
 236 --- Lower layer TCP interface
 237
 238 TCP provides a simple interface to the lower layers of the
 239 system. During system initialization, the function tcp_init() has
 240 to be called before any other TCP function is called. When the system
 241 is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
 242 must be called with regular intervals. The tcp_fasttmr() should be
 243 called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
 244 tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
 245
 246
 247 --- UDP interface
 248
 249 The UDP interface is similar to that of TCP, but due to the lower
 250 level of complexity of UDP, the interface is significantly simpler.
 251
 252 - struct udp_pcb *udp_new(void)
 253
 254   Creates a new UDP pcb which can be used for UDP communication. The
 255   pcb is not active until it has either been bound to a local address
 256   or connected to a remote address.
 257
 258 - void udp_remove(struct udp_pcb *pcb)
 259
 260   Removes and deallocates the pcb.
 261
 262 - err_t udp_bind(struct udp_pcb *pcb, struct ip_addr *ipaddr,
 263                  u16_t port)
 264
 265   Binds the pcb to a local address. The IP-address argument "ipaddr"
 266   can be IP_ADDR_ANY to indicate that it should listen to any local IP
 267   address. The function currently always return ERR_OK.
 268
 269 - err_t udp_connect(struct udp_pcb *pcb, struct ip_addr *ipaddr,
 270                     u16_t port)
 271
 272   Sets the remote end of the pcb. This function does not generate any
 273   network traffic, but only set the remote address of the pcb.
 274
 275 - err_t udp_disconnect(struct udp_pcb *pcb)
 276
 277   Remove the remote end of the pcb. This function does not generate
 278   any network traffic, but only removes the remote address of the pcb.
 279
 280 - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
 281
 282   Sends the pbuf p. The pbuf is not deallocated.
 283
 284 - void udp_recv(struct udp_pcb *pcb,
 285                 void (* recv)(void *arg, struct udp_pcb *upcb,
 286                                          struct pbuf *p,
 287                                          struct ip_addr *addr,
 288                                          u16_t port),
 289                               void *recv_arg)
 290
 291   Specifies a callback function that should be called when a UDP
 292   datagram is received.