EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
socket (Network Socket Interface)

Overview

Platform-neutral BSD-modeled network socket implementation.

#include "etcpal/socket.h"

WARNING: This module must be explicitly initialized before use. Initialize the module by calling etcpal_init() with the relevant feature mask:

#define ETCPAL_FEATURE_SOCKETS
Use the etcpal/socket module.
Definition: common.h:127
etcpal_error_t etcpal_init(etcpal_features_t features)
Initialize the EtcPal library.
Definition: common.c:87

This module attempts to abstract the network socket interface from various platforms into one platform-neutral interface. The functions and flags are modeled after the BSD sockets interface. This API is too large and complex to provide a concise how-to here; users of this module are assumed to already be familiar with some version of the BSD interface. If not, UNIX Network Programming: The Sockets Networking API by Stevens, Fenner, and Rudoff is highly recommended reading.

Data Structures

struct  EtcPalLinger
 Option value for ETCPAL_SO_LINGER. More...
 
struct  EtcPalMreq
 Option value for ETCPAL_IP_ADD_MEMBERSHIP and ETCPAL_IP_DROP_MEMBERSHIP. More...
 
struct  EtcPalGroupReq
 Option value for ETCPAL_MCAST_JOIN_GROUP and ETCPAL_MCAST_LEAVE_GROUP. More...
 
struct  EtcPalPollEvent
 A description of an event that occurred on a socket, for usage with etcpal_poll_wait(). More...
 
struct  EtcPalAddrinfo
 A structure containing name and address information about an internet host. More...
 

Macros

#define ETCPAL_POLL_VALID_INPUT_EVENT_MASK   0x0fu
 Mask of valid events for use with etcpal_poll_add_socket().
 
#define ETCPAL_SOCKET_INVALID   [PLATFORM_DEFINED]
 An identifier for an invalid socket handle.
 
#define ETCPAL_SOCKET_MAX_POLL_SIZE   [PLATFORM_DEFINED]
 The maximum number of sockets that can be simultaneously monitored by etcpal_poll_wait(). More...
 

Typedefs

typedef uint32_t etcpal_poll_events_t
 Event flags for the etcpal_poll_*() API functions.
 
typedef struct EtcPalLinger EtcPalLinger
 Option value for ETCPAL_SO_LINGER.
 
typedef struct EtcPalMreq EtcPalMreq
 Option value for ETCPAL_IP_ADD_MEMBERSHIP and ETCPAL_IP_DROP_MEMBERSHIP.
 
typedef struct EtcPalGroupReq EtcPalGroupReq
 Option value for ETCPAL_MCAST_JOIN_GROUP and ETCPAL_MCAST_LEAVE_GROUP.
 
typedef struct EtcPalPollEvent EtcPalPollEvent
 A description of an event that occurred on a socket, for usage with etcpal_poll_wait().
 
typedef struct EtcPalAddrinfo EtcPalAddrinfo
 A structure containing name and address information about an internet host. More...
 
typedef PLATFORM_DEFINED etcpal_socket_t
 A socket handle. More...
 

Functions

etcpal_error_t etcpal_accept (etcpal_socket_t id, EtcPalSockAddr *address, etcpal_socket_t *conn_sock)
 Accept a connection on a socket. More...
 
etcpal_error_t etcpal_bind (etcpal_socket_t id, const EtcPalSockAddr *address)
 Bind a name to a socket. More...
 
etcpal_error_t etcpal_close (etcpal_socket_t id)
 Close a socket. More...
 
etcpal_error_t etcpal_connect (etcpal_socket_t id, const EtcPalSockAddr *address)
 Initiate a connection on a socket. More...
 
etcpal_error_t etcpal_getpeername (etcpal_socket_t id, EtcPalSockAddr *address)
 Get the name of the connected peer socket. More...
 
etcpal_error_t etcpal_getsockname (etcpal_socket_t id, EtcPalSockAddr *address)
 Get socket name. More...
 
etcpal_error_t etcpal_getsockopt (etcpal_socket_t id, int level, int option_name, void *option_value, size_t *option_len)
 Get an option value for a socket. More...
 
etcpal_error_t etcpal_listen (etcpal_socket_t id, int backlog)
 Listen for connections on a socket. More...
 
int etcpal_recv (etcpal_socket_t id, void *buffer, size_t length, int flags)
 Receive data on a connected socket. More...
 
int etcpal_recvfrom (etcpal_socket_t id, void *buffer, size_t length, int flags, EtcPalSockAddr *address)
 Receive data on a socket. More...
 
int etcpal_send (etcpal_socket_t id, const void *message, size_t length, int flags)
 Send data on a connected socket. More...
 
int etcpal_sendto (etcpal_socket_t id, const void *message, size_t length, int flags, const EtcPalSockAddr *dest_addr)
 Send data on a socket. More...
 
etcpal_error_t etcpal_setsockopt (etcpal_socket_t id, int level, int option_name, const void *option_value, size_t option_len)
 Set an option value on a socket. More...
 
etcpal_error_t etcpal_shutdown (etcpal_socket_t id, int how)
 Shut down part of a full-duplex connection. More...
 
etcpal_error_t etcpal_socket (unsigned int family, unsigned int type, etcpal_socket_t *id)
 Create a socket. More...
 
etcpal_error_t etcpal_setblocking (etcpal_socket_t id, bool blocking)
 Change the blocking behavior of a socket. More...
 
etcpal_error_t etcpal_getblocking (etcpal_socket_t id, bool *blocking)
 Get the current blocking behavior of a socket. More...
 
etcpal_error_t etcpal_getaddrinfo (const char *hostname, const char *service, const EtcPalAddrinfo *hints, EtcPalAddrinfo *result)
 Get address information for a named internet host and/or service. More...
 
bool etcpal_nextaddr (EtcPalAddrinfo *ai)
 Get the next address from the list returned by etcpal_getaddrinfo(). More...
 
void etcpal_freeaddrinfo (EtcPalAddrinfo *ai)
 Free an addrinfo list returned by etcpal_getaddrinfo(). More...
 

etcpal_poll API

The etcpal_poll functions enable monitoring several sockets at once.

typedef PLATFORM_DEFINED EtcPalPollContext
 A structure that holds context information for poll operations on multiple sockets. More...
 
etcpal_error_t etcpal_poll_context_init (EtcPalPollContext *context)
 Create a new context for waiting on events on multiple sockets. More...
 
void etcpal_poll_context_deinit (EtcPalPollContext *context)
 Invalidate a previously-initialized EtcPalPollContext structure. More...
 
etcpal_error_t etcpal_poll_add_socket (EtcPalPollContext *context, etcpal_socket_t socket, etcpal_poll_events_t events, void *user_data)
 Add a new socket to an EtcPalPollContext. More...
 
etcpal_error_t etcpal_poll_modify_socket (EtcPalPollContext *context, etcpal_socket_t socket, etcpal_poll_events_t new_events, void *new_user_data)
 Change the set of events or user data associated with a monitored socket. More...
 
void etcpal_poll_remove_socket (EtcPalPollContext *context, etcpal_socket_t socket)
 Remove a monitored socket from an EtcPalPollContext. More...
 
etcpal_error_t etcpal_poll_wait (EtcPalPollContext *context, EtcPalPollEvent *event, int timeout_ms)
 Wait for an event on a set of sockets defined by an EtcPalPollContext. More...
 

Flags for etcpal_recvfrom()

#define ETCPAL_MSG_PEEK   0x1
 

Level values for etcpal_setsockopt() and etcpal_getsockopt()

Refer to the group of option names for each level.

#define ETCPAL_SOL_SOCKET   0
 etcpal_socket API level.
 
#define ETCPAL_IPPROTO_IP   1
 IPv4 protocol level.
 
#define ETCPAL_IPPROTO_ICMPV6   2
 ICMPv6 protocol level.
 
#define ETCPAL_IPPROTO_IPV6   3
 IPv6 protocol level.
 
#define ETCPAL_IPPROTO_TCP   4
 TCP protocol level.
 
#define ETCPAL_IPPROTO_UDP   5
 UDP protocol level.
 

Options for level ETCPAL_SOL_SOCKET

Used in the option parameter to etcpal_setsockopt() and etcpal_getsockopt().

Refer to the similarly-named option on your favorite man page for more details.

#define ETCPAL_SO_BROADCAST   0
 Get/Set, value is boolean int.
 
#define ETCPAL_SO_ERROR   1
 Get only, value is int representing platform error value.
 
#define ETCPAL_SO_KEEPALIVE   2
 Get/Set, value is boolean int.
 
#define ETCPAL_SO_LINGER   3
 Get/Set, value is EtcPalLinger.
 
#define ETCPAL_SO_RCVBUF   4
 Get/Set, value is int representing byte size.
 
#define ETCPAL_SO_SNDBUF   5
 Get/Set, value is int representing byte size.
 
#define ETCPAL_SO_RCVTIMEO   6
 Get/Set, value is int representing ms.
 
#define ETCPAL_SO_SNDTIMEO   7
 Get/Set, value is int representing ms.
 
#define ETCPAL_SO_REUSEADDR   8
 Get/Set, value is boolean int.
 
#define ETCPAL_SO_REUSEPORT   9
 Get/Set, value is boolean int.
 
#define ETCPAL_SO_TYPE   10
 Get only, value is int.
 

Options for level ETCPAL_IPPROTO_IP or ETCPAL_IPPROTO_IPV6

Used in the option parameter to etcpal_setsockopt() and etcpal_getsockopt().

Refer to the similarly-named option on your favorite man page for more details.

#define ETCPAL_IP_TTL   11
 Get/Set, value is int. More...
 
#define ETCPAL_IP_MULTICAST_IF   12
 Get/Set, value is unsigned int representing interface index (see Network Interface Indexes).
 
#define ETCPAL_IP_MULTICAST_TTL   13
 Get/Set, value is int. More...
 
#define ETCPAL_IP_MULTICAST_LOOP   14
 Get/Set, value is boolean int.
 
#define ETCPAL_IP_ADD_MEMBERSHIP   15
 [Legacy IPv4-only option, use of ETCPAL_MCAST_JOIN_GROUP is preferred] Set only, value is EtcPalMreq.
 
#define ETCPAL_IP_DROP_MEMBERSHIP   16
 [Legacy IPv4-only option, use of ETCPAL_MCAST_LEAVE_GROUP is preferred] Set only, value is EtcPalMreq.
 
#define ETCPAL_MCAST_JOIN_GROUP   17
 Set only, value is EtcPalGroupReq.
 
#define ETCPAL_MCAST_LEAVE_GROUP   18
 Set only, value is EtcPalGroupReq.
 
#define ETCPAL_IPV6_V6ONLY   19
 Get/Set, value is boolean int.
 

'how' values for etcpal_shutdown()

#define ETCPAL_SHUT_RD   0
 
#define ETCPAL_SHUT_WR   1
 
#define ETCPAL_SHUT_RDWR   2
 

'family' values for etcpal_socket() and EtcPalAddrinfo

#define ETCPAL_AF_UNSPEC   0u
 
#define ETCPAL_AF_INET   1u
 
#define ETCPAL_AF_INET6   2u
 

'type' values for etcpal_socket() and etcpal_getsockopt()

#define ETCPAL_SOCK_STREAM   0u
 
#define ETCPAL_SOCK_DGRAM   1u
 

Flag values to use with etcpal_poll_events_t.

#define ETCPAL_POLL_IN   0x1u
 Notify when data is available for reading on the socket.
 
#define ETCPAL_POLL_OUT   0x2u
 Notify when the socket has space available to write data.
 
#define ETCPAL_POLL_CONNECT   0x4u
 Notify when a non-blocking connect operation has completed.
 
#define ETCPAL_POLL_OOB   0x8u
 Notify when there is out-of-band data on a TCP socket.
 
#define ETCPAL_POLL_ERR   0x10u
 An error has occurred on the socket (output only).
 

'flags' values for EtcPalAddrinfo

Refer to the similarly-named flags in your favorite getaddrinfo() man page for more details.

#define ETCPAL_AI_PASSIVE   0x01
 
#define ETCPAL_AI_CANONNAME   0x02
 
#define ETCPAL_AI_NUMERICHOST   0x04
 

Macro Definition Documentation

◆ ETCPAL_IP_MULTICAST_TTL

#define ETCPAL_IP_MULTICAST_TTL   13

Get/Set, value is int.

Value indicates TTL for IPv4 or hop limit for IPv6.

◆ ETCPAL_IP_TTL

#define ETCPAL_IP_TTL   11

Get/Set, value is int.

Value indicates TTL for IPv4 or hop limit for IPv6.

◆ ETCPAL_SOCKET_MAX_POLL_SIZE

#define ETCPAL_SOCKET_MAX_POLL_SIZE   [PLATFORM_DEFINED]

The maximum number of sockets that can be simultaneously monitored by etcpal_poll_wait().

Some systems have no compile-time limit on this value - it could be a runtime system-defined limit (e.g. ulimit) or even limited only by the amount of available memory. In that case this constant will have the value -1.

Typedef Documentation

◆ etcpal_socket_t

typedef PLATFORM_DEFINED etcpal_socket_t

A socket handle.

Typedefed to the system's socket identifier.

◆ EtcPalAddrinfo

A structure containing name and address information about an internet host.

Returned by etcpal_getaddrinfo().

◆ EtcPalPollContext

typedef PLATFORM_DEFINED EtcPalPollContext

A structure that holds context information for poll operations on multiple sockets.

See the documentation for etcpal_poll_context_init() and etcpal_poll_wait() for more information.

Function Documentation

◆ etcpal_accept()

etcpal_error_t etcpal_accept ( etcpal_socket_t  id,
EtcPalSockAddr address,
etcpal_socket_t conn_sock 
)

Accept a connection on a socket.

Refer to your favorite accept() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPalSockAddr type. Connected socket is returned in an output parameter rather than the return value.

Parameters
[in]idListening socket on which to accept a new connection.
[out]addressRemote address from which the connection was accepted.
[out]conn_sockFilled in on success with handle to connected socket.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (failure).

◆ etcpal_bind()

etcpal_error_t etcpal_bind ( etcpal_socket_t  id,
const EtcPalSockAddr address 
)

Bind a name to a socket.

Refer to your favorite bind() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPalSockAddr type.

Parameters
[in]idSocket to which to bind an address (traditionally called a 'name').
[in]addressAddress to assign to the socket.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_close()

etcpal_error_t etcpal_close ( etcpal_socket_t  id)

Close a socket.

Refer to your favorite close() man page for more information.

On UNIX-like systems, note that this may also successfully close descriptors that don't refer to sockets; however, for portability it should only be used on identifiers that were returned from an etcpal_* function.

Parameters
[in]idSocket to close.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_connect()

etcpal_error_t etcpal_connect ( etcpal_socket_t  id,
const EtcPalSockAddr address 
)

Initiate a connection on a socket.

Refer to your favorite connect() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters
[in]idSocket to connect.
[in]addressAddress to which to connect.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_freeaddrinfo()

void etcpal_freeaddrinfo ( EtcPalAddrinfo ai)

Free an addrinfo list returned by etcpal_getaddrinfo().

Most platforms allocate memory when getaddrinfo() is called. This must always be called after any call to etcpal_getaddrinfo() to free that memory. It can be called with any of the EtcPalAddrinfo instances in the list, and the whole list will be freed. See the example usage in the description of etcpal_getaddrinfo().

Parameters
[in]aiPointer to EtcPalAddrinfo struct for which to free the platform memory.

◆ etcpal_getaddrinfo()

etcpal_error_t etcpal_getaddrinfo ( const char *  hostname,
const char *  service,
const EtcPalAddrinfo hints,
EtcPalAddrinfo result 
)

Get address information for a named internet host and/or service.

Refer to your favorite getaddrinfo() man page for more information. One difference between this and the POSIX function is the way that multiple addresses are iterated. EtcPal uses the etcpal_nextaddr() function instead of a next pointer to iterate over multiple addresses. For example:

if (0 == etcpal_getaddrinfo("www.google.com", "http", NULL, &info))
{
do
{
char inet_str[ETCPAL_IP_STRING_BYTES];
if (kEtcPalErrOk == etcpal_ip_to_string(&info.ai_addr.ip, inet_str))
{
printf("Address: %s\n", inet_str);
}
else
{
printf("Address conversion error!\n");
}
} while (etcpal_nextaddr(&info));
}
@ kEtcPalErrOk
The call was successful, no error occurred.
Definition: error.h:51
#define ETCPAL_IP_STRING_BYTES
Maximum length of the string representation of an IP address.
Definition: inet.h:394
etcpal_error_t etcpal_ip_to_string(const EtcPalIpAddr *src, char *dest)
Convert IPv4 and IPv6 addresses from binary to text form.
etcpal_error_t etcpal_getaddrinfo(const char *hostname, const char *service, const EtcPalAddrinfo *hints, EtcPalAddrinfo *result)
Get address information for a named internet host and/or service.
bool etcpal_nextaddr(EtcPalAddrinfo *ai)
Get the next address from the list returned by etcpal_getaddrinfo().
void etcpal_freeaddrinfo(EtcPalAddrinfo *ai)
Free an addrinfo list returned by etcpal_getaddrinfo().
A structure containing name and address information about an internet host.
Definition: socket.h:295
EtcPalSockAddr ai_addr
Address of host.
Definition: socket.h:301
EtcPalIpAddr ip
IP address.
Definition: inet.h:313

On an internet-connected machine with DNS resolution capability, the above code should print something like:

Address: 172.217.4.196
Address: 172.217.4.196
Address: 2607:f8b0:4009:806::2004
Address: 2607:f8b0:4009:806::2004
Parameters
[in]hostnameEither a string-represented numerical network address or a network hostname to resolve.
[in]serviceEither a string-represented numerical port number or a service name.
[in]hintsStructure containing hints restricting the address types that can be returned.
[out]resultOn success, filled in with the first address result.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (an error occurred).

◆ etcpal_getblocking()

etcpal_error_t etcpal_getblocking ( etcpal_socket_t  id,
bool *  blocking 
)

Get the current blocking behavior of a socket.

This is similar to checking the state of the O_NONBLOCK flag through the fcntl() function on a BSD socket.

Parameters
[in]idSocket for which to read the blocking behavior.
[out]blockingFilled in with whether the socket is currently blocking or not.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getpeername()

etcpal_error_t etcpal_getpeername ( etcpal_socket_t  id,
EtcPalSockAddr address 
)

Get the name of the connected peer socket.

Refer to your favorite getpeername() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters
[in]idConnected socket for which to get the peer address.
[in]addressFilled in with peer address on success.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getsockname()

etcpal_error_t etcpal_getsockname ( etcpal_socket_t  id,
EtcPalSockAddr address 
)

Get socket name.

Refer to your favorite getsockname() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters
[in]idConnected socket for which to get the bound address.
[in]addressFilled in with bound address on success.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_getsockopt()

etcpal_error_t etcpal_getsockopt ( etcpal_socket_t  id,
int  level,
int  option_name,
void *  option_value,
size_t *  option_len 
)

Get an option value for a socket.

Refer to your favorite getsockopt() man page for more information.

Differences from POSIX: Some overlapping option values are consolidated and some legacy option values are not included. Some value types are different; see the documentation of each possible option value.

Parameters
[in]idSocket for which to get the option value.
[in]levelProtocol level of the option for which to get the value.
[in]option_nameName of the option for which to get the value.
[out]option_valueFilled in with option value on success.
[in,out]option_lenContains size of buffer pointed to by option_value, filled in with actual size of value returned.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_listen()

etcpal_error_t etcpal_listen ( etcpal_socket_t  id,
int  backlog 
)

Listen for connections on a socket.

Refer to your favorite listen() man page for more information.

Parameters
[in]idETCPAL_SOCK_STREAM socket on which to listen.
[in]backlogMaximum length of pending connection queue.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_nextaddr()

bool etcpal_nextaddr ( EtcPalAddrinfo ai)

Get the next address from the list returned by etcpal_getaddrinfo().

Most platforms allocate and return a linked list of address info structs in their getaddrinfo() implementation. To avoid further memory allocation in the abstraction layer, this non-POSIX-like way to iterate through the EtcPalAddrinfo structs is provided. To get all of the addresses returned from a etcpal_getaddrinfo() call, keep calling this on the result struct until it returns false.

Parameters
[in,out]aiPointer to last EtcPalAddrinfo struct, filled in with values of the next address.
Returns
true (next address was filled in) or false (no more addresses or error).

◆ etcpal_poll_add_socket()

etcpal_error_t etcpal_poll_add_socket ( EtcPalPollContext context,
etcpal_socket_t  socket,
etcpal_poll_events_t  events,
void *  user_data 
)

Add a new socket to an EtcPalPollContext.

This socket will be monitored on future calls to etcpal_poll_wait() for the events specified in the 'events' parameter. See the definitions of the ETCPAL_POLL_* flag values for more information. The flag values can be 'or'ed together to monitor for multiple events. Only flag values that are not marked 'output only' are valid for use with this function. Errors on sockets will always be reported with the ETCPAL_POLL_ERR flag.

On some systems, the underlying polling method has a limit to how many sockets can be monitored in a single call. If there is a limit, it is defined as the positive value ETCPAL_SOCKET_MAX_POLL_SIZE. Otherwise, that constant is set to -1.

Parameters
[in,out]contextPointer to EtcPalPollContext to which to add new socket.
[in]socketSocket to start monitoring.
[in]eventsEvents to monitor for on this socket.
[in]user_dataOpaque data pointer that is passed back with events on this socket.
Returns
kEtcPalErrOk: Socket added successfully.
kEtcPalErrExists: The socket has already been added to this context.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNoMem: ETCPAL_SOCKET_MAX_POLL_SIZE is exceeded in this context.
kEtcPalErrSys: System call failed.

◆ etcpal_poll_context_deinit()

void etcpal_poll_context_deinit ( EtcPalPollContext context)

Invalidate a previously-initialized EtcPalPollContext structure.

This must be called at shutdown or when the EtcPalPollContext is no longer needed to free any resources being used to track polling context.

Parameters
[in]contextPointer to EtcPalPollContext to deinitialize.

◆ etcpal_poll_context_init()

etcpal_error_t etcpal_poll_context_init ( EtcPalPollContext context)

Create a new context for waiting on events on multiple sockets.

EtcPalPollContext structures contain information about an application's interest in events on a set of sockets. The etcpal_poll_wait() function can then be used to block the calling thread until one such event takes place.

This function must be called on an EtcPalPollContext structure before using it with any other etcpal_poll_* function.

Parameters
[in,out]contextPointer to EtcPalPollContext to initialize.
Returns
kEtcPalErrOk: Init successful.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrSys: System call failed.

◆ etcpal_poll_modify_socket()

etcpal_error_t etcpal_poll_modify_socket ( EtcPalPollContext context,
etcpal_socket_t  socket,
etcpal_poll_events_t  new_events,
void *  new_user_data 
)

Change the set of events or user data associated with a monitored socket.

The new events and/or user data will be used on the next call to etcpal_poll_wait().

Parameters
[in,out]contextPointer to EtcPalPollContext on which to modify socket parameters.
[in]socketSocket to modify.
[in]new_eventsNew set of events to monitor for on this socket. Passing the same events as before is also valid if only the user data is being changed.
[in]new_user_dataNew opaque data pointer that is passed back with events on this socket. Passing the same pointer as before is also valid if only the events are being changed.
Returns
kEtcPalErrOk: Socket modified successfully.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNotFound: Socket was not previously added to this context.
kEtcPalErrSys: System call failed.

◆ etcpal_poll_remove_socket()

void etcpal_poll_remove_socket ( EtcPalPollContext context,
etcpal_socket_t  socket 
)

Remove a monitored socket from an EtcPalPollContext.

This socket will no longer be monitored on future calls to etcpal_poll_wait().

Parameters
[in,out]contextPointer to EtcPalPollContext from which to remove socket.
[in]socketSocket to remove.

◆ etcpal_poll_wait()

etcpal_error_t etcpal_poll_wait ( EtcPalPollContext context,
EtcPalPollEvent event,
int  timeout_ms 
)

Wait for an event on a set of sockets defined by an EtcPalPollContext.

Waits for events defined by previous calls to etcpal_poll_add_socket() on this context structure. Reports one event at a time in the output 'event' parameter. Waits up to timeout_ms milliseconds; use ETCPAL_WAIT_FOREVER to wait indefinitely. If there are no sockets currently added to the context structure, returns the special error code kEtcPalErrNoSockets immediately.

This function should not be assumed to be thread-safe with respect to the other etcpal_poll API functions; for this reason, etcpal_poll_add_socket(), etcpal_poll_modify_socket(), and etcpal_poll_remove_socket() should not be called while this function is blocking.

Uses OS-specific APIs for monitoring multiple sockets under the hood. Details:

Platform: API used: Notes:
Linux epoll()
lwIP select() ETCPAL_SOCKET_MAX_POLL_SIZE is controlled by FD_SETSIZE which is in turn controlled by MEMP_NUM_NETCONN in lwipopts.h.
macOS kqueue()
MQX (RTCS) select() ETCPAL_SOCKET_MAX_POLL_SIZE is controlled by the RTCS config constant RTCSCFG_FD_SETSIZE.
Microsoft Windows select() ETCPAL_SOCKET_MAX_POLL_SIZE defaults to 64, but can be increased by setting FD_SETSIZE=[new_value] as a compile-time definition.
Parameters
[in]contextPointer to EtcPalPollContext for which to wait for events.
[out]eventOn success, contains information about the event that occurred.
[in]timeout_msHow long to wait for an event, in milliseconds. Use ETCPAL_WAIT_FOREVER to wait indefinitely.
Returns
kEtcPalErrOk: An event occurred, and information is available in the event argument.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNoSockets: The context has no sockets added to it.
kEtcPalErrTimedOut: Timed out waiting for an event to occur.
kEtcPalErrSys: System or socket call failed.
Other etcpal_error_t values are possible from underlying socket calls.

◆ etcpal_recv()

int etcpal_recv ( etcpal_socket_t  id,
void *  buffer,
size_t  length,
int  flags 
)

Receive data on a connected socket.

Refer to your favorite recv() man page for more information.

Parameters
[in]idSocket on which to receive.
[out]bufferBuffer in which to place received data.
[in]lengthSize in bytes of buffer.
[in]flagsReceive flags.
Returns
Number of bytes received (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_recvfrom()

int etcpal_recvfrom ( etcpal_socket_t  id,
void *  buffer,
size_t  length,
int  flags,
EtcPalSockAddr address 
)

Receive data on a socket.

Refer to your favorite recvfrom() man page for more information.

Differences from POSIX: addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters
[in]idSocket on which to receive.
[out]bufferBuffer in which to place received data.
[in]lengthSize in bytes of buffer.
[in]flagsReceive flags.
[out]addressIf provided, filled in on success with peer address from which the data was received.
Returns
Number of bytes received (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_send()

int etcpal_send ( etcpal_socket_t  id,
const void *  message,
size_t  length,
int  flags 
)

Send data on a connected socket.

Refer to your favorite send() man page for more information.

Differences from POSIX: Returns int rather than nonstandard ssize_t.

Parameters
[in]idSocket on which to send.
[in]messageMessage to send.
[in]lengthSize in bytes of message.
[in]flagsSend flags.
Returns
Number of bytes sent (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_sendto()

int etcpal_sendto ( etcpal_socket_t  id,
const void *  message,
size_t  length,
int  flags,
const EtcPalSockAddr dest_addr 
)

Send data on a socket.

Refer to your favorite sendto() man page for more information.

Differences from POSIX: Returns int rather than nonstandard ssize_t. addrlen parameter is omitted because there is only one EtcPal sockaddr type.

Parameters
[in]idSocket on which to send.
[in]messageMessage to send.
[in]lengthSize in bytes of message.
[in]flagsSend flags.
[in]dest_addrAddress to which to send the message.
Returns
Number of bytes sent (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_setblocking()

etcpal_error_t etcpal_setblocking ( etcpal_socket_t  id,
bool  blocking 
)

Change the blocking behavior of a socket.

This is similar to manipulating the O_NONBLOCK flag through the fcntl() function on a BSD socket.

Parameters
[in]idSocket for which to change the blocking behavior.
[in]blockingtrue (socket should block) or false (socket should not block).
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_setsockopt()

etcpal_error_t etcpal_setsockopt ( etcpal_socket_t  id,
int  level,
int  option_name,
const void *  option_value,
size_t  option_len 
)

Set an option value on a socket.

Refer to your favorite setsockopt() man page for more information.

Differences from POSIX: Some overlapping option values are consolidated and some legacy option values are not included. Some value types are different; see the documentation of each possible option value.

Parameters
[in]idSocket for which to set the option value.
[in]levelProtocol level of the option for which to set the value.
[in]option_nameName of the option for which to set the value.
[out]option_valueValue to set for the option.
[in,out]option_lenSize of value pointed to by option_value.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_shutdown()

etcpal_error_t etcpal_shutdown ( etcpal_socket_t  id,
int  how 
)

Shut down part of a full-duplex connection.

Refer to your favorite shutdown() man page for more information.

Parameters
[in]idSocket to be shut down.
[in]howHow to shut down the socket, one of the ETCPAL_SHUT_* values.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).

◆ etcpal_socket()

etcpal_error_t etcpal_socket ( unsigned int  family,
unsigned int  type,
etcpal_socket_t id 
)

Create a socket.

Refer to your favorite socket() man page for more information.

Differences from POSIX: Returns an error code and fills in an output parameter for the socket handle instead of returning the socket handle. Rarely-used 'protocol' parameter is omitted.

Parameters
[in]familyProtocol family that the socket should use.
[in]typeSocket communication type.
[out]idFilled in with socket handle on success. Filled in with ETCPAL_SOCKET_INVALID on failure.
Returns
kEtcPalErrOk (success) or etcpal_error_t code from system (error occurred).