物联网lwIP网络开发 1.3RAW API编程模型

---

Raw API 编程模型

Raw API

TCP connection setup

tcp_new

struct tcp_pcb *tcp_new(void)
//函数说明
  Creates a new connection identifier (PCB). If memory is not
  available for creating the new pcb, NULL is returned.
//参数
      void
//返回值
      new pcb

tcp_bind()

err_t tcp_bind(struct tcp_pcb *pcb, ip_addr_t *ipaddr,
                 u16_t port)
//函数说明
Binds the connection to a local port number and IP address. If the IP address is not given (i.e., ipaddr == IP_ANY_TYPE), the connection is bound to all local IP addresses. If another connection is bound to the same port, the function will return ERR_USE, otherwise ERR_OK is returned.
//参数
pcb	the tcp_pcb to bind (no check is done whether this pcb is already bound!)
ipaddr	the local ip address to bind to (use IPx_ADDR_ANY to bind to any local address
port	the local port to bind to
//返回值
ERR_USE if the port is already in use ERR_VAL if bind failed because the PCB is not in a valid state ERR_OK if bound

tcp_listen()

struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
  //函数说明
  Commands a pcb to start listening for incoming connections. When an
  incoming connection is accepted, the function specified with the
  tcp_accept() function will be called. The pcb will have to be bound
  to a local port with the tcp_bind() function.
  The tcp_listen() function returns a new connection identifier, and
  the one passed as an argument to the function will be
  deallocated. The reason for this behavior is that less memory is
  needed for a connection that is listening, so tcp_listen() will
  reclaim the memory needed for the original connection and allocate a
  new smaller memory block for the listening connection.
  tcp_listen() may return NULL if no memory was available for the
  listening connection. If so, the memory associated with the pcb
  passed as an argument to tcp_listen() will not be deallocated.
//参数
pcb	the original tcp_pcb
//返回值
tcp_pcb used for listening, consumes less memory.
//注意
The original tcp_pcb is freed. This function                                                                                                                  has to be called like this: tpcb = tcp_listen(tpcb);
    

tcp_accept

void tcp_accept(struct tcp_pcb *pcb,
                err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
                       err_t err))
//函数说明
  Specified the callback function that should be called when a new
  connection arrives on a listening connection.
//参数
pcb	the  tcp_pcb
err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
                       err_t err)   //回调函数

err_t (* accept)(void *arg, struct tcp_pcb *newpcb, err_t err)

/**
  * @brief  This function is the implementation of tcp_accept LwIP callback
  * @param  arg: not used
  * @param  newpcb: pointer on tcp_pcb struct for the newly created tcp connection
  * @param  err: not used 
  * @retval err_t: error status
  */

tcp_connect

err_t tcp_connect(struct tcp_pcb *pcb, ip_addr_t *ipaddr,u16_t port, err_t (* connected)(void *arg,struct tcp_pcb *tpcb,err_t err));
//函数说明
  Sets up the pcb to connect to the remote host and sends the
  initial SYN segment which opens the connection. 
  The tcp_connect() function returns immediately; it does not wait for
  the connection to be properly setup. Instead, it will call the
  function specified as the fourth argument (the "connected" argument)
  when the connection is established. If the connection could not be
  properly established, either because the other host refused the
  connection or because the other host didn't answer, the "err"
  callback function of this pcb (registered with tcp_err, see below)
  will be called.
  The tcp_connect() function can return ERR_MEM if no memory is
  available for enqueueing the SYN segment. If the SYN indeed was
  enqueued successfully, the tcp_connect() function returns ERR_OK.
//参数
pcb	the tcp_pcb used to establish the connection
ipaddr	the remote ip address to connect to
port	the remote tcp port to connect to
connected	callback function to call when connected (on error, the err calback will be called)
//返回值
ERR_VAL if invalid arguments are given ERR_OK if connect request has been sent other err_t values if connect request couldn't be sent

err_t (* connected)(void *arg,struct tcp_pcb *tpcb,err_t err)

/**
  * @brief Function called when TCP connection established
  * @param tpcb: pointer on the connection contol block
  * @param err: when connection correctly established err should be ERR_OK 
  * @retval err_t: returned error 
  */

Sending TCP data

tcp_write

err_t tcp_write(struct tcp_pcb *pcb, const void *dataptr, u16_t len,
                  u8_t apiflags)
//函数说明
Enqueues the data pointed to by the argument dataptr. The length of
the data is passed as the len parameter. The apiflags can be one or more of:
  - TCP_WRITE_FLAG_COPY: indicates whether the new memory should be allocated for the data to be copied into. If this flag is not given, no new memory should be allocated and the data should only be referenced by pointer. This also means that the memory behind dataptr must not change until the data is ACKed by the remote host
  - TCP_WRITE_FLAG_MORE: indicates that more data follows. If this is omitted,the PSH flag is set in the last segment created by this call to tcp_write.If this flag is given, the PSH flag is not set.
  The tcp_write() function will fail and return ERR_MEM if the length
  of the data exceeds the current send buffer size or if the length of
  the queue of outgoing segment is larger than the upper limit defined
  in lwipopts.h. The number of bytes available in the output queue can
  be retrieved with the tcp_sndbuf() function.
  The proper way to use this function is to call the function with at
  most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
  the application should wait until some of the currently enqueued
  data has been successfully received by the other host and try again.
//参数
pcb:Protocol control block for the TCP connection to enqueue data for.
arg:Pointer to the data to be enqueued for sending.
len:Data length in bytes
apiflags:combination of following flags :
TCP_WRITE_FLAG_COPY (0x01) data will be copied into memory belonging to the stack
TCP_WRITE_FLAG_MORE (0x02) for TCP connection, PSH flag will not be set on last segment sent,
//返回值
ERR_OK if enqueued, another err_t on error

tcp_sent

void tcp_sent(struct tcp_pcb *pcb,
                err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
                u16_t len))
//函数说明
  Specifies the callback function that should be called when data has
  successfully been received (i.e., acknowledged) by the remote
  host. The len argument passed to the callback function gives the
  amount bytes that was acknowledged by the last acknowledgment.
//参数

pcb	tcp_pcb to set the sent callback
sent callback function to call for this pcb when data is successfully sent
//返回值
ERR_OK if shutdown succeeded (or the PCB has already been shut down) another err_t on error.

Receiving TCP data

tcp_recv

void tcp_recv(struct tcp_pcb *pcb,
                err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
                               struct pbuf *p, err_t err))
//函数说明
  Sets the callback function that will be called when new data
  arrives. The callback function will be passed a NULL pbuf to
  indicate that the remote host has closed the connection. If
  there are no errors and the callback function is to return
  ERR_OK, then it must free the pbuf. Otherwise, it must not
  free the pbuf so that lwIP core code can store it.
//参数
pcb		tcp_pcb to set the recv callback
recv	callback function to call for this pcb when data is received

tcp_recved

void tcp_recved(struct tcp_pcb *pcb, u16_t len)
//函数说明
  Must be called when the application has received the data. The len
  argument indicates the length of the received data.

pcb	the tcp_pcb for which data is read
len	the amount of bytes that have been read by the application

Application polling

tcp_poll

tcp_poll(struct tcp_pcb *pcb, 
                err_t (* poll)(void *arg, struct tcp_pcb *tpcb),
                u8_t interval)
//函数说明
  Specifies the polling interval and the callback function that should
  be called to poll the application. The interval is specified in
  number of TCP coarse grained timer shots, which typically occurs
  twice a second. An interval of 10 means that the application would
  be polled every 5 seconds.
 

Closing and aborting connections

tcp_close

err_t tcp_close	(	struct tcp_pcb * 	pcb	)	
//函数说明
  Closes the connection. The function may return ERR_MEM if no memory
  was available for closing the connection. If so, the application
  should wait and try again either by using the acknowledgment
  callback or the polling functionality. If the close succeeds, the
  function returns ERR_OK.

  The pcb is deallocated by the TCP code after a call to tcp_close(). 

tcp_err

If a connection is aborted because of an error, the application is alerted of this event by the err callback. Errors that might abort a connection are when there is a shortage of memory. The callback function to be called is set using the tcp_err() function.

void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,err_t err))

  The error callback function does not get the pcb passed to it as a
  parameter since the pcb may already have been deallocated.

tcp_abort

void tcp_abort(struct tcp_pcb *pcb)
//函数说明
  Aborts the connection by sending a RST (reset) segment to the remote
  host. The pcb is deallocated. This function never fails.

  ATTENTION: When calling this from one of the TCP callbacks, make
  sure you always return ERR_ABRT (and never return ERR_ABRT otherwise
  or you will risk accessing deallocated memory or memory leaks!