Lines Matching full:the
6 to use for communication with the TCP/IP code:
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 blocking 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
18 The socket API is a compatibility API for existing applications,
19 currently it is built on top of the sequential API. It is meant to
22 in the specification of this API, there might be incompatibilities
28 threading support, instead of making the core thread-safe, another
29 approach was chosen: there is one main thread running the lwIP core
30 (also known as the "tcpip_thread"). The raw API may only be used from
31 this thread! Application threads using the sequential- or socket API
34 As such, the list of functions that may be called from
53 be called from an ISR: otherwise, the HEAP is only
57 ** The remainder of this document discusses the "raw" API. **
59 The raw TCP/IP interface allows the application program to integrate
60 better with the TCP/IP code. Program execution is event based by
61 having callback functions being called from within the TCP/IP
62 code. The TCP/IP code and the application program both run in the same
63 thread. The sequential API has a much higher overhead and is not very
65 on the application.
67 The raw TCP/IP interface is not only faster in terms of code execution
68 time but is also less memory intensive. The drawback is that program
70 the raw TCP/IP interface are more difficult to understand. Still, this
71 is the preferred way of writing applications that should be small in
75 programs. In fact, the sequential API is implemented as an application
76 program using the raw TCP/IP interface.
81 C function that is called from within the TCP/IP code. Every callback
82 function is passed the current TCP or UDP connection state as an
84 the callback functions are called with a program specified argument
85 that is independent of the TCP/IP state.
87 The function for setting the application connection state is:
91 Specifies the program specific state that should be passed to all
92 other callback functions. The "pcb" argument is the current TCP
93 connection control block, and the "arg" argument is the argument
94 that will be passed to the callbacks.
99 The functions used for setting up connections is similar to that of
100 the sequential API and of the BSD socket API. A new TCP connection
101 identifier (i.e., a protocol control block - PCB) is created with the
108 available for creating the new pcb, NULL is returned.
113 Binds the pcb to a local IP address and port number. The IP address
114 can be specified as IP_ADDR_ANY in order to bind the connection to
117 If another connection is bound to the same port, the function will
123 incoming connection is accepted, the function specified with the
124 tcp_accept() function will be called. The pcb will have to be bound
125 to a local port with the tcp_bind() function.
127 The tcp_listen() function returns a new connection identifier, and
128 the one passed as an argument to the function will be
129 deallocated. The reason for this behavior is that less memory is
131 reclaim the memory needed for the original connection and allocate a
132 new smaller memory block for the listening connection.
134 tcp_listen() may return NULL if no memory was available for the
135 listening connection. If so, the memory associated with the pcb
140 Same as tcp_listen, but limits the number of outstanding connections
141 in the listen queue to the value specified by the backlog argument.
147 usually be called from the accept callback. This allows lwIP to perform
149 queued in the listen backlog.
150 ATTENTION: the PCB passed in must be the listening pcb, not the pcb passed
151 into the accept callback!
157 Specified the callback function that should be called when a new
165 Sets up the pcb to connect to the remote host and sends the
166 initial SYN segment which opens the connection.
168 The tcp_connect() function returns immediately; it does not wait for
169 the connection to be properly setup. Instead, it will call the
170 function specified as the fourth argument (the "connected" argument)
171 when the connection is established. If the connection could not be
172 properly established, either because the other host refused the
173 connection or because the other host didn't answer, the "err"
177 The tcp_connect() function can return ERR_MEM if no memory is
178 available for enqueueing the SYN segment. If the SYN indeed was
179 enqueued successfully, the tcp_connect() function returns ERR_OK.
184 TCP data is sent by enqueueing the data with a call to
185 tcp_write(). When the data is successfully transmitted to the remote
186 host, the application will be notified with a call to a specified
192 Enqueues the data pointed to by the argument dataptr. The length of
193 the data is passed as the len parameter. The apiflags can be one or more of:
194 - TCP_WRITE_FLAG_COPY: indicates whether the new memory should be allocated
195 for the data to be copied into. If this flag is not given, no new memory
196 should be allocated and the data should only be referenced by pointer. This
197 also means that the memory behind dataptr must not change until the data is
198 ACKed by the remote host
200 the PSH flag is set in the last segment created by this call to tcp_write.
201 If this flag is given, the PSH flag is not set.
203 The tcp_write() function will fail and return ERR_MEM if the length
204 of the data exceeds the current send buffer size or if the length of
205 the queue of outgoing segment is larger than the upper limit defined
206 in lwipopts.h. The number of bytes available in the output queue can
207 be retrieved with the tcp_sndbuf() function.
209 The proper way to use this function is to call the function with at
210 most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
211 the application should wait until some of the currently enqueued
212 data has been successfully received by the other host and try again.
218 Specifies the callback function that should be called when data has
219 successfully been received (i.e., acknowledged) by the remote
220 host. The len argument passed to the callback function gives the
221 amount bytes that was acknowledged by the last acknowledgment.
227 callback function is called when new data arrives. When the
228 application has taken the data, it has to call the tcp_recved()
229 function to indicate that TCP can advertise increase the receive
236 Sets the callback function that will be called when new data
237 arrives. The callback function will be passed a NULL pbuf to
238 indicate that the remote host has closed the connection. If
239 there are no errors and the callback function is to return
240 ERR_OK, then it must free the pbuf. Otherwise, it must not
241 free the pbuf so that lwIP core code can store it.
245 Must be called when the application has received the data. The len
246 argument indicates the length of the received data.
252 received), lwIP will repeatedly poll the application by calling a
257 the application may use the polling functionality to call tcp_write()
258 again when the connection has been idle for a while.
264 Specifies the polling interval and the callback function that should
265 be called to poll the application. The interval is specified in
267 twice a second. An interval of 10 means that the application would
275 Closes the connection. The function may return ERR_MEM if no memory
276 was available for closing the connection. If so, the application
277 should wait and try again either by using the acknowledgment
278 callback or the polling functionality. If the close succeeds, the
281 The pcb is deallocated by the TCP code after a call to tcp_close().
285 Aborts the connection by sending a RST (reset) segment to the remote
286 host. The pcb is deallocated. This function never fails.
288 ATTENTION: When calling this from one of the TCP callbacks, make
293 If a connection is aborted because of an error, the application is
294 alerted of this event by the err callback. Errors that might abort a
295 connection are when there is a shortage of memory. The callback
296 function to be called is set using the tcp_err() function.
301 The error callback function does not get the pcb passed to it as a
302 parameter since the pcb may already have been deallocated.
307 TCP provides a simple interface to the lower layers of the
308 system. During system initialization, the function tcp_init() has
309 to be called before any other TCP function is called. When the system
310 is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
311 must be called with regular intervals. The tcp_fasttmr() should be
318 The UDP interface is similar to that of TCP, but due to the lower
319 level of complexity of UDP, the interface is significantly simpler.
323 Creates a new UDP pcb which can be used for UDP communication. The
329 Removes and deallocates the pcb.
334 Binds the pcb to a local address. The IP-address argument "ipaddr"
336 address. The function currently always return ERR_OK.
341 Sets the remote end of the pcb. This function does not generate any
342 network traffic, but only set the remote address of the pcb.
346 Remove the remote end of the pcb. This function does not generate
347 any network traffic, but only removes the remote address of the pcb.
351 Sends the pbuf p. The pbuf is not deallocated.
366 A truly complete and generic sequence for initializing the lwip stack
367 cannot be given because it depends on the build configuration (lwipopts.h)
370 We can give you some idea on how to proceed when using the raw API.
371 We assume a configuration using a single Ethernet netif and the
372 UDP and TCP transport layers, IPv4 and the DHCP client.
374 Call these functions in the order of appearance:
378 Clears the structure where runtime statistics are gathered.
382 Not of much use since we set the NO_SYS 1 option in lwipopts.h,
387 Initializes the dynamic memory heap defined by MEM_SIZE.
391 Initializes the memory pools defined by MEMP_NUM_x.
395 Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
399 Initializes the ARP table and queue.
409 Clears the UDP PCB list.
413 Clears the TCP PCB list and clears some internal TCP timers.
414 Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
422 Adds your network interface to the netif_list. Allocate a struct
423 netif and pass a pointer to this structure as the first argument.
425 or fill them with sane numbers otherwise. The state pointer may be NULL.
427 The init function pointer must point to a initialization function for
428 your ethernet netif interface. The following code illustrates it's use.
439 For ethernet drivers, the input function pointer must point to the lwip
445 Registers the default network interface.
449 When the netif is fully configured this function must be called.
453 Creates a new DHCP client for this interface on the first call.
455 the predefined regular intervals after starting the client.
457 You can peek in the netif->dhcp struct for the actual DHCP status.
462 The first thing you want to optimize is the lwip_standard_checksum()
464 function with the #define LWIP_CHKSUM <your_checksum_routine>.
478 a higher speed than the maximum wire-speed. If the
482 E.g. when using the cs8900 driver, call cs8900if_service(ethif)
483 as frequently as possible. When using an RTOS let the cs8900 interrupt
490 high values to the memory options.
492 For more optimization hints take a look at the lwIP wiki.
496 To achieve zero-copy on transmit, the data passed to the raw API must
497 remain unchanged until sent. Because the send- (or write-)functions return
498 when the packets have been enqueued for sending, data must be kept stable
502 must *not* be reused by the application unless their ref-count is 1.
505 but the stack/driver will/must copy PBUF_REF'ed data when enqueueing, while
508 Also, data passed to tcp_write without the copy-flag must not be changed!