Portable socket adapter

Detailed Description

Platform-specific TCP operations behind a common native interface.

The Socket Example Lib (selib.h/selib.c) is a basic module that provides a platform agnostic socket API. Start with se_connect() for an outbound connection or se_bind()/se_accept() for a listener. Socket storage, timeouts, and blocking behavior depend on the selected port.

Collaboration diagram for Portable socket adapter:

Macros
#define	INFINITE_TMO   (~((U32)0))
	Infinite wait time option for socket read functions. More...
#define	SOCKET   int
	The SOCKET object/handle is an 'int' when using a BSD compatible TCP/IP stack. More...

Functions
int	se_connect (SOCKET *sock, const char *address, U16 port)
	Initializes a SOCKET object connected to a remote host/address at a given port. More...
int	se_bind (SOCKET *sock, U16 port)
	Initializes a SOCKET object bound to a local port, ready to accept client connections. More...
int	se_accept (SOCKET **listenSock, U32 timeout, SOCKET **outSock)
	Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection. More...
void	se_close (SOCKET *sock)
	Close a connected socket connection. More...
int	se_sockValid (SOCKET *sock)
	Check the socket representation using the selected port. More...
S32	se_send (SOCKET *sock, const void *buf, U32 len)
	Sends data to the connected peer. More...
S32	se_recv (SOCKET *sock, void *buf, U32 len, U32 timeout)
	Waits for data sent by peer. More...
void	mainTask (SeCtx *ctx)
	Main entry for all example programs. More...

Macro Definition Documentation

INFINITE_TMO

#define INFINITE_TMO   (~((U32)0))

Infinite wait time option for socket read functions.

SOCKET

#define SOCKET   int

The SOCKET object/handle is an 'int' when using a BSD compatible TCP/IP stack.

Non BSD compatible TCP IP stacks must set the macro NO_BSD_SOCK and define the SOCKET object. See the header file selib.h for details.

Function Documentation

mainTask()

void mainTask

(

SeCtx *

ctx

)

Main entry for all example programs.

Parameters

ctx	Context supplied by the example entry wrapper; bare-metal examples use it for sequential/event-driven switching.

se_accept()

int se_accept	(	SOCKET **	listenSock,
		U32	timeout,
		SOCKET **	outSock
	)

Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection.

Returns

• 1 Success
• 0 timeout
• -1 error

Parameters

listenSock	Required listening-socket argument, initialized by se_bind().
timeout	Wait time in milliseconds, or INFINITE_TMO.
outSock	Required output-socket argument for the accepted connection; use the selected port's SOCKET representation.

se_bind()

int se_bind	(	SOCKET *	sock,
		U16	port
	)

Initializes a SOCKET object bound to a local port, ready to accept client connections.

Returns

Zero on success. Error codes returned:

• -1 Cannot create socket: Fatal
• -2 Cannot listen: Fatal
• -3 Cannot bind: socket in use

Parameters

sock	Required socket storage to initialize.
port	Local TCP port number.

se_close()

void se_close

(

SOCKET *

sock

)

Close a connected socket connection.

Parameters

sock	Required socket to close and invalidate.

se_connect()

int se_connect	(	SOCKET *	sock,
		const char *	address,
		U16	port
	)

Initializes a SOCKET object connected to a remote host/address at a given port.

Returns

Zero on success. Error codes returned:

• -1 Cannot create socket: Fatal
• -2 Cannot resolve 'address'
• -3 Cannot connect

Parameters

sock	Required socket storage to initialize.
address	Required NUL-terminated host name or address.
port	Remote TCP port number.

se_recv()

S32 se_recv	(	SOCKET *	sock,
		void *	buf,
		U32	len,
		U32	timeout
	)

Waits for data sent by peer.

Parameters

sock	the SOCKET object.
buf	Required writable buffer for received data.
len	Capacity of buf in bytes.
timeout	in milliseconds. The timeout can be set to INFINITE_TMO.

Returns

the length of the data read, zero on timeout, or a negative value on error.

se_send()

S32 se_send	(	SOCKET *	sock,
		const void *	buf,
		U32	len
	)

Sends data to the connected peer.

Parameters

sock	Required connected socket.
buf	Readable payload retained through the call.
len	Payload length in bytes.

Returns

Number of bytes sent, or a negative transport error. Check the selected port for partial-send behavior.

se_sockValid()

int se_sockValid

(

SOCKET *

sock

)

Check the socket representation using the selected port.

Parameters

sock	Required socket argument to inspect.

Returns

Nonzero when the port considers the socket valid, zero otherwise. This is not a peer-liveness probe; I/O can still report a closed connection.