API Reference Manual
r8267
|
Functions | |
int | wlp_socket (int type, int proto) |
Creates an endpoint for communication and returns a socket id. | |
int | wlp_set_conn_cb (int sockid, void(*conn_cb)(void *ctx, int sockid, int connected), void *ctx) |
Register a connection status callback. | |
int | wlp_set_recv_cb (int sockid, void(*recv_cb)(void *ctx, int sockid, int len), void *ctx) |
Register a data pending callback. | |
int | wlp_set_sent_cb (int sockid, void(*sent_cb)(void *ctx, int sockid, int len), void *ctx) |
int | wlp_bind (int sockid, const struct ip_addr *addr, uint16_t port) |
Assign an address for a socket. | |
int | wlp_listen (int sockid, int backlog, void(*listen_cb)(void *ctx, int sockid), void *ctx) |
Configure the socket to listen for incoming connections. | |
int | wlp_connect (int sockid, const struct ip_addr *ip, uint16_t port) |
Initiate a connection on a socket. | |
int | wlp_accept (int sockid) |
Accept a connection on a socket. | |
int | wlp_close (int sockid) |
Close a socket. | |
int | wlp_recv (int sockid, char *buf, int16_t len) |
Read data from a socket. | |
int | wlp_send (int sockid, const char *buf, int16_t len) |
Send data to a socket. | |
int | wlp_sendto (int sockid, const char *buf, int16_t len, const struct ip_addr *ip, uint16_t port) |
Send data to a specified address from a socket. | |
int | wlp_get_peeraddr (int sockid, struct ip_addr *peer) |
Get name of connected peer socket. | |
int | wlp_get_hostbyname (const char *host, void(*lookup_cb)(void *ctx, const struct ip_addr *ip), void *ctx) |
Get network address given a dns name. | |
int | wlp_poll (void) |
Event progress function. |
These functions manage the network sockets.
int wlp_accept | ( | int | sockid | ) |
Accept a connection on a socket.
wlp_accept() will accept any pending connection on a listening socket. A new socket will be created and returned as a result of this call. The original listening socket is unaffected by this call.
This function should typically be called when the callback registered in wlp_listen() for the specific socket is invoked. The listening socket id (as passed to wlp_listen()) should be passed to wlp_accept().
However it is also valid to wlp_accept() even through a listen_cb is not invoked for the socket (or not registerd at all). Therefore, it is also possible to accept a pending connection from a specific listening socket in a polling fashion.
Upon returning from wlp_accept() the new socket is connected and ready to send and receive data using e.g wlp_send() and wlp_recv(). If the connection is lost, the any conn_cb registered through wlp_set_conn_cb() will be invoked. Any recv_cb registered through wlp_set_recv_cb() will be invoked when there is pending data to read from the socket. See wlp_recv() for more information.
sockid | is the listening to socket to accept the new connection from. |
Assign an address for a socket.
When a socket is created with wlp_socket(), it has no address assigned to it. wlp_bind() assigns the address specified by addr and port to the socket referred to by the sockid parameter.
A socket must be disconnected in order to use wlp_bind() on the socket.
For sockets of type WLP_SOCK_STREAM, the address and port set through wlp_bind() will be used in wlp_listen(). Also, the source address of any transmitted data will be set to the address configured through wlp_bind(). If wlp_bind() is not called, any transmitted data will have a random source port. Incoming connections for the socket will only be allowed on the port which the socket is bound to.
For sockets of type WLP_SOCK_DGRAM, the source address of any transmitted data will be set to the address configured through wlp_bind(). If wlp_bind() is not called, any transmitted data will have a random source port. Further, incoming data will only be forwarded to this socket if the destination port of the data matches the port the socket is bound to. Note that if the socket was connected through wlp_connect(), incoming data will be forwarded to the socket based on the source address and port of the data. See wlp_connect() for more information.
For sockets of type WLP_SOCK_RAW, the the source address of any transmitted data will be set to the address configured through wlp_bind(). The bound address will not affect which incoming data that is forwarded to the socket, that is only depending on the protocol used.
It is allowed to invoke this function multiple times on the same socket to bind the socket to a new address.
sockid | is the socket to bind |
addr | must be IP_ADDR_ANY. |
port | is the port to bind to. |
int wlp_close | ( | int | sockid | ) |
Close a socket.
wlp_close() will close and remove a socket that was created with wlp_socket(). All memory used by the socket will be free'd.
A connected socket will be cleanly disconnected from the remote end. If there is still pending data on the socket (wlp_recv() was not called to fetch all data), a TCP RST will be sent to the remote end.
A socket can be closed form any state. Any connection callbacks registed for the socket (e.g. from wlp_connect(), wlp_accept() or wlp_listen()) will not be invoked when the socket is closed.
sockid | of the socket to close. |
int wlp_connect | ( | int | sockid, |
const struct ip_addr * | ip, | ||
uint16_t | port | ||
) |
Initiate a connection on a socket.
If the socket is of type WLP_SOCK_DGRAM or WLP_SOCK_RAW then IP and port is the address to which datagrams are sent to by default, and the only address from which datagrams are received.
If the socket is of type WLP_SOCK_STREAM, this call attempts to make a connection to the socket with the given address. Any conn_cb function registered through wlp_set_conn_cb() will be invoked when the attempt is complete, indicating wheter the connection is established or not through the connected paramater. If the connected parameter is 0 when the conn_cb callback is invoked, the the wifi device will not retry the connection and the socket is considered disconnected again. If the connected parameter is 1, then the socket is successfully connected and data transfer can start by e.g. using the wlp_send() and wlp_recv() functions.
For sockets of type WLP_SOCK_DGRAM and WLP_SOCK_RAW, there is no actual concept of a "connected" and "disconnected" sockets since those sockets are connectionless. However, it is still possible to call wlp_connect() for these sockets, indicating that all data sent through wlp_send() will be sent to the address specified in wlp_connect(). Any conn_cb registered through wlp_set_conn_cb() will be invoked upon a successful return from wlp_connect(). Note that a connected socket will only accept incoming data which has a source address and port which matches the parameters passed to wlp_connect(). See wlp_bind() for more information regarding which packets that gets formwarded to the socket.
For sockets of type WLP_SOCK_RAW, the port parameter will be ignored since it is not included in the IP header.
On a connected socket any registerd recv_cb() will be invoked when there is pending data to read from the socket. See wlp_recv() and wlp_set_recv_cb() for more information.
Note that the socket connection status will also be indicated by any wlp_api calls that performs socket communication (e.g. wlp_send() and wlp_recv()) through their return values, even though any conn_cb was not registered through wlp_set_conn_cb().
wlp_connect() can be called multiple times for a single socket but the socket must be disconnected prior to each call.
sockid | is the socket id to connect |
ip | is the IP address of the remote end |
port | is the port number of the remote end, ignored for sockets of type WLP_SOCK_RAW. |
int wlp_get_hostbyname | ( | const char * | host, |
void(*)(void *ctx, const struct ip_addr *ip) | lookup_cb, | ||
void * | ctx | ||
) |
Get network address given a dns name.
If name is an IPv4 address, no lookup is performed and wlp_get_hostbyname() copies host into the parameter provided to the lookup_cb.
Every time wlp_poll() is invoked, the callback condition will be evaluated and any registered callback will be invoked from same context as the call to wlp_poll().
host | is the dns name to lookup |
lookup_cb | will be invoked when lookup is complete or considered failed. On success, the IP parameter will be set to the IP address that was looked up. On failure, IP will be NULL. |
ctx | is an opaque context parameter that will be passed back to the lookup_cb. |
int wlp_get_peeraddr | ( | int | sockid, |
struct ip_addr * | peer | ||
) |
Get name of connected peer socket.
wlp_get_peeraddr() returns the address of the peer connected to the socket. Only supported on sockets of type WLP_SOCK_STREAM.
sockid | is the socket for which the peer should be obtained. |
peer | will hold the peer IP address upon successful return. |
int wlp_listen | ( | int | sockid, |
int | backlog, | ||
void(*)(void *ctx, int sockid) | listen_cb, | ||
void * | ctx | ||
) |
Configure the socket to listen for incoming connections.
wlp_listen() marks the socket referred to by sockid as a passive socket, that is, as a socket that will be used to accept incoming connection requests wlp_accept(). Only sockets of type WLP_SOCK_STREAM may be put in listening mode.
Upon successful return the socket will listen on the port configured in wlp_bind() and the listen_cb will be invoked upon any incoming connection. Every time wlp_poll() is invoked, the callback condition will be evaluated and any registered listen callback will be invoked from same context as the call to wlp_poll().
Note that any incoming connections will be silently rejected before the listen_cb is invoked in case the wifi device is low on resources (e.g. the maximum number of connected WLP_SOCK_STREAM sockets are already in use).
sockid | is a socket id that refers to a socket of type WLP_SOCK_STREAM. |
backlog | defines the maximum length to which the queue of pending connections for the socket may grow. If a connection request arrives when the queue is full, the client may receive an connection refused indication. |
listen_cb | will be invoked when there's a pending connection to accept. The id of the listening socket will be passed to the listen_cb. See wlp_accept() for more information. |
ctx | is an opaque context pointer that will be passed back to the listen_cb. |
int wlp_poll | ( | void | ) |
Event progress function.
This function must be called in stand-alone environments to ensure forward progress of events. The call can be made periodically from the main application loop.
Every time wlp_poll() is invoked, the callback conditions for all callbacks registered through wlp_api will be evaluated and any registered callback will be invoked from same context as the call to wlp_poll().
If no callbacks are registered, wlp_poll() does not have to be invoked.
In systems using an OS, a task could be scheduled to run this task periodicallly.
Note that this function should not be invoked from interrupt context.
int wlp_recv | ( | int | sockid, |
char * | buf, | ||
int16_t | len | ||
) |
Read data from a socket.
Read pending data from a socket. This function will attempt to read up to len bytes from the given socket.
If no data is pending on the socket, 0 will be returned.
Sockets of type WLP_SOCK_STREAM will not preserve message boundaries in general. If the socket has less than len bytes available for reading, the available bytes will be read and the function will return. The actual number of bytes read will be returned.
Sockets of type WLP_SOCK_DGRAM and WLP_SOCK_RAW will preserve message boundaries by requiring that the len parameter is large enough to hold the complete message. Otherwise WLP_ERR_SIZE will be returned and no data will be received. In this case, the caller must invoke wlp_recv() again with a larger buffer that can hold the complete message. Also note that any incoming packets addressed to a socket of type WLP_SOCK_DGRAM or WLP_SOCK_RAW that are larger than 1500 bytes (including IP/UDP header) will be discarded by the device.
In case the host wants to discard a packet but do not have enough memory to hold the complete packet, a NULL pointer can be passed as the buf parameter. This pointer will be passed along to the bus read and write functions registered in wlp_init(). Therefore, this assumes that these user-provided functions can handle the NULL pointer and that the semantics is to read data (according to the len paramter) but discard the bytes instead of writing the destination buffer.
For sockets of type WLP_SOCK_RAW, the IP header will be included in the received message.
See wlp_connect() for more information about message boundaries for the differenct socket types.
This function should typically be called from the recv_cb registered through wlp_set_recv_cb(). However it is also valid to wlp_recv() even through a recv_cb is not invoked for the socket (or not registerd at all). Therefore, it is possible to recieve data from a specific socket in a polling fashion.
Note that the error code WLP_ERR_CONN will be returned if the socket was closed from the remote end. Note that any pending, buffered, data will be returned before WLP_ERR_CONN is returned. In case the socket connection was closed by the remote end, any registered recv_cb (see wlp_set_recv_cb()) will also be called with len set to 0.
The error code WLP_ERR_ABORT will be returned if the socket connection was terminated in any other way, e.g. link goes down. In this case any registered conn_cb (see wlp_connect() or wlp_accept()) will also be called with the connected parameter set to 0. Any non-read data that is buffered by the wifi device will be lost.
sockid | is the socket to read |
buf | should point to a buffer which will hold the read data. |
len | is the number of bytes to read. |
int wlp_send | ( | int | sockid, |
const char * | buf, | ||
int16_t | len | ||
) |
Send data to a socket.
Send data to a connected socket.
Sockets of type WLP_SOCK_STREAM will not preserve message boundaries in general. This function will attempt to send up to len bytes of data to the given socket. If the socket has room for less than len bytes in its input buffer, the maximum allowed bytes will be written and then this function will return. The actual number of bytes written will be returned.
Sockets of type WLP_SOCK_DGRAM and WLP_SOCK_RAW will preserve message boundaries by ensuring that the requested len is also the length of the single IP packet transmitted over the wireless link (possibly fragmented) If the call to wlp_send() returns WLP_ERR_SIZE, the provide buffer is too large to be transferred as a single message. No data is transferred in this case. This limit is 1500 bytes.
Note that for sockets of type WLP_SOCK_RAW, you can not modify the IP headers (this is inconsistent with the data read through wlp_recv() where you actually get the IP headers), you can only specify the IP payload here.
See wlp_connect() for more information about message boundaries for the differenct socket types.
It is valid to call wlp_send() multple times even though all requested data was not transmitted (according to the return value) to send a large chunk of data. Therefore, it is possible to send data to specific socket in a blocking fashion.
Note that the error code WLP_ERR_CONN will be returned if the socket was closed by the remote end. In case the socket connection was closed by the remote end, any registered recv_cb (see wlp_set_recv_cb()) will also be called with len set to 0.
The error code WLP_ERR_ABORT will be returned if the socket connection was terminated in any other way, e.g. link goes down. In this case the conn_cb will also be called with the connected parameter set to 0.
sockid | is the socket to write |
buf | should pointer to a buffer which will hold the data to be written. |
len | is the number of bytes to write. |
int wlp_sendto | ( | int | sockid, |
const char * | buf, | ||
int16_t | len, | ||
const struct ip_addr * | ip, | ||
uint16_t | port | ||
) |
Send data to a specified address from a socket.
wlp_sendto() will send data to a specified address. This is generally used for connectionless sockets, e.g. of type WLP_SOCK_DGRAM or WLP_SOCK_RAW. For WLP_SOCK_TYPE_STREAM sockets, the IP and port parameters will be ignored and the data will be sent to any remote endpoint established through wlp_connect().
For sockets of type WLP_SOCK_RAW, the port parameter will be ignored since it is not included in the IP header.
Except for the extra parameters, this function will behave exactly the same as wlp_send(). See wlp_send() for more details.
sockid | is the socket to write |
buf | should pointer to a buffer which will hold the data to be written. |
len | is the number of bytes to write. |
ip | is the IP address to send to |
port | is the port to send to, ignored for sockets of type WLP_SOCK_RAW. |
int wlp_set_conn_cb | ( | int | sockid, |
void(*)(void *ctx, int sockid, int connected) | conn_cb, | ||
void * | ctx | ||
) |
Register a connection status callback.
wlp_set_conn_cb() will register a function that will be invoked when the socket connection status for the specified socket changes.
The connection status will change when wlp_connect() is finished processing or when a the remote end aborts the connection. See wlp_connect() for details.
Every time wlp_poll() is invoked, the conn_cb callback conditions will be evaluated and any registered callback will be invoked from same context as the call to wlp_poll().
A registered callback can be removed by calling wlp_set_conn_cb() with NULL parameters.
sockid is the socket for which the conn_cb should be bound to.
conn_cb | is a callback function that will be invoked when the connection is established or lost. The socket id and the connection state will be passed as arguments to the callback. Not used if NULL. |
ctx | is an opaque context parameter that will be passed back to the conn_cb. |
int wlp_set_recv_cb | ( | int | sockid, |
void(*)(void *ctx, int sockid, int len) | recv_cb, | ||
void * | ctx | ||
) |
Register a data pending callback.
Any registerd recv_cb() will be invoked when there is pending data to read from the specified socket. See wlp_recv() for more information.
Every time wlp_poll() is invoked, the recv_cb callback conditions will be evaluated and any registered callback will be invoked from same context as the call to wlp_poll().
sockid is the socket for which the recv_cb should be bound to.
recv_cb | is a callback function that will be invoked when there is pending data to read from the socket. The number of bytes available for reading will be passed in the len parameter. If 0, then the connection was closed by the remote end. Not used if NULL. |
ctx | is an opaque context parameter that will be passed back to the recv_cb. |
int wlp_socket | ( | int | type, |
int | proto | ||
) |
Creates an endpoint for communication and returns a socket id.
To create a TCP socket, set the type to WLP_SOCK_STREAM. To create a UDP socket, set the type to WLP_SOCK_DGRAM. To create a RAW socket, set the type to WLP_SOCK_RAW.
Sockets of type WLP_SOCK_STREAM must be in a connected state before any data may be sent or received on it. A connection to another socket is created with wlp_connect(). Once connected, data may be transferred using wlp_recv() and wlp_send() calls. When a session has been completed, wlp_close() can be called. Sockets of type WLP_SOCK_STREAM always uses the TCP protocol. WLP_SOCK_STREAM type sockets does not preserve message boundaries, i.e sequential calls to wlp_send() might result in a single, aggregated, IP packet being transferred on the wireless interface. It is also possible that a single call to wlp_send() results in multiple IP packets being transferred on the wireless interface.
WLP_SOCK_DGRAM and WLP_SOCK_RAW sockets are connectionless and allows the sending of datagrams to correspondents named in wlp_sendto(). Further, these sockets does preserve message boundaries, i.e sequential calls to wlp_send() or wlp_sendto() might will result in multiple IP packets being transferred on the wireless interface. See wlp_send() and wlp_sendto() for more information.
The protocol parameter specifies a particular protocol to be used with the socket. For the WLP_SOCK_STREAM and WLP_SOCK_DGRAM types, only a single protocol exists to support a particular socket type, in which case the protocol parameter is ignored. However, for WLP_SOCK_RAW many protocols exists, in which case a particular protocol must be specified in this manner.
The default Wi-Fi device configuration allows for up to eight WLP_SOCK_STREAM sockets (four in listening mode and four in connection mode), four WLP_SOCK_DGRAM sockets, and four WLP_SOCK_RAW sockets.
Note that is is only possible to create a single WLP_SOCK_RAW socket for each protocol type.
type | is the socket type; WLP_SOCK_STREAM, WLP_SOCK_DGRAM or WLP_SOCK_RAW. |
proto | specifies a particular protocol to be used with the socket, ignored if type is WLP_SOCK_STREAM or WLP_SOCK_DGRAM. |