RAW API参考手册
2.1 简介——回调函数
程序的执行是靠回调函数来驱动的。每一个回调函数也只不过是一个能够直接被TCP/IP代码调用的普通的C语言函数。每一个回调函数的调用都是传递一个当前连接UDP或TCP的状态。另外，为了使应用程序有一个明确的执行状态，回调函数的指定是可编程的，并且是独立于TCP/IP状态之外的。
剩下的部分我们将逐个来介绍LwIP提供的RAW API函数。
2.2 应用程序状态设置函数
1. tcp_arg()
该函数用于传递给应用程序的具体状态，在控制块标志建立以后调用，即在函数tcp_new()(请见表2.2)调用之后才能调用，该函数的详细描述请见表2.1。
表2.1 函数tcp_arg()
功能
指定应该传递给所有回调函数的应用程序的具体状态
原型
void tcp_arg(struct tcp_pcb *pcb, void *arg)
参数
pcb： 当前TCP连接的控制块
arg： 需要传递给回调函数的参数
返回
无
2.3 建立TCP连接函数
建立连接的函数同sequential API以及BSD标准的socket
API都非常相似。一个新的TCP连接的标志(实质上是一个协议控制块-PCB)由tcp_new()函数来创建。连接创建后，该PCB可以进入监听状态，等待数据接收的连接信号，也可以直接连接另外一个主机。
1. tcp_new()
该函数在定义一个tcp_pcb控制块后应该首先被调用，以建立该控制块的连接标志。该函数的详细描述请见表2.2。
表2.2 函数tcp_new()
功能
建立一个新的连接标志(pcb)
原型
struct tcp_pcb *tcp_new(void)
参数
无
返回
pcb: 正常建立了连接标志，返回建立的pcb
NULL：新的pcb内存不可用时
2. tcp_bind()
该函数用户绑定本地的IP地址和端口号，用户可以将其绑定在一个任意的本地IP地址上，它也只能在函数tcp_new()(请见表2.2)调用之后才能调用。该函数的详细描述请见表
2.3。
工程技术笔记 ©2008 Guangzhou ZHIYUAN Electronics CO., LTD..
2
广州致远电子有限公司
TCP/IP 协议栈应用
LwIP 的 RAW API 接口及编程指南
表 2.3 函数tcp_bind()
功能
绑定本地IP地址和端口号
原型
err_t tcp_bind (struct tcp_pcb *pcb, struct ip_addr *ipaddr, u16_t
port)
参数
pcb： 准备绑定的连接，类似于BSD标准中的Sockets
ipaddr：绑定的IP地址。如果为IP_ADDR_ANY，则将连接绑定到所有的本地IP地址上
port： 绑定的本地端口号。注意：千万不要和其它的应用程序产生冲突
返回
ERR_OK： 正确地绑定了指定的连接
ERR_USE： 指定的端口号已经绑定了一个连接，产生了冲突
3. tcp_listen()
当一个正在请求的连接被接收时，由tcp_accept()(请见表
2.7)函数指定的回调函数将会被调用。当然，在调用本函数前，必须首先调用函数tcp_bind()(请见表
2.3)来绑定一个本地的IP地址和端口号。该函数的详细描述请见表2.4。
表2.4 函数tcp_listen()
功能
使指定的连接开始进入监听状态
原型
struct tcp_pcb *tcp_listen (struct tcp_pcb *pcb)
参数
pcb：指定将要进入监听状态的连接
返回
pcb:
返回一个新的连接标志pcb，它作为一个参数传递给将要被分派的函数。这样做的原因是处于监听状态的连接一般只需要较小的内存，于是函数tcp_listen()就会收回原始连接的内存，而重新分配一个较小内存块供处于监听状态的连接使用。
NULL：监听状态的连接的内存块不可用时，返回NULL。如果这样的话，作为参数传递给函数tcp_listen()的pcb所占用的内存将不能够被分配。
4. tcp_listen_with_backlog()
该函数同tcp_listen()一样，但是该函数将限制在监听队列中未处理的连接的数量，这是通过参数backlog来实现的。要使用该函数，需要在配置文件lwipopts.h中设置TCP_LISTEN_BACKLOG=1。该函数的详细描述请见表2.5。
表2.5 函数tcp_listen_with_backlog()
功能
使指定的连接开始进入监听状态，但将会限制监听队列中连接的数量
原型
struct tcp_pcb *tcp_listen_with_backlog(struct tcp_pcb *pcb, u8_t
backlog)
参数
pcb: 指定将要进入监听状态的连接
backlog: 限制监听队列中连接的数量
返回
pcb:
返回一个新的连接标志pcb，它作为一个参数传递给将要被分派的函数。这样做的原因是处于监听状态的连接一般只需要较小的内存，于是函数tcp_listen()就会收回原始连接的内存，而重新分配一个较小内存块供处于监听状态的连接使用。
NULL：监听状态的连接的内存块不可用时，返回NULL。如果这样的话，作为参数传递给函数tcp_listen()的pcb所占用的内存将不能够被分配。
5. tcp_accepted()
这个函数通常在“accept”的回调函数中被调用。它允许LwIP去执行一些内务工作，例
工程技术笔记 ©2008 Guangzhou ZHIYUAN Electronics CO., LTD..
3
广州致远电子有限公司
TCP/IP 协议栈应用
LwIP 的 RAW API 接口及编程指南
如，将新来的连接放入到监听队列中，以等待处理。该函数的详细描述请见表2.6。
表2.6 函数tcp_accepted()
功能
通知LwIP一个新来的连接已经被接收
原型
void tcp_accepted(struct tcp_pcb *pcb)
参数
pcb: 已经被接收的连接
返回
无
6. tcp_accept()
当处于监听的连接与一个新来的连接连接上后，该函数指定的回调函数将被调用。通常在tcp_listen()(请见表2.4)函数调用之后调用。该函数的详细描述请见表
2.7。
表 2.7 函数tcp_accept()
功能
指定处于监听状态的连接接通后将要调用的回调函数
原型
void tcp_accept(struct tcp_pcb *pcb,
err_t (* accept)(void *arg,
struct tcp_pcb *newpcb,
err_t err))
参数
pcb： 指定一个处于监听状态的连接
accept：指定连接接通后将要调用的回调函数
返回
无
7. tcp_connect()
请求参数pcb指定的连接连接到远程主机，并发送打开连接的最初的SYN段。函数tcp_connect()调用后立即返回，它并不会等待连接一定要正确建立。如果当连接正确建立，那么它会直接调用第四个参数指定的函数(connected参数)。相反地，如果连接不能够被正确建立，这原因可能是远程主机拒绝连接，也可能是远程主机不应答，无论是什么原因，都会调用connected函数来设置相应的参数err。该函数的详细描述请见表
2.8。
表 2.8 函数tcp_connect()
功能
请求指定的连接连接到远程主机，并发送打开连接的最初的SYN段
原型
err_t tcp_connect(struct tcp_pcb *pcb,
struct ip_addr *ipaddr,
u16_t port,
err_t (* connected)(void *arg,
struct tcp_pcb *tpcb,
err_t err))
参数
pcb： 指定一个连接(pcb)
ipaddr： 指定连接远程主机的IP地址
port： 指定连接远程主机的端口号
connected：指定连接正确建立后调用的回调函数
返回
ERR_MEM：当访问SYN段的内存不可用时，即连接没有成功建立
ERR_OK： 当SYN被正确地访问时，即连接成功建立
工程技术笔记 ©2008 Guangzhou ZHIYUAN Electronics CO., LTD..
4
广州致远电子有限公司
TCP/IP 协议栈应用
LwIP 的 RAW API 接口及编程指南
2.4 TCP数据发送函数
LwIP通过调用函数tcp_write()来发送TCP数据。当数据被成功地发送到远程主机后，应用程序将会收到应答从而去调用一个指定的回调函数。
1. tcp_write()
该函数功能是发送TCP数据，但是并不是一经调用，就立即发送数据，而是将指定的数据放入到发送队列，由协议内核来决定发送。发送队列中可用字节的大小可以通过函数tcp_sndbuf()来重新获得。使用这个函数的一个比较恰当的方法是以函数tcp_sndbuf()返回的字节大小来发送数据。如果函数返回ERR_MEM，则应用程序就等待一会，直到当前发送队列中的数据被远程主机成功地接收，然后在尝试发送下一个数据。该函数的详细描述请见表2.9。
表2.9 函数tcp_write()
功能
发送TCP数据
原型
err_t tcp_write(struct tcp_pcb *pcb,
void *dataptr,
u16_t len,
u8_t copy)
参数
pcb： 指定所要发送的连接(pcb)
dataptr：是一个指针，它指向准
