1 socket related API
In the OpenCPU solution, developers can use Socket API interface functions to implement TCP/UDP programming, and up to 8 Socket connections can be established. These API interface functions are defined in the zyf_socket.h file.
1.1 Usage
TCP client programming steps are as follows:
Step 1: Register. Call the ZYF_SocketRegister interface function to register the socket callback function.
Step 2: Create a socket. Call ZYF_SocketCreate to create a socket, the "contextId" parameter must use the same one in the ZYF_GprsRegister interface. "SocketType" must be set to SOC_TYPE_TCP.
Step 3: Link the socket. Call ZYF_SocketConnect interface function to request socket connection. The SOC_CONNECT message in the callback function registered in step 1 will indicate whether the link is successful.
Step 4: Send data through socket. Call ZYF_SocketSend to send data. After the data is sent, you can call the ZYF_SocketGetAckNumber interface to query whether the server has received the data. If ZYF_SocketSend returns SOC_WOULDBLOCK, the App must wait for the SOC_WRITE message in the callback function registered in step 1 to send data again.
Step 5: Receive data from the socket. When the server sends data to the device, the socket will receive the SOC_READ message notification in the callback function. At this time, the ZYF_SocketRecv interface can be called to receive data. App must read all data, otherwise when there is new data, the callback function message SOC_READ will
not be received .
Step 6: Close the socket. Call the ZYF_SocketClose interface function to close the socket. After processing the data, and the socket does not need to remain connected, the App can call this interface to close the socke. Or, when the App receives the SOC_CLOSE message notification, it means that the server has closed the socket. In this case, ZYF_SocketClose must also be called to close the client's socket.
1.2 Function API
1.2.1 SocketRegister
This function registers a callback function for the specified socket.
·Function prototype
int32_t ZYF_SocketRegister(int32_t socketId, ZYF_SocketCallBack_t Callback);
·Parameters
callback: Socket callback function
socketId: the return value of ZYF_SocketCreate()
·return value
socketId or other error codes. For more information, see Enum_SocErrCode.
1.2.2 SocketCreate
This function creates a socketID with a maximum value range of 6.
·Function prototype
int32_t ZYF_SocketCreate(uint8_t socketType);
·Parameter
socketType: socket type
·Return value
Success: socketId (equal to or greater than 0), failure: negative number. Refer to Enum_SocErrCode.
1.2.3 SocketClose
This function is used to close the specified socketId.
·Function prototype
int32_t ZYF_SocketClose(int32_t socketId);
·Parameter
socketId: the socketID to be closed.
·Return value
If the function succeeds, the return value will be SOC_SUCCESS(0); otherwise, the return value will be 0. Otherwise, a negative number (error code) will be returned.
1.2.4 SocketConnect
This function connects to a TCP server. The server is specified by the IP address and port number.
·Function prototype
int32_t ZYF_SocketConnect(int32_t socketId, uint8_t *ipAddr, uint16_t ipPort);
· Parameter
socketId: socketId
ipAddr: an address pointer to an IPv4 address. See usage examples.
ipPort: target port number.
· Return value
SOC_SUCCESS: The function succeeded. SOC_WOULDBLOCK: This return value is used in non-blocking mode. This means that the operation is in progress and needs to wait for callback_socket_connect() to get the result.
Other values: error code, please refer to Enum_SocErrCode.
1.2.5 SocketSend
This function is used to send data to a connected TCP socket.
·Function prototype
int32_t ZYF_SocketSend(int32_t socketId, uint8_t* pData, int32_t dataLen);
·Parameter
socketId: receiver socketID.
pData: pointer to data.
dataLen: The length of the data.
·Return value
If no error occurs, ZYF_SocketSend returns the total number of bytes sent, which can be less than the number of bytes requested to be sent in the dataLen parameter. Otherwise, it will return the value of Enum_SocErrCode.
1.2.6 SocketSendTo
This function sends data to a specific destination through a UDP socket.
·Function prototype
int32_t ZYF_SocketSendTo(int32_t socketId, uint8_t* pData, int32_t dataLen, uint8_t *ipAddr, uint16_t ipPort);
·Parameter
socketId: receiver socketID.
pData: pointer to data.
dataLen: The length of the data.
ipAddr: points to the address of the target socket.
ipPort: target port number.
·Return value
If no error occurs, this function returns the actual number of bytes sent. Otherwise, it will return the value of Enum_SocErrCode.
1.2.7 SocketGetAckNumber
This function is used to obtain the TCP socket ACK number.
·Function prototype
int32_t ZYF_SocketGetAckNumber(int32_t socketId, int32_t *ackNum);
·Parameter
socketId: socketID.
ackNum: points to an int32_t type variable, which is the storage space of TCP ACK number.
·Return value
If no error occurs, the return value is SOC_SUCCESS(). Otherwise, the return value "Enum_SocErrCode".
1.2.8 SocketRecv
This function is used to receive data from the bound socket.
·Function prototype
int32_t ZYF_SocketRecv(int32_t socketId, uint8_t* pBuffer, int32_t
bufferLen);
·Parameter
socketId: socketID.
pBuffer: A pointer used to store the received data.
·Return value
If no error occurs, ZYF_SocketRecv returns the total number of bytes received. Otherwise, return the value of Enum_SocErrCode.
1.2.9 SocketRecvFrom
This function is used to receive datagram data through a TCP socket.
·Function prototype
int32_t ZYF_SocketRecvFrom(int32_t socketId, uint8_t *pBuffer, int32_t recvLen, uint8_t *ipAddr, uint16_t *ipPort);
·Parameter
socketId: socketID.
pBuffer: A pointer used to store the received data.
recvLen: The length of the received data.
ipAddr: An optional pointer to the buffer that receives the address of the connection entity.
ipPort: An optional pointer to an integer that contains the port number of the connection entity.
·Return value
If no error occurs, ZYF_SocketRecv returns the total number of bytes received. Otherwise, return the value of Enum_SocErrCode.
1.2.10 SocketListen
This function puts the socket in a state so that it can monitor the upcoming connection in real time.
·Function prototype
int32_t ZYF_SocketListen(int32_t listenSocketId);
·Parameter
listenSocketId: the socketID to be monitored.
·Return value
If no error occurs, this function returns SOC_SUCCESS(0). Otherwise, return the value of Enum_SocErrCode.
1.2.11 SocketAccept
allows connection attempts on sockets.
·Function prototype
int32_t ZYF_SocketAccept(int32_t listenSocketId, uint8_t *ipAddr, uint16_t ipPort);
·Parameter
listenSocketId: the socketID being monitored.
ipAddr: An optional pointer to the buffer used to receive the address of the connected entity.
ipPort: An optional pointer to an integer that contains the port number of the connection entity.
·Return value
If no error occurs, this function returns a socket ID, which is used to send data to the tcp server. Greater than or equal to zero. Otherwise, it will return the value of Enum_SocErrCode.
1.2.12 GetIPByHostName
This function is used to retrieve the host IP corresponding to the host name.
·Function prototype
int32_t ZYF_GetIPByHostName(uint8_t contextId, char *hostName, ZYF_GetIpByNameCallBack_t callback);
·Parameter
contextId: OpenCPU supports two PDP environments to the target host at a time. This parameter can be 0 or 1.
hostName: host name.
callback: The system calls this callback to notify whether the host IP is successfully retrieved.
·Return value
If no error occurs, this function returns SOC_SUCCESS(0). Otherwise, the value of Enum_SocErrCode will be returned.
1.2.13 ConvertIpAddr
This function is used to check whether the IP address is a valid IP address. If "Yes", each segment of the IP address string will be converted to an integer for storage in the ipaddr parameter.
·Function prototype
int32_t ZYF_ConvertIpAddr(uint8_t *addrString, uint8_t* ipAddr);
·Parameter
addrString: IP address string.
ipAddr: points to an IPv4 address, each byte stores the IP number converted from the corresponding IP string.
·Return value
If no error occurs, this function returns SOC_SUCCESS(0). Otherwise, the value of Enum_SocErrCode will be returned.
1.2.14 SocketSetOpt
sets the options of the socket referenced by the file descriptor sockfd. Options may exist at multiple protocol levels. They are always at the top socket level.
·Function prototype
int32_t ZYF_SocketSetOpt(int32_t socketId, int level, int optname, const void *optval, int optlen );
·Parameter
socketId: socketId.
level: Protocol level.
optname: configuration name.
optval: configuration value.
optlen: configuration length.
·Return value
If no error occurs, this function returns SOC_SUCCESS (0). Otherwise, it will return the value of Enum_SocErrCode.
1.2.15 SocketGetOpt
sets the options of the socket referenced by the file descriptor sockfd. Options may exist at multiple protocol levels. They are always at the top socket level.
·Function prototype int32_t ZYF_SocketGetOpt(int32_t socketId, int level, int optname,
const void *optval, int optlen );
·Parameter
socketId: socketId.
level: Protocol level.
optname: configuration name.
optval: configuration value.
optlen: configuration length.
·Return value
If no error occurs, this function returns SOC_SUCCESS (0). Otherwise, it will return the value of Enum_SocErrCode.
2 Introduction to socket routines
Refer to the next section of the example: the use of TCP and UDP.