API description of TCP and UDP for LwIP

Time:2022-1-7

01、TCP related APIs

1、tcp_arg()

This function is used to transfer the specific state to the application and is called after the control block flag is set up, that is, in the function tcp_. Cannot be called until new() is called

function

Specifies the specific state of the application that should be passed to all callback functions

prototype

void tcp_arg(struct tcp_pcb *pcb, void *arg)

parameter

PCB: the control block of the current TCP connection

Arg: parameter to be passed to callback function

return

nothing

2tcp_new()

This function defines a TCP_ After the PCB control block, it should be called first to establish the connection flag of the control block

function

Create a new connection flag (PCB)

prototype

struct tcp_pcb *tcp_new(void)

parameter

nothing

return

pcb:After the connection flag is established normally, the established PCB is returned

Null: when new PCB memory is unavailable

3tcp_bind()

This function binds the local IP address and port number. Users can bind it to any local IP address, and it can only be used in the function TCP_ Cannot be called until new() is called

function

Bind local IP address and port number

prototype

err_t tcp_bind (struct tcp_pcb *pcb, struct ip_addr *ipaddr, u16_t port)

parameter

PCB: prepare the bound connection, similar to sockets in BSD standard

IPADDR: the bound IP address. If IP_ ADDR_ Any, bind the connection to all local IP addresses

Port: the bound local port number. Note: never conflict with other applications

return

ERR_ OK: the specified connection is bound correctly

ERR_ Use: the specified port number has bound a connection, resulting in a conflict

4tcp_listen()

When a connection being requested is received, TCP_ The callback function specified by the accept() function will be called. Of course, before calling this function, you must first call the function TCP_ Bind() to bind a local IP address and port number

function

Causes the specified connection to enter the listening state

prototype

struct tcp_pcb *tcp_listen (struct tcp_pcb *pcb)

parameter

PCB: Specifies the connection to enter the listening state

return

pcb:Returns a new connection flag PCB, which is passed as a parameter to the function to be dispatched. The reason for doing so

Since the connection in the listening state generally requires only a small amount of memory, the TCP function is used_ Listen () retracts the original connection

And reallocate a smaller block of memory for listening connections.

Null: returns null when the connected memory block in listening state is unavailable. If so, pass it as a parameter to

Function TCP_ The memory occupied by the PCB of listen() cannot be allocated.

5、tcp_listen_with_backlog()

This function is the same as TCP_ Listen() is the same, but this function will limit the number of unprocessed connections in the listening queue, which is implemented through the parameter backlog. To use this function, you need to set the lwipopts Set TCP in H_ LISTEN_ BACKLOG=1。

function

Make the specified connection enter the listening state, but it will limit the number of connections in the listening queue

prototype

struct tcp_pcb *tcp_listen_with_backlog(struct tcp_pcb *pcb, u8_t backlog)

parameter

pcb:Specify the connection that will enter the listening state

backlog:Limit the number of connections in the listening queue

return

pcb:Returns a new connection flag PCB, which is passed as a parameter to the function to be dispatched. The reason for doing so

Since the connection in the listening state generally requires only a small amount of memory, the TCP function is used_ Listen() will retract the original

And reallocate a smaller memory block for listening connections.

Null: returns null when the connected memory block in listening state is unavailable. If so, pass it as a parameter

Give function TCP_ The memory occupied by the PCB of listen() cannot be allocated.

6tcp_accepted()

This function is usually called in the callback function of “accept”. It allows LwIP to perform some housekeeping work, such as putting new connections into the listening queue for processing.

function

Notify LwIP that a new connection has been received

prototype

void tcp_accepted(struct tcp_pcb *pcb)

parameter

pcb:Connections that have been received

return

nothing

7tcp_accept()

When the listening connection is connected to a new connection, the callback function specified by this function will be called. Usually in TCP_ Listen () calls after the function is called.

function

Specifies the callback function to be called after the listening connection is connected

prototype

void tcp_accept(struct tcp_pcb *pcb,

err_t (* accept)(void *arg,

struct tcp_pcb *newpcb,

err_t err))

parameter

PCB: specify a connection in listening state

Accept: Specifies the callback function to be called after the connection is connected

return

nothing

8tcp_connect()

The connection specified by the request parameter PCB connects to the remote host and sends the initial syn segment of the open connection. Function TCP_ Return immediately after the connect () call. It does not wait for the connection to be established correctly. If the connection is established correctly, it will directly call the function specified by the fourth parameter (connected parameter). On the contrary, if the connection cannot be established correctly, the reason may be that the remote host refuses to connect or the remote host does not respond. No matter what the reason is, the connected function will be called to set the corresponding parameter err

function

Requests the specified connection to connect to the remote host and sends the initial syn segment to open the connection

prototype

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))

parameter

PCB: specify a connection (PCB)

IPADDR: Specifies the IP address of the remote host

Port: Specifies the port number to connect to the remote host

Connected: Specifies the callback function that is called after the connection is established correctly.

return

ERR_ MEM: when the memory accessing the syn segment is unavailable, that is, the connection is not successfully established

ERR_ OK: when SYN is accessed correctly, the connection is successfully established

9tcp_write()

This function is used to send TCP data, but it does not send data immediately once called, but puts the specified data into the sending queue, which is determined by the protocol kernel. The size of available bytes in the send queue can be determined through the TCP function_ Sndbuf(). A more appropriate way to use this function is to use the function TCP_ Sndbuf () sends data based on the byte size returned by sndbuf (). If the function returns err_ MEM, the application waits until the data in the current send queue is successfully received by the remote host, and then tries to send the next data

function

Send TCP data

prototype

err_t tcp_write(struct tcp_pcb *pcb,

void *dataptr,

u16_t len,

u8_t copy)

parameter

PCB: Specifies the connection (PCB) to send

Dataptr: is a pointer to the data to be sent

Len: Specifies the length of data to be sent

Copy: This is a logical variable. It is 0 or 1. It specifies whether to allocate new memory space and the number to be sent

Copy it. If this parameter is 0, no new memory space will be allocated for the transmitted data, so it is not necessary to send

Data can only be accessed through the specified pointer

return

ERR_ MEM: if the length of the data exceeds the size of the current sending data buffer or the length of the segment queue to be sent

Length exceeds file lwipopts The upper limit (i.e. the maximum value) defined in H, then the function TCP_ Write() call failed

Failed, return err_ MEM

ERR_ OK: the data is correctly put into the sending queue, and err is returned_ OK

10tcp_sent()

This function is used to set the callback function called after the remote host successfully receives the data, usually in the function tcp_. After listen (), it is called.

function

Specifies the callback function called by the application when the remote host successfully receives data

prototype

void tcp_sent(struct tcp_pcb *pcb,

err_t (* sent)(void *arg,

struct tcp_pcb *tpcb,

u16_t len))

parameter

PCB: specifies a connection (PCB) to the remote host

Sent: Specifies the callback function that the remote host successfully receives after the data is received. “Len” is passed to the callback function as a parameter,

Give the maximum number of bytes sent last time that have been confirmed.

return

nothing

11tcp_recv()

This function is used to specify the callback function to be called when new data is received, usually in function TCP_ Call in the callback function specified by accept ().

function

Specifies the callback function to call when new data is received

prototype

void tcp_recv (struct tcp_pcb *pcb,

err_t (* recv)(void *arg,

struct tcp_pcb *tpcb,

struct pbuf *p,

err_t err))

parameter

PCB: specifies a connection (PCB) to the remote host

Recv: Specifies the callback function to be called when new data is received. The callback function can pass a null

The pbuf structure is used to indicate that the remote host has closed the connection. If no error occurs, the callback function returns

ERR_ OK, and the pbuf structure must be released. Otherwise, if an error occurs in the call to the function, it will be ignored

Never release the structure so that the LwIP kernel can save the structure and wait for later processing.

return

nothing

12tcp_recved()

When the application receives data, the function must be called to obtain the length of the received data, that is, the function should be in function TCP_ Call in the callback function specified by recv ().

function

Gets the length of the received data

prototype

void tcp_recved(struct tcp_pcb *pcb, u16_t len)

parameter

PCB: specifies a connection (PCB) to the remote host

Len: get the length of the received data

return

nothing

13tcp_poll()

This function must be called when using the polling function of LwIP. It is used to specify the polling time interval and the callback function that should be called during polling

function

Specify the polling interval and the callback function that should be called when polling the application

prototype

void tcp_poll(struct tcp_pcb *pcb,

err_t (* poll)(void *arg, struct tcp_pcb *tpcb),

u8_t interval)

parameter

PCB: specify a connection (PCB)

Poll: Specifies the callback function that should be called when polling the application

Interval: Specifies the polling interval. The time interval should be in TCP’s fine-grained timer, which is a typical setting

It’s twice a second. Setting the parameter “interval” to 10 means that the application will poll every 5 seconds.

return

nothing

14tcp_close()

function

Close a specified TCP connection. After calling this function, the TCP code will release (delete) the PCB structure

prototype

err_t tcp_close(struct tcp_pcb *pcb)

parameter

PCB: specify a connection (PCB) that needs to be closed

return

ERR_ MEM: this function returns err when no memory is available for the connection to be closed_ MEM。 If so

Then, the application will wait and close the connection again through a pre-established callback function or polling function

ERR_ OK: the connection is closed normally.

15tcp_abort()

This function aborts the connection by sending an RST (reset) segment to the remote host. The PCB structure will be released. This function will not fail. It must complete the purpose of abort. If the connection is aborted due to an error, the application will handle the event sensitively through the callback function. Usually, the connection interruption caused by sending error is caused by the shortage of memory resources. Set the callback function to handle errors through the TCP function_ Err().

function

Abort a specified connection (PCB)

prototype

void tcp_abort(struct tcp_pcb *pcb)

parameter

PCB: specify a connection (PCB) that needs to be closed

return

nothing

16tcp_err()

This function specifies the callback function that handles the error. A reliable and excellent application generally has to deal with possible errors, such as memory unavailability, which requires calling this function to specify a callback function to obtain error information

function

Specifies the callback function that handles the error

prototype

void tcp_err(struct tcp_pcb *pcb,

void (* err)(void *arg, err_t err))

parameter

PCB: Specifies the connection (PCB) for sending errors to be processed

Err: Specifies the callback function to call when sending an error. Because the PCB structure may have been deleted, it is processing errors

The PCB parameter in the callback function of cannot be passed in.

return

nothing

02. UDP related APIs

 1udp_new()

This function is used to establish a UDP control block (PCB) for UDP communication, but this PCB is not activated unless the PCB has been bound to a local address or connected to a remote host with a fixed address. Defining a UDP_ After the PCB control block, the function should be called first to establish the connection flag of the control block

function

Establish a UDP control block (PCB) for UDP communication

prototype

struct udp_pcb *udp_new(void)

parameter

nothing

return

udp_ PCB: the control block (PCB) of the established UDP connection

2udp_remove()

This function is used to delete a specified connection, usually after the control block is successfully established, that is, in the function UDP_ After the new () call, when the network connection is not needed for communication, it needs to be deleted to release the resources occupied by the connection (PCB).

function

Delete and release a UDP_ pcb

prototype

void udp_remove(struct udp_pcb *pcb)

parameter

PCB: Specifies the connection (PCB) to delete

return

nothing

3udp_bind()

This function binds the local IP address and port number. You can bind it to any local IP address, and it can only be used in the function UDP_ Cannot be called until new() is called

function

Bind the local IP address and port number for the specified connection

prototype

err_t udp_bind(struct udp_pcb *pcb,

struct ip_addr *ipaddr,

u16_t port)

parameter

PCB: specify a connection (PCB)

IPADDR: the bound local IP address. If IP_ ADDR_ Any, bind the connection to all local IP addresses

Port: the bound local port number. Note: never conflict with other applications

return

ERR_ OK: the specified connection is bound correctly

ERR_ Use: the specified port number has bound a connection, resulting in a conflict

4udp_connect()

This function connects a specified connection (PCB) to the remote host. Because UDP communication is for connectionless, it does not parameter any network traffic (network data sending and receiving). It only sets the IP address and port number of a remote connection.

function

Connect the connection control block specified by the parameter “PCB” to the remote host

prototype

err_t udp_connect(struct udp_pcb *pcb,

struct ip_addr *ipaddr,

u16_t port)

parameter

PCB: specify a connection (PCB)

IPADDR: sets the IP address of the connected remote host

Port: sets the port number of the connected remote host

return

ERR_ OK: connect to the remote host correctly

Other values: some error code flags of LwIP, indicating that the connection is not established correctly

5udp_disconnect()

This function closes the connection specified by the parameter “PCB”, which is the same as the function UDP_ Connect() works the opposite. Because UDP communication is for connectionless, this function also does not parameter any network traffic (network data sending and receiving), it only deletes the address of the remote connection

function

Close the connection specified by the parameter “PCB”, the same as the function UDP_ Connect() works the opposite way

prototype

void udp_disconnect(struct udp_pcb *pcb)

parameter

PCB: Specifies the connection (PCB) to delete

return

nothing

6udp_send()

This function uses UDP protocol to send pbufp pointed data. Called when data needs to be sent. After sending, the pbuf structure is not released. After calling this function, the data packet will be sent to the currently specified IP address and port number stored in PCB. If the PCB is not connected to a fixed port number, the function will automatically assign a port number randomly and send the data packet. Usually, the UDP function is called before calling_ connect()

function

Send pbuf P pointed data using UDP protocol

prototype

err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)

parameter

PCB: Specifies the connection (PCB) to send data

p: Contains the pbuf chain that needs to send data

return

ERR_ OK: the packet was sent successfully without any error

ERR_ MEM: memory unavailable

ERR_ RTE: unable to find route to remote host

Other values: other error codes indicate that an error has been sent

7udp_sendto()

This function is the same as UDP_ Send () has the same function, but it specifies the IP address and port number of the destination host, which is equivalent to UDP_ Connect() and UDP functions_ The effect of using send() together. However, if the UDP function has been called before calling the function_ Connect(), then the IP address and port number of the sending destination host will be subject to the specified in this function, which is determined by the function UDP_ The specified by connect() will be refreshed

function

Sends UDP data to a remote host with the specified IP address and port number

prototype

err_t udp_sendto(struct udp_pcb *pcb,

struct pbuf *p,

struct ip_addr *dst_ip,

u16_t dst_port)

parameter

PCB: Specifies the connection (PCB) to send data

p: Contains the pbuf chain that needs to send data

dst_ IP: the IP address of the remote host that sent the data

dst_ Port: the port number of the remote host to send data

return

Same function UDP_ The return value of send () is the same

8udp_recv()

This function is used to specify the callback function to be called when new UDP data is received. The parameters of the callback function will be passed into the IP address, port number, received data and other information of the remote host

function

Specifies a callback function to be called when a UDP packet is received

prototype

void udp_recv(struct udp_pcb *pcb,

void (* recv)(void *arg,

struct udp_pcb *upcb,

struct pbuf *p,

struct ip_addr *addr,

u16_t port),

void *recv_arg)

parameter

PCB: specify a connection (PCB)

Recv: Specifies the callback function when the packet is received

recv_ Arg: parameter passed to callback function

return

nothing

Click to view the album where this article is located,Stm32f207 network development