API description of TCP and UDP for LwIP

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

2、tcp_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

3、tcp_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

4、tcp_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.

6、tcp_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

7、tcp_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

8、tcp_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

9、tcp_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

10、tcp_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

11、tcp_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

12、tcp_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

13、tcp_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

14、tcp_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.

15、tcp_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

16、tcp_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

1、udp_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

2、udp_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

3、udp_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

4、udp_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

5、udp_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

6、udp_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

7、udp_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

8、udp_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