lwpa  0.1.0
LightWeight Platform Abstraction (lwpa)
View other versions:
lwpa_socket

Overview

Platform-neutral BSD-modeled network socket implementation.

#include "lwpa_socket.h"

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. UNIX Network Programming: The Sockets Networking API by Stevens, Fenner, and Rudoff is highly recommended reading for those unfamiliar with this interface.

Data Structures

struct  LwpaLinger
 Option value for LWPA_SO_LINGER. More...
 
struct  LwpaMreq
 Option value for LWPA_MCAST_JOIN_GROUP and LWPA_MCAST_LEAVE_GROUP. More...
 
struct  LwpaPollfd
 A description for a socket to poll with lwpa_poll(). More...
 
struct  LwpaAddrinfo
 A structure containing name and address information about an internet host. More...
 

Macros

#define LWPA_SOCKET_INVALID
 An identifier for an invalid socket handle.
 
#define LWPA_INET_ADDRSTRLEN   16
 Maximum length of the string representation of an IPv4 address.
 
#define LWPA_INET6_ADDRSTRLEN   46
 Maximum length of the string representation of an IPv6 address.
 

Typedefs

typedef UNDEFINED lwpa_socket_t
 A socket handle. More...
 
typedef struct LwpaLinger LwpaLinger
 Option value for LWPA_SO_LINGER.
 
typedef struct LwpaMreq LwpaMreq
 Option value for LWPA_MCAST_JOIN_GROUP and LWPA_MCAST_LEAVE_GROUP.
 
typedef struct LwpaPollfd LwpaPollfd
 A description for a socket to poll with lwpa_poll().
 
typedef struct LwpaAddrinfo LwpaAddrinfo
 A structure containing name and address information about an internet host. More...
 

Functions

lwpa_error_t lwpa_socket_init (void *platform_data)
 Initialize the lwpa_socket module. More...
 
void lwpa_socket_deinit ()
 Deinitialize the lwpa_socket module. More...
 
lwpa_error_t lwpa_accept (lwpa_socket_t id, LwpaSockaddr *address, lwpa_socket_t *conn_sock)
 Accept a connection on a socket. More...
 
lwpa_error_t lwpa_bind (lwpa_socket_t id, const LwpaSockaddr *address)
 Bind a name to a socket. More...
 
lwpa_error_t lwpa_close (lwpa_socket_t id)
 Close a socket. More...
 
lwpa_error_t lwpa_connect (lwpa_socket_t id, const LwpaSockaddr *address)
 Initiate a connection on a socket. More...
 
lwpa_error_t lwpa_getpeername (lwpa_socket_t id, LwpaSockaddr *address)
 Get the name of the connected peer socket. More...
 
lwpa_error_t lwpa_getsockname (lwpa_socket_t id, LwpaSockaddr *address)
 Get socket name. More...
 
lwpa_error_t lwpa_getsockopt (lwpa_socket_t id, int level, int option_name, void *option_value, size_t *option_len)
 Get an option value for a socket. More...
 
lwpa_error_t lwpa_listen (lwpa_socket_t id, int backlog)
 Listen for connections on a socket. More...
 
int lwpa_recv (lwpa_socket_t id, void *buffer, size_t length, int flags)
 Receive data on a connected socket. More...
 
int lwpa_recvfrom (lwpa_socket_t id, void *buffer, size_t length, int flags, LwpaSockaddr *address)
 Receive data on a socket. More...
 
int lwpa_send (lwpa_socket_t id, const void *message, size_t length, int flags)
 Send data on a connected socket. More...
 
int lwpa_sendto (lwpa_socket_t id, const void *message, size_t length, int flags, const LwpaSockaddr *dest_addr)
 Send data on a socket. More...
 
lwpa_error_t lwpa_setsockopt (lwpa_socket_t id, int level, int option_name, const void *option_value, size_t option_len)
 Set an option value on a socket. More...
 
lwpa_error_t lwpa_shutdown (lwpa_socket_t id, int how)
 Shut down part of a full-duplex connection. More...
 
lwpa_socket_t lwpa_socket (unsigned int family, unsigned int type)
 Create a socket. More...
 
lwpa_error_t lwpa_setblocking (lwpa_socket_t id, bool blocking)
 Change the blocking behavior of a socket. More...
 
int lwpa_poll (LwpaPollfd *fds, size_t nfds, int timeout_ms)
 Wait for some event on a set of sockets. More...
 
lwpa_error_t lwpa_getaddrinfo (const char *hostname, const char *service, const LwpaAddrinfo *hints, LwpaAddrinfo *result)
 Get address information for a named internet host and/or service. More...
 
bool lwpa_nextaddr (LwpaAddrinfo *ai)
 Get the next address from the list returned by lwpa_getaddrinfo(). More...
 
void lwpa_freeaddrinfo (LwpaAddrinfo *ai)
 Free an addrinfo list returned by lwpa_getaddrinfo(). More...
 
lwpa_error_t lwpa_inet_ntop (const LwpaIpAddr *src, char *dest, size_t size)
 Convert IPv4 and IPv6 addresses from binary to text form. More...
 
lwpa_error_t lwpa_inet_pton (lwpa_iptype_t type, const char *src, LwpaIpAddr *dest)
 Convert IPv4 and IPv6 addresses from text to binary form. More...
 

Flags for lwpa_recvfrom()

#define LWPA_MSG_PEEK   0x1
 

Level values for lwpa_setsockopt() and lwpa_getsockopt()

Refer to the group of option names for each level.

#define LWPA_SOL_SOCKET   0
 lwpa_socket API level.
 
#define LWPA_IPPROTO_IP   1
 IPv4 protocol level.
 
#define LWPA_IPPROTO_ICMPV6   2
 ICMPv6 protocol level.
 
#define LWPA_IPPROTO_IPV6   3
 IPv6 protocol level.
 
#define LWPA_IPPROTO_TCP   4
 TCP protocol level.
 
#define LWPA_IPPROTO_UDP   5
 UDP protocol level.
 

Options for level LWPA_SOL_SOCKET

Used in the option parameter to lwpa_setsockopt() and lwpa_getsockopt().

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

#define LWPA_SO_BROADCAST   0
 Get/Set, value is boolean int.
 
#define LWPA_SO_ERROR   1
 Get only, value is int representing platform error value.
 
#define LWPA_SO_KEEPALIVE   2
 Get/Set, value is boolean int.
 
#define LWPA_SO_LINGER   3
 Get/Set, value is LwpaLinger.
 
#define LWPA_SO_RCVBUF   4
 Get/Set, value is int representing byte size.
 
#define LWPA_SO_SNDBUF   5
 Get/Set, value is int representing byte size.
 
#define LWPA_SO_RCVTIMEO   6
 Get/Set, value is int representing ms.
 
#define LWPA_SO_SNDTIMEO   7
 Get/Set, value is int representing ms.
 
#define LWPA_SO_REUSEADDR   8
 Get/Set, value is boolean int.
 
#define LWPA_SO_REUSEPORT   9
 Get/Set, value is boolean int.
 
#define LWPA_SO_TYPE   10
 Get only, value is int.
 

Options for level LWPA_IPPROTO_IP or LWPA_IPPROTO_IPV6

Used in the option parameter to lwpa_setsockopt() and lwpa_getsockopt().

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

#define LWPA_IP_TTL   11
 Get/Set, value is int.
 
#define LWPA_IP_MULTICAST_IF   12
 Get/Set, value is LwpaIpAddr.
 
#define LWPA_IP_MULTICAST_TTL   13
 Get/Set, value is int.
 
#define LWPA_IP_MULTICAST_LOOP   14
 Get/Set, value is boolean int.
 
#define LWPA_MCAST_JOIN_GROUP   15
 Set only, value is LwpaMreq.
 
#define LWPA_MCAST_LEAVE_GROUP   16
 Set only, value is LwpaMreq.
 

'how' values for lwpa_shutdown()

#define LWPA_SHUT_RD   0
 
#define LWPA_SHUT_WR   1
 
#define LWPA_SHUT_RDWR   2
 

'family' values for lwpa_socket() and LwpaAddrinfo

#define LWPA_AF_UNSPEC   0
 
#define LWPA_AF_INET   1
 
#define LWPA_AF_INET6   2
 

'type' values for lwpa_socket() and lwpa_getsockopt()

#define LWPA_STREAM   0
 
#define LWPA_DGRAM   1
 

'events' and 'revents' values for LwpaPollfd

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

#define LWPA_POLLIN   0x1
 
#define LWPA_POLLOUT   0x2
 
#define LWPA_POLLPRI   0x4
 
#define LWPA_POLLERR   0x8
 

'flags' values for LwpaAddrinfo

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

#define LWPA_AI_PASSIVE   0x01
 
#define LWPA_AI_CANONNAME   0x02
 
#define LWPA_AI_NUMERICHOST   0x04
 

Typedef Documentation

◆ lwpa_socket_t

typedef UNDEFINED lwpa_socket_t

A socket handle.

Typedefed to the system's socket identifier.

◆ LwpaAddrinfo

typedef struct LwpaAddrinfo LwpaAddrinfo

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

Returned by lwpa_getaddrinfo().

Function Documentation

◆ lwpa_accept()

lwpa_error_t lwpa_accept ( lwpa_socket_t  id,
LwpaSockaddr address,
lwpa_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 lwpa sockaddr 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
LWPA_OK (success) or lwpa_error_t code from system (failure).

◆ lwpa_bind()

lwpa_error_t lwpa_bind ( lwpa_socket_t  id,
const LwpaSockaddr 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 lwpa sockaddr type.

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

◆ lwpa_close()

lwpa_error_t lwpa_close ( lwpa_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 lwpa_* function.

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

◆ lwpa_connect()

lwpa_error_t lwpa_connect ( lwpa_socket_t  id,
const LwpaSockaddr 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 lwpa sockaddr type.

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

◆ lwpa_freeaddrinfo()

void lwpa_freeaddrinfo ( LwpaAddrinfo ai)

Free an addrinfo list returned by lwpa_getaddrinfo().

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

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

◆ lwpa_getaddrinfo()

lwpa_error_t lwpa_getaddrinfo ( const char *  hostname,
const char *  service,
const LwpaAddrinfo hints,
LwpaAddrinfo 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. lwpa uses the lwpa_nextaddr() function instead of a next pointer to iterate over multiple addresses. For example:

if (0 == lwpa_getaddrinfo("www.google.com", "http", NULL, &info))
{
do
{
char inet_str[LWPA_INET6_ADDRSTRLEN];
if (LWPA_OK == lwpa_inet_ntop(&info.ai_addr.ip, inet_str,
{
printf("Address: %s\n", inet_str);
}
else
printf("Address conversion error!\n");
} while (lwpa_nextaddr(&info));
}
@ LWPA_OK
The call was successful, no error occurred.
Definition: lwpa_error.h:39
#define LWPA_INET6_ADDRSTRLEN
Maximum length of the string representation of an IPv6 address.
Definition: lwpa_socket.h:238
int lwpa_getaddrinfo(const char *hostname, const char *service, const LwpaAddrinfo *hints, LwpaAddrinfo *result)
Get address information for a named internet host and/or service.
Definition: lwpa_socket.c:515
void lwpa_freeaddrinfo(LwpaAddrinfo *ai)
Free an addrinfo list returned by lwpa_getaddrinfo().
Definition: lwpa_socket.c:580
lwpa_error_t lwpa_inet_ntop(const LwpaIpAddr *src, char *dest, size_t size)
Convert IPv4 and IPv6 addresses from binary to text form.
Definition: lwpa_socket.c:586
bool lwpa_nextaddr(LwpaAddrinfo *ai)
Get the next address from the list returned by lwpa_getaddrinfo().
Definition: lwpa_socket.c:544
A structure containing name and address information about an internet host.
Definition: lwpa_socket.h:213
LwpaSockaddr ai_addr
Address of host.
Definition: lwpa_socket.h:219
LwpaIpAddr ip
IP address.
Definition: lwpa_inet.h:178

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
LWPA_OK (success) or lwpa_error_t code from system (an error occurred).

◆ lwpa_getpeername()

lwpa_error_t lwpa_getpeername ( lwpa_socket_t  id,
LwpaSockaddr 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 lwpa sockaddr type.

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

◆ lwpa_getsockname()

lwpa_error_t lwpa_getsockname ( lwpa_socket_t  id,
LwpaSockaddr 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 lwpa sockaddr type.

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

◆ lwpa_getsockopt()

lwpa_error_t lwpa_getsockopt ( lwpa_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
LWPA_OK (success) or lwpa_error_t code from system (error occurred).

◆ lwpa_inet_ntop()

lwpa_error_t lwpa_inet_ntop ( const LwpaIpAddr src,
char *  dest,
size_t  size 
)

Convert IPv4 and IPv6 addresses from binary to text form.

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

Differences from POSIX: af parameter is omitted because that information is contained in the struct lwpa_ip.

Parameters
[in]srcAddress to convert to string form.
[out]destFilled in on success with the string-represented address.
[in]sizeSize in bytes of dest buf.
Returns
LWPA_OK: Success.
LWPA_INVALID: Invalid parameter.
LWPA_SYSERR: System call failed.

◆ lwpa_inet_pton()

lwpa_error_t lwpa_inet_pton ( lwpa_iptype_t  type,
const char *  src,
LwpaIpAddr dest 
)

Convert IPv4 and IPv6 addresses from text to binary form.

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

Differences from POSIX: lwpa_iptype_t used instead of AF_* value, since this function is only used for IP addresses.

Parameters
[in]typeType of string-represented IP address pointed to by src.
[in]srcCharacter string containing a string-represented IP address.
[out]destFilled in on success with the address.
Returns
LWPA_OK: Success.
LWPA_INVALID: Invalid parameter.
LWPA_SYSERR: System call failed.

◆ lwpa_listen()

lwpa_error_t lwpa_listen ( lwpa_socket_t  id,
int  backlog 
)

Listen for connections on a socket.

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

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

◆ lwpa_nextaddr()

bool lwpa_nextaddr ( LwpaAddrinfo ai)

Get the next address from the list returned by lwpa_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 addrinfo structs is provided. To get all of the addresses returned from a lwpa_getaddrinfo() call, keep calling this on the result struct until it returns false.

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

◆ lwpa_poll()

int lwpa_poll ( LwpaPollfd fds,
size_t  nfds,
int  timeout_ms 
)

Wait for some event on a set of sockets.

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

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

Parameters
[in,out]fdsSet of socket descriptors to be monitored.
[in]nfdsNumber of LwpaPollfd structs in the fds array.
[in]timeout_msHow long to wait for an event, in milliseconds. Use LWPA_WAIT_FOREVER to wait indefinitely.
Returns
Number of LwpaPollfd structs which have nonzero revents fields (success), LWPA_TIMEDOUT (timed out), or other lwpa_error_t value from the underlying system call (error occurred).

◆ lwpa_recv()

int lwpa_recv ( lwpa_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 lwpa_error_t code from system (error occurred).

◆ lwpa_recvfrom()

int lwpa_recvfrom ( lwpa_socket_t  id,
void *  buffer,
size_t  length,
int  flags,
LwpaSockaddr 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 lwpa 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 lwpa_error_t code from system (error occurred).

◆ lwpa_send()

int lwpa_send ( lwpa_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 lwpa_error_t code from system (error occurred).

◆ lwpa_sendto()

int lwpa_sendto ( lwpa_socket_t  id,
const void *  message,
size_t  length,
int  flags,
const LwpaSockaddr 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 lwpa 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 lwpa_error_t code from system (error occurred).

◆ lwpa_setblocking()

lwpa_error_t lwpa_setblocking ( lwpa_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
LWPA_OK (success) or lwpa_error_t code from system (error occurred).

◆ lwpa_setsockopt()

lwpa_error_t lwpa_setsockopt ( lwpa_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
LWPA_OK (success) or lwpa_error_t code from system (error occurred).

◆ lwpa_shutdown()

lwpa_error_t lwpa_shutdown ( lwpa_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 LWPA_SHUT_* values.
Returns
LWPA_OK (success) or lwpa_error_t code from system (error occurred).

◆ lwpa_socket()

lwpa_socket_t lwpa_socket ( unsigned int  family,
unsigned int  type 
)

Create a socket.

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

Differences from POSIX: Rarely-used 'protocol' parameter is omitted. LWPA_SOCKET_INVALID is the only invalid return value.

Parameters
[in]familyProtocol family that the socket should use.
[in]typeSocket communication type.
Returns
LWPA_SOCKET_INVALID (error occurred) or a value other than LWPA_SOCKET_INVALID (success).

◆ lwpa_socket_deinit()

void lwpa_socket_deinit ( )

Deinitialize the lwpa_socket module.

Some platforms require deinitialization when an application is finished using socket/networking functionality. Others do not, and on those platforms this will simply be an empty function. This function must be called for every time that lwpa_socket_init() is called in an application.

◆ lwpa_socket_init()

lwpa_error_t lwpa_socket_init ( void *  platform_data)

Initialize the lwpa_socket module.

Some platforms require initialization before socket/networking functionality can be used. Others do not, and on those platforms this will simply be an empty function. This function can be called multiple times in a given application, but it must be paired with an equal number of calls to lwpa_socket_deinit().

Parameters
[in]platform_dataA pointer to platform-specific data to use on initialization. The specific type is defined in lwpa_socket_[platform].h if it exists for a platform. NULL indicates use defaults.
Returns
LWPA_OK: Initialization successful.
LWPA_SYSERR: An internal library or system call error occurred.