CMSIS-Driver
Version 2.8.0
Peripheral Interface for Middleware and Application Code
|
Socket interface to IP stack running on WiFi module. More...
Content | |
WiFi Socket Address Family definitions | |
WiFi Socket Address Family definitions. | |
WiFi Socket Type definitions | |
WiFi Socket Type definitions. | |
WiFi Socket Protocol definitions | |
WiFi Socket Protocol definitions. | |
WiFi Socket Option definitions | |
WiFi Socket Option definitions. | |
WiFi Socket Function return codes | |
WiFi Socket Function return codes. | |
Functions | |
int32_t | ARM_WIFI_SocketCreate (int32_t af, int32_t type, int32_t protocol) |
Create a communication socket. More... | |
int32_t | ARM_WIFI_SocketBind (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port) |
Assign a local address to a socket. More... | |
int32_t | ARM_WIFI_SocketListen (int32_t socket, int32_t backlog) |
Listen for socket connections. More... | |
int32_t | ARM_WIFI_SocketAccept (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port) |
Accept a new connection on a socket. More... | |
int32_t | ARM_WIFI_SocketConnect (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port) |
Connect a socket to a remote host. More... | |
int32_t | ARM_WIFI_SocketRecv (int32_t socket, void *buf, uint32_t len) |
Receive data or check if data is available on a connected socket. More... | |
int32_t | ARM_WIFI_SocketRecvFrom (int32_t socket, void *buf, uint32_t len, uint8_t *ip, uint32_t *ip_len, uint16_t *port) |
Receive data or check if data is available on a socket. More... | |
int32_t | ARM_WIFI_SocketSend (int32_t socket, const void *buf, uint32_t len) |
Send data or check if data can be sent on a connected socket. More... | |
int32_t | ARM_WIFI_SocketSendTo (int32_t socket, const void *buf, uint32_t len, const uint8_t *ip, uint32_t ip_len, uint16_t port) |
Send data or check if data can be sent on a socket. More... | |
int32_t | ARM_WIFI_SocketGetSockName (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port) |
Retrieve local IP address and port of a socket. More... | |
int32_t | ARM_WIFI_SocketGetPeerName (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port) |
Retrieve remote IP address and port of a socket. More... | |
int32_t | ARM_WIFI_SocketGetOpt (int32_t socket, int32_t opt_id, void *opt_val, uint32_t *opt_len) |
Get socket option. More... | |
int32_t | ARM_WIFI_SocketSetOpt (int32_t socket, int32_t opt_id, const void *opt_val, uint32_t opt_len) |
Set socket option. More... | |
int32_t | ARM_WIFI_SocketClose (int32_t socket) |
Close and release a socket. More... | |
int32_t | ARM_WIFI_SocketGetHostByName (const char *name, int32_t af, uint8_t *ip, uint32_t *ip_len) |
Retrieve host IP address from host name. More... | |
int32_t | ARM_WIFI_Ping (const uint8_t *ip, uint32_t ip_len) |
Probe remote host with Ping command. More... | |
Socket interface to IP stack running on WiFi module.
The WiFi Socket functions provide the interface to an IP stack that is running on the WiFi module. This IP stack handles data communication with the network and provides the user with a communication endpoint called sockets.
int32_t ARM_WIFI_SocketCreate | ( | int32_t | af, |
int32_t | type, | ||
int32_t | protocol | ||
) |
Create a communication socket.
[in] | af | Address family |
[in] | type | Socket type |
[in] | protocol | Socket protocol |
The function ARM_WIFI_SocketCreate creates a communication endpoint called a socket.
The argument af specifies the address family. The following values are supported:
Family | Description |
---|---|
ARM_SOCKET_AF_INET | Address Family Internet |
ARM_SOCKET_AF_INET6 | Address Family Internet version 6 |
The argument type specifies the communication semantics. The following are the currently supported types:
Type | Description |
---|---|
ARM_SOCKET_SOCK_STREAM | Provides a reliable connection based data stream that is full-duplex |
ARM_SOCKET_SOCK_DGRAM | Provides connectionless communication that is unreliable |
The argument protocol specifies the protocol that must be used with the socket type:
Protocol | Description |
---|---|
ARM_SOCKET_IPPROTO_TCP | Must be used with ARM_SOCKET_SOCK_STREAM socket type |
ARM_SOCKET_IPPROTO_UDP | Must be used with ARM_SOCKET_SOCK_DGRAM socket type |
0 | The system selects a matching protocol for the socket type |
Example:
int32_t ARM_WIFI_SocketBind | ( | int32_t | socket, |
const uint8_t * | ip, | ||
uint32_t | ip_len, | ||
uint16_t | port | ||
) |
Assign a local address to a socket.
[in] | socket | Socket identification number |
[in] | ip | Pointer to local IP address |
[in] | ip_len | Length of 'ip' address in bytes |
[in] | port | Local port number |
The function ARM_WIFI_SocketBind assigns a name to an unnamed socket. The name represents the local address and port of the communication endpoint.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument ip is a pointer to the buffer containing the IP address octets of the local IP address.
The argument ip_len specifies the length of the local IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.
The argument port specifies the local port. If the argument port is 0, the function returns error, because this port is reserved.
Example:
int32_t ARM_WIFI_SocketListen | ( | int32_t | socket, |
int32_t | backlog | ||
) |
Listen for socket connections.
[in] | socket | Socket identification number |
[in] | backlog | Number of connection requests that can be queued |
The function ARM_WIFI_SocketListen sets the specified socket to listening mode, that is to the server mode of operation. Before calling the ARM_WIFI_SocketListen function, the ARM_WIFI_SocketBind function must be called.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument backlog specifies a maximum number of connection requests that can be queued.
Example:
int32_t ARM_WIFI_SocketAccept | ( | int32_t | socket, |
uint8_t * | ip, | ||
uint32_t * | ip_len, | ||
uint16_t * | port | ||
) |
Accept a new connection on a socket.
[in] | socket | Socket identification number |
[out] | ip | Pointer to buffer where address of connecting socket shall be returned (NULL for none) |
[in,out] | ip_len | Pointer to length of 'ip' (or NULL if 'ip' is NULL)
|
[out] | port | Pointer to buffer where port of connecting socket shall be returned (NULL for none) |
The function ARM_WIFI_SocketAccept accepts a connection request queued for a listening socket. If a connection request is pending, ARM_WIFI_SocketAccept removes the request from the queue, and creates a new socket for the connection. The original listening socket remains open and continues to queue new connection requests. The socket must be a socket of type ARM_SOCKET_SOCK_STREAM.
In blocking mode, which is enabled by default, this function waits for a connection request. In non blocking mode, you must call the ARM_WIFI_SocketAccept function again if the error code ARM_SOCKET_EAGAIN
is returned.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument ip is a pointer to the buffer that will receive the IP address of the connection node. If the ip is NULL, the IP address is not returned.
The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.
The argument port is a pointer to the buffer, that will receive the port number of the connection node. If the port is NULL, the port number is not returned.
Example:
int32_t ARM_WIFI_SocketConnect | ( | int32_t | socket, |
const uint8_t * | ip, | ||
uint32_t | ip_len, | ||
uint16_t | port | ||
) |
Connect a socket to a remote host.
[in] | socket | Socket identification number |
[in] | ip | Pointer to remote IP address |
[in] | ip_len | Length of 'ip' address in bytes |
[in] | port | Remote port number |
The function ARM_WIFI_SocketConnect assigns the address of the peer communication endpoint. The function behaves differently according to the type of socket:
ARM_SOCKET_SOCK_STREAM: A connection is established between the endpoints.
In blocking mode, which is enabled by default, this function waits for a connection to be established.
In non blocking mode, the function returns the error code ARM_SOCKET_EINPROGRESS
and the connection is established asynchronously. Subsequent calls to ARM_WIFI_SocketConnect for the same socket, before the connection is established, return the error code ARM_SOCKET_EALREADY
. When the connection is established, the call to ARM_WIFI_SocketConnect returns the error code ARM_SOCKET_EISCONN
.
ARM_SOCKET_SOCK_DGRAM: An address filter is established between the endpoints.
The address filter is changed with another ARM_WIFI_SocketConnect function call. If the socket is not yet bound, the system implicitly binds to a random dynamic port.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument ip is a pointer to the buffer containing the IP address octets of the endpoint node.
The argument ip_len specifies the length of the IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.
The argument port specifies the port of the endpoint node. If the argument port is 0, the function returns error, because this port is reserved.
Example:
int32_t ARM_WIFI_SocketRecv | ( | int32_t | socket, |
void * | buf, | ||
uint32_t | len | ||
) |
Receive data or check if data is available on a connected socket.
[in] | socket | Socket identification number |
[out] | buf | Pointer to buffer where data should be stored |
[in] | len | Length of buffer (in bytes), set len = 0 to check if data is available |
The function ARM_WIFI_SocketRecv receives incoming data that has been queued for the socket. You can use this function with both, the stream and the datagram socket. It reads as much information as currently available up to the size of the buffer specified.
In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the ARM_WIFI_SocketRecv function again if the error code ARM_SOCKET_EAGAIN
is returned.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of a datagram sockets. For stream sockets, the data is buffered internally so the application can retrieve all data by multiple calls of ARM_WIFI_SocketRecv function.
The argument len specifies the size of the application data buffer.
Example:
int32_t ARM_WIFI_SocketRecvFrom | ( | int32_t | socket, |
void * | buf, | ||
uint32_t | len, | ||
uint8_t * | ip, | ||
uint32_t * | ip_len, | ||
uint16_t * | port | ||
) |
Receive data or check if data is available on a socket.
[in] | socket | Socket identification number |
[out] | buf | Pointer to buffer where data should be stored |
[in] | len | Length of buffer (in bytes), set len = 0 to check if data is available |
[out] | ip | Pointer to buffer where remote source address shall be returned (NULL for none) |
[in,out] | ip_len | Pointer to length of 'ip' (or NULL if 'ip' is NULL)
|
[out] | port | Pointer to buffer where remote source port shall be returned (NULL for none) |
The function ARM_WIFI_SocketRecvFrom is used to receive data that has been queued for a socket. It is normally used to receive messages on datagram sockets, but can also be used to receive a reliable, ordered stream of data on a connected stream sockets. It reads as much information as currently available up to the size of the buffer specified.
In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the ARM_WIFI_SocketRecv function again if the error code ARM_SOCKET_EAGAIN
is returned.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of a datagram sockets. For stream sockets, the data is buffered internally so the application can retrieve all data by multiple calls of ARM_WIFI_SocketRecv function.
The argument len specifies the size of the application data buffer.
The argument ip is a pointer to the buffer that will receive the IP address of the sender. If the ip is NULL, the IP address is not returned.
The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.
The argument port is a pointer to the buffer, that will receive the port number of the sender. If the port is NULL, the port number is not returned.
Example:
int32_t ARM_WIFI_SocketSend | ( | int32_t | socket, |
const void * | buf, | ||
uint32_t | len | ||
) |
Send data or check if data can be sent on a connected socket.
[in] | socket | Socket identification number |
[in] | buf | Pointer to buffer containing data to send |
[in] | len | Length of data (in bytes), set len = 0 to check if data can be sent |
The function ARM_WIFI_SocketSend is used to send data on an already connected socket. This function is normally used to send a reliable, ordered stream of data bytes on a stream sockets. It can also be used to send messages on datagram sockets.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the ARM_WIFI_SocketSend function will fragment the data and send it in several successive data packets:
The argument len specifies the length of data in bytes.
Return value, when positive, represents the number of bytes sent, which can be less than len.
Example:
int32_t ARM_WIFI_SocketSendTo | ( | int32_t | socket, |
const void * | buf, | ||
uint32_t | len, | ||
const uint8_t * | ip, | ||
uint32_t | ip_len, | ||
uint16_t | port | ||
) |
Send data or check if data can be sent on a socket.
[in] | socket | Socket identification number |
[in] | buf | Pointer to buffer containing data to send |
[in] | len | Length of data (in bytes), set len = 0 to check if data can be sent |
[in] | ip | Pointer to remote destination IP address |
[in] | ip_len | Length of 'ip' address in bytes |
[in] | port | Remote destination port number |
The function ARM_WIFI_SocketSendTo is used to send data. It is normally used to send messages on a datagram sockets, but can also be used to send data on a connected stream sockets.
If the datagram socket is not yet bound, the system implicitly binds to a random dynamic port.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the ARM_WIFI_SocketSend function will fragment the data and send it in several successive data packets:
The argument len specifies the length of data in bytes.
The argument ip is a pointer to the buffer containing the IP address octets of the endpoint node.
The argument ip_len specifies the length of the IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.
The argument port specifies the port of the endpoint node. If the argument port is 0, the function returns error, because this port is reserved.
For the stream sockets, arguments ip, ip_len and port are ignored.
Return value, when positive, represents the number of bytes sent, which can be less than len.
Example:
int32_t ARM_WIFI_SocketGetSockName | ( | int32_t | socket, |
uint8_t * | ip, | ||
uint32_t * | ip_len, | ||
uint16_t * | port | ||
) |
Retrieve local IP address and port of a socket.
[in] | socket | Socket identification number |
[out] | ip | Pointer to buffer where local address shall be returned (NULL for none) |
[in,out] | ip_len | Pointer to length of 'ip' (or NULL if 'ip' is NULL)
|
[out] | port | Pointer to buffer where local port shall be returned (NULL for none) |
The function ARM_WIFI_SocketGetSockName retrieves the local IP address and port for a socket.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument ip is a pointer to the buffer that will receive the local IP address. If the ip is NULL, the local IP address is not returned.
The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.
The argument port is a pointer to the buffer, that will receive the local port number. If the port is NULL, the local port number is not returned.
Example:
int32_t ARM_WIFI_SocketGetPeerName | ( | int32_t | socket, |
uint8_t * | ip, | ||
uint32_t * | ip_len, | ||
uint16_t * | port | ||
) |
Retrieve remote IP address and port of a socket.
[in] | socket | Socket identification number |
[out] | ip | Pointer to buffer where remote address shall be returned (NULL for none) |
[in,out] | ip_len | Pointer to length of 'ip' (or NULL if 'ip' is NULL)
|
[out] | port | Pointer to buffer where remote port shall be returned (NULL for none) |
The function ARM_WIFI_SocketGetPeerName retrieves the IP address and port of the peer to which a socket is connected.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument ip is a pointer to the buffer that will receive the IP address of the peer. If the ip is NULL, the IP address is not returned.
The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.
The argument port is a pointer to the buffer, that will receive the port number of the peer. If the port is NULL, the port number is not returned.
Example:
int32_t ARM_WIFI_SocketGetOpt | ( | int32_t | socket, |
int32_t | opt_id, | ||
void * | opt_val, | ||
uint32_t * | opt_len | ||
) |
Get socket option.
[in] | socket | Socket identification number |
[in] | opt_id | Option identifier |
[out] | opt_val | Pointer to the buffer that will receive the option value |
[in,out] | opt_len | Pointer to length of the option value
|
The function ARM_WIFI_SocketGetOpt retrieves options for a socket.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument opt_id is the socket option for which the value is to be retrieved. The following socket options are supported:
Option | Description |
---|---|
ARM_SOCKET_SO_RCVTIMEO | Timeout for receiving in blocking mode |
ARM_SOCKET_SO_SNDTIMEO | Timeout for sending in blocking mode |
ARM_SOCKET_SO_KEEPALIVE | Keep-alive mode for the stream socket |
ARM_SOCKET_SO_TYPE | Type of the socket (stream or datagram) |
The argument opt_val points to the buffer that will receive the value of the opt_id.
The argument opt_len contains the length of the buffer at the input and returns the length of the option information on the output.
Example:
int32_t ARM_WIFI_SocketSetOpt | ( | int32_t | socket, |
int32_t | opt_id, | ||
const void * | opt_val, | ||
uint32_t | opt_len | ||
) |
Set socket option.
[in] | socket | Socket identification number |
[in] | opt_id | Option identifier |
[in] | opt_val | Pointer to the option value |
[in] | opt_len | Length of the option value in bytes |
The function ARM_WIFI_SocketSetOpt sets options for a socket.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
The argument opt_id is the socket option for which the value is to be set. The following socket options are supported:
Option | Description |
---|---|
ARM_SOCKET_IO_FIONBIO | Non-blocking mode for the socket |
ARM_SOCKET_SO_RCVTIMEO | Timeout for receiving in blocking mode |
ARM_SOCKET_SO_SNDTIMEO | Timeout for sending in blocking mode |
ARM_SOCKET_SO_KEEPALIVE | Keep-alive mode for the stream socket |
The argument opt_val points to the buffer containing the value of the opt_id.
The argument opt_len tells the exact length of the option.
Example:
int32_t ARM_WIFI_SocketClose | ( | int32_t | socket | ) |
Close and release a socket.
[in] | socket | Socket identification number |
The function ARM_WIFI_SocketClose closes an existing socket and releases the socket descriptor. Further references to socket fail with ARM_SOCKET_EINVAL
error code.
The argument socket specifies a socket identification number returned from a previous call to ARM_WIFI_SocketCreate.
In blocking mode, which is enabled by default, this function will wait until a socket is closed. In non blocking mode, you must call the ARM_WIFI_SocketClose function again if the error code ARM_SOCKET_EAGAIN
is returned.
Example:
int32_t ARM_WIFI_SocketGetHostByName | ( | const char * | name, |
int32_t | af, | ||
uint8_t * | ip, | ||
uint32_t * | ip_len | ||
) |
Retrieve host IP address from host name.
[in] | name | Host name |
[in] | af | Address family |
[out] | ip | Pointer to buffer where resolved IP address shall be returned |
[in,out] | ip_len | Pointer to length of 'ip'
|
The function ARM_WIFI_SocketGetHostByName retrieves host information corresponding to a host name from a host database. It does this by sending DNS requests to the DNS server. The IP address of the DNS server is specified in the network interface configuration or can be obtained from the DHCP server for the local area network.
The argument name is a pointer to the null-terminated name of the host to resolve.
The argument af specifies the address family, that is, which type of IP address you want to resolve. The following values are supported:
Family | Description |
---|---|
ARM_SOCKET_AF_INET | Resolve the IPv4 address |
ARM_SOCKET_AF_INET6 | Resolve the IPv6 address |
The argument ip is a pointer to the buffer that will receive the resolved IP address of the host. If the argument ip is NULL, the function returns error.
The argument ip_len is a pointer to the IP address length. It should initially contain the amount of space pointed to by ip. On return it contains the actual length of the address returned in bytes.
Example:
int32_t ARM_WIFI_Ping | ( | const uint8_t * | ip, |
uint32_t | ip_len | ||
) |
Probe remote host with Ping command.
[in] | ip | Pointer to remote host IP address |
[in] | ip_len | Length of 'ip' address in bytes |
The function ARM_WIFI_Ping checks if the remote host is reachable. It does this by sending an echo request and waiting for an echo response. The function then returns the result of the operation. Check the ARM_WIFI_CAPABILITIES of the driver, if this function is supported in the driver implementation.
The argument ip is a pointer to the buffer containing the IP address octets of the host to ping.
The argument ip_len specifies the length of the IP address. The length is 4 bytes for the IPv4 address and 16 bytes for the IPv6 address.
Example: