lwpa
0.1.0
LightWeight Platform Abstraction (lwpa)
|
View other versions:
|
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() | |
#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 |
typedef UNDEFINED lwpa_socket_t |
A socket handle.
Typedefed to the system's socket identifier.
typedef struct LwpaAddrinfo LwpaAddrinfo |
A structure containing name and address information about an internet host.
Returned by lwpa_getaddrinfo().
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.
[in] | id | Listening socket on which to accept a new connection. |
[out] | address | Remote address from which the connection was accepted. |
[out] | conn_sock | Filled in on success with handle to connected socket. |
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.
[in] | id | Socket to which to bind an address (traditionally called a 'name'). |
[in] | address | Address to assign to the socket. |
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.
[in] | id | Socket to close. |
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.
[in] | id | Socket to connect. |
[in] | address | Address to which to connect. |
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().
[in] | ai | Pointer to lwpa_addrinfo struct for which to free the platform memory. |
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:
On an internet-connected machine with DNS resolution capability, the above code should print something like:
[in] | hostname | Either a string-represented numerical network address or a network hostname to resolve. |
[in] | service | Either a string-represented numerical port number or a service name. |
[in] | hints | Structure containing hints restricting the address types that can be returned. |
[out] | result | On success, filled in with the first address result. |
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.
[in] | id | Connected socket for which to get the peer address. |
[in] | address | Filled in with peer address on success. |
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.
[in] | id | Connected socket for which to get the bound address. |
[in] | address | Filled in with bound address on success. |
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.
[in] | id | Socket for which to get the option value. |
[in] | level | Protocol level of the option for which to get the value. |
[in] | option_name | Name of the option for which to get the value. |
[out] | option_value | Filled in with option value on success. |
[in,out] | option_len | Contains size of buffer pointed to by option_value, filled in with actual size of value returned. |
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.
[in] | src | Address to convert to string form. |
[out] | dest | Filled in on success with the string-represented address. |
[in] | size | Size in bytes of dest buf. |
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.
[in] | type | Type of string-represented IP address pointed to by src. |
[in] | src | Character string containing a string-represented IP address. |
[out] | dest | Filled in on success with the address. |
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.
[in] | id | LWPA_STREAM socket on which to listen. |
[in] | backlog | Maximum length of pending connection queue. |
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.
[in,out] | ai | Pointer to last lwpa_addrinfo struct, filled in with values of the next address. |
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.
[in,out] | fds | Set of socket descriptors to be monitored. |
[in] | nfds | Number of LwpaPollfd structs in the fds array. |
[in] | timeout_ms | How long to wait for an event, in milliseconds. Use LWPA_WAIT_FOREVER to wait indefinitely. |
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.
[in] | id | Socket on which to receive. |
[out] | buffer | Buffer in which to place received data. |
[in] | length | Size in bytes of buffer. |
[in] | flags | Receive flags. |
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.
[in] | id | Socket on which to receive. |
[out] | buffer | Buffer in which to place received data. |
[in] | length | Size in bytes of buffer. |
[in] | flags | Receive flags. |
[out] | address | If provided, filled in on success with peer address from which the data was received. |
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.
[in] | id | Socket on which to send. |
[in] | message | Message to send. |
[in] | length | Size in bytes of message. |
[in] | flags | Send flags. |
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.
[in] | id | Socket on which to send. |
[in] | message | Message to send. |
[in] | length | Size in bytes of message. |
[in] | flags | Send flags. |
[in] | dest_addr | Address to which to send the message. |
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.
[in] | id | Socket for which to change the blocking behavior. |
[in] | blocking | true (socket should block) or false (socket should not block). |
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.
[in] | id | Socket for which to set the option value. |
[in] | level | Protocol level of the option for which to set the value. |
[in] | option_name | Name of the option for which to set the value. |
[out] | option_value | Value to set for the option. |
[in,out] | option_len | Size of value pointed to by option_value. |
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.
[in] | id | Socket to be shut down. |
[in] | how | How to shut down the socket, one of the LWPA_SHUT_* values. |
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.
[in] | family | Protocol family that the socket should use. |
[in] | type | Socket communication type. |
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_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().
[in] | platform_data | A 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. |