Changes: Application API layers

Revision as of 08:19, 2 March 2010

lwIP provides three Application Program's Interfaces (APIs) for programs to use for communication with the TCP/IP code:

low-level "core" / "callback" or "raw" API.
two higher-level "sequential" APIs:
- netconn API
- socket API (targeted at compatibility to posix- / BSD-sockets)

The sequential API provides a way for ordinary, sequential, programs to use the lwIP stack. It is quite similar to the BSD socket API. The model of execution is based on the blocking open-read-write-close paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP code and the application program must reside in different execution contexts (threads).

You have to be careful when mixing raw and sequential APIs: raw API functions really only may be called from the main tcpip_thread. Also, registering the callbacks (or initializing a pcb) must be done in that context (e.g. at startup time in tcpip_init_callback or at runtime using tcpip_callback).

Some more facts on the APIs to help you to decide which one to use in your application:

netconn- and raw-API are lwIP-only: code written in these APIs isn't portable to be re-used with other stacks
the socket API in contrast is targeted at portability with other posix OSes/stacks at the cost of lower throughput
socket- and netconn-API are sequential APIs that require threading (one thread for the application that uses the API, one thread for the stack to handle timers, incoming packets, etc.)
the raw API uses a callback mechanism (e.g. your application's callback is called when new data arrives). If you are used to program in a sequential way, this may be harder to implement.
the raw API gives the best performance since it does not require thread-changes
raw- and netconn-API support zero-copy both for TX and RX (although DMA-enabled MACs can prevent zero-copy-RX)

@@ Line 1: / Line 1: @@
-lwIP provides two Application Program's Interfaces (APIs) for programs to use for communication with the TCP/IP code:
+lwIP provides three Application Program's Interfaces (APIs) for programs to use for communication with the TCP/IP code:
 * low-level "core" / "callback" or "raw" API.
-* higher-level "sequential" API.
+* two higher-level "sequential" APIs:
+** netconn API
+** socket API (targeted at compatibility to posix- / BSD-sockets)
 The sequential API provides a way for ordinary, sequential, programs to use the lwIP stack. It is quite similar to the BSD socket API. The model of execution is based on the blocking open-read-write-close paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP code and the application program must reside in different execution contexts (threads).
 You have to be careful when mixing raw and sequential APIs: raw API functions really only may be called from the main tcpip_thread. Also, registering the callbacks (or initializing a pcb) must be done in that context (e.g. at startup time in tcpip_init_callback or at runtime using tcpip_callback).
+Some more facts on the APIs to help you to decide which one to use in your application:
+* netconn- and raw-API are lwIP-only: code written in these APIs isn't portable to be re-used with other stacks
+* the socket API in contrast is targeted at portability with other posix OSes/stacks at the cost of lower throughput
+* socket- and netconn-API are sequential APIs that require threading (one thread for the application that uses the API, one thread for the stack to handle timers, incoming packets, etc.)
+* the raw API uses a callback mechanism (e.g. your application's callback is called when new data arrives). If you are used to program in a sequential way, this may be harder to implement.
+* the raw API gives the best performance since it does not require thread-changes
+* raw- and netconn-API support zero-copy both for TX and RX (although DMA-enabled MACs can prevent zero-copy-RX)
 [[category:LwIP Application Developers Manual]]