LWIP的TCP相关API

欢迎查看本文所在的系列，STM32的LWIP应用，点击跳转

1、tcp_arg()

该函数用于传递给应用程序的具体状态，在控制块标志建立以后调用，即在函数tcp_new()调用之后才能调用

功能	指定应该传递给所有回调函数的应用程序的具体状态
原型	void tcp_arg(struct tcp_pcb *pcb, void *arg)
参数	pcb： 当前TCP连接的控制块 arg： 需要传递给回调函数的参数
返回	无

2、tcp_new()

该函数在定义一个tcp_pcb控制块后应该首先被调用，以建立该控制块的连接标志

功能	建立一个新的连接标志(pcb)
原型	struct tcp_pcb *tcp_new(void)
参数	无
返回	pcb: 正常建立了连接标志，返回建立的pcb NULL：新的pcb内存不可用时

3、tcp_bind()

该函数用户绑定本地的IP地址和端口号，用户可以将其绑定在一个任意的本地IP地址上，它也只能在函数tcp_new()调用之后才能调用

功能	绑定本地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： 指定的端口号已经绑定了一个连接，产生了冲突

4、tcp_listen()

当一个正在请求的连接被接收时，由tcp_accept()函数指定的回调函数将会被调用。当然，在调用本函数前，必须首先调用函数tcp_bind()来绑定一个本地的IP地址和端口号

功能	使指定的连接开始进入监听状态
原型	struct tcp_pcb *tcp_listen (struct tcp_pcb *pcb)
参数	pcb：指定将要进入监听状态的连接
返回	pcb: 返回一个新的连接标志pcb，它作为一个参数传递给将要被分派的函数。这样做的原 因是处于监听状态的连接一般只需要较小的内存，于是函数tcp_listen()就会收回原始连接 的内存，而重新分配一个较小内存块供处于监听状态的连接使用。 NULL： 监听状态的连接的内存块不可用时，返回NULL。如果这样的话，作为参数传递给 函数tcp_listen()的pcb所占用的内存将不能够被分配。

5、tcp_listen_with_backlog()

该函数同tcp_listen()一样，但是该函数将限制在监听队列中未处理的连接的数量，这是通过参数backlog来实现的。要使用该函数，需要在配置文件lwipopts.h中设置TCP_LISTEN_BACKLOG=1。

功能	使指定的连接开始进入监听状态，但将会限制监听队列中连接的数量
原型	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所占用的内存将不能够被分配。

6、tcp_accepted()

这个函数通常在“accept”的回调函数中被调用。它允许LwIP去执行一些内务工作，例如，将新来的连接放入到监听队列中，以等待处理。

功能	通知LwIP一个新来的连接已经被接收
原型	void tcp_accepted(struct tcp_pcb *pcb)
参数	pcb: 已经被接收的连接
返回	无

7、tcp_accept()

当处于监听的连接与一个新来的连接连接上后， 该函数指定的回调函数将被调用。通常在tcp_listen()函数调用之后调用。

功能	指定处于监听状态的连接接通后将要调用的回调函数
原型	void tcp_accept(struct tcp_pcb *pcb, err_t (* accept)(void *arg, struct tcp_pcb *newpcb, err_t err))
参数	pcb： 指定一个处于监听状态的连接 accept：指定连接接通后将要调用的回调函数
返回	无

8、tcp_connect()

请求参数pcb指定的连接连接到远程主机，并发送打开连接的最初的SYN段。函数tcp_connect()调用后立即返回，它并不会等待连接一定要正确建立。如果当连接正确建立，那么它会直接调用第四个参数指定的函数(connected参数)。相反地，如果连接不能够被正确建立，这原因可能是远程主机拒绝连接，也可能是远程主机不应答，无论是什么原因，都会调用connected函数来设置相应的参数err

功能	请求指定的连接连接到远程主机，并发送打开连接的最初的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被正确地访问时，即连接成功建立

9、tcp_write()

该函数功能是发送TCP数据，但是并不是一经调用，就立即发送数据，而是将指定的数据放入到发送队列，由协议内核来决定发送。发送队列中可用字节的大小可以通过函数tcp_sndbuf()来重新获得。使用这个函数的一个比较恰当的方法是以函数tcp_sndbuf()返回的字节大小来发送数据。如果函数返回ERR_MEM，则应用程序就等待一会，直到当前发送队列中的数据被远程主机成功地接收，然后在尝试发送下一个数据

功能	发送TCP数据
原型	err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len, u8_t copy)
参数	pcb： 指定所要发送的连接(pcb) dataptr：是一个指针，它指向准备发送的数据 len： 指定要发送数据的长度 copy： 这是一个逻辑变量，它为0或者1，它指定是否分配新的内存空间，而把要发送的数 据复制进去。如果该参数为0，则不会为发送的数据分配新的内存空间，因而对发送 数据的访问只能通过指定的指针
返回	ERR_MEM：如果数据的长度超过了当前发送数据缓冲区的大小或者将要发送的段队列的 长度超过了文件lwipopts.h中定义的上限(即最大值)，则函数tcp_write()调用失 败，返回ERR_MEM ERR_OK：数据被正确地放入到发送队列中，返回ERR_OK

10、tcp_sent ()

该函数用于设定远程主机成功接收到数据后调用的回调函数，通常也在函数tcp_listen()之后调用。

功能	指定当远程主机成功地接收到数据后，应用程序调用的回调函数
原型	void tcp_sent(struct tcp_pcb *pcb, err_t (* sent)(void *arg, struct tcp_pcb *tpcb, u16_t len))
参数	pcb： 指定一个与远程主机相连接的连接(pcb) sent： 指定远程主机成功地接收到数据后调用的回调函数。“len”作为参数传递给回调函数， 给出上一次已经被确认的发送的最大字节数。
返回	无

11、tcp_recv ()

该函数用于指定当有新的数据接收到时调用的回调函数，通常在函数tcp_accept()指定的回调函数中调用。

功能	指定当新的数据接收到时调用的回调函数
原型	void tcp_recv (struct tcp_pcb *pcb, err_t (* recv)(void *arg, struct tcp_pcb *tpcb, struct pbuf *p, err_t err))
参数	pcb： 指定一个与远程主机相连接的连接(pcb) recv： 指定当新的数据接收到时调用的回调函数。该回调函数可以通过传递一个NULL的 pbuf结构用来指示远程主机已经关闭连接。如果没有错误发生，则回调函数返回 ERR_OK，并且必须释放掉pbuf结构。否则，如果函数的调用中发生错误，那么千 万不要释放该结构，以便LwIP内核可以保存该结构，从而等待以后处理。
返回	无

12、tcp_recved ()

当应用程序接收到数据的时候该函数必须被调用，用于获取接收到的数据的长度，即该函数应该在函数tcp_recv()指定的回调函数中调用。

功能	获取接收到的数据的长度
原型	void tcp_recved(struct tcp_pcb *pcb, u16_t len)
参数	pcb： 指定一个与远程主机相连接的连接(pcb) len： 获取接收到的数据的长度
返回	无

13、tcp_poll()

当使用LwIP的轮询功能时必须调用该函数，用于指定轮询的时间间隔及轮询时应该调用的回调函数

功能	指定轮询的时间间隔以及轮询应用程序时应该调用的回调函数
原型	void tcp_poll(struct tcp_pcb *pcb, err_t (* poll)(void *arg, struct tcp_pcb *tpcb), u8_t interval)
参数	pcb： 指定一个连接(pcb) poll： 指定轮询应用程序时应该调用的回调函数 interval：指定轮询的时间间隔。时间间隔应该以TCP的细粒度定时器为单位，典型的设置 是每秒钟两次。把参数“interval”设置为10意味着应用程序将每5秒钟轮询一次。
返回	无

14、tcp_close()

功能	关闭一个指定的TCP连接，调用该函数后，TCP代码将会释放(删除)pcb结构
原型	err_t tcp_close(struct tcp_pcb *pcb)
参数	pcb： 指定一个需要关闭的连接(pcb)
返回	ERR_MEM：当需要关闭的连接没有可用的内存时，该函数返回ERR_MEM。如果这样 的 话，应用程序将通过事先确立的回调函数或者是轮询功能来等待及重新关闭连接 ERR_OK：连接正常关闭。

15、tcp_abort()

该函数通过向远程主机发送一个RST(复位)段来中止连接。pcb结构将会被释放。该函数是不会失败的，它一定能完成中止的目的。

如果连接是因为一个错误而产生了中止，则应用程序会通过回调函数灵敏地处理这个事件。通常发送错误而引起的连接中止都是因为内存资源短缺引起的。设置处理错误的回调函数是通过函数tcp_err()来完成。

功能	中止一个指定的连接(pcb)
原型	void tcp_abort(struct tcp_pcb *pcb)
参数	pcb： 指定一个需要关闭的连接(pcb)
返回	无

16、tcp_err()

该函数用于指定处理错误的回调函数。一个可靠的优秀的应用程序一般都要处理可能出现的错误，如内存不可用等，这就需要调用该函数来指定一个回调函数来获取错误信息

功能	指定处理错误的回调函数
原型	void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg, err_t err))
参数	pcb： 指定需要处理的发送错误的连接(pcb) err： 指定发送错误时调用的回调函数。因为pcb结构可能已经被删除了，所以在处理错误 的回调函数中pcb参数不可能传递进来。
返回	无