Socket functions. More...

#include "techtype.h"

Data Structures
struct	S_NW_SOCKSET

struct	S_NW_ADDR_INFO

struct	S_NW_ACCESS_POINT

Macros
#define	MAX_ADDR_STRING_LEN 255

#define	SOCK_SETSIZE 64

#define	SOCK_CLR(sock, set) STB_NWSockClear((sock), (set));

#define	SOCK_SET(sock, set) STB_NWSockSet((sock), (set));

#define	SOCK_ZERO(set) STB_NWSockZero((set))

#define	SOCK_ISSET(sock, set) STB_NWSockIsSet((sock), (set))

#define	INVALID_SOCKET 0

Typedefs
typedef void(*	NW_eth_callback )(E_NW_INTERFACE iface, E_NW_LINK_STATUS iface_status)

typedef void *	NW_handle

Enumerations
enum	E_NW_INTERFACE { NW_WIRED, NW_WIRELESS }

enum	E_NW_AF { NW_AF_INET, NW_AF_INET6 }

enum	E_NW_TYPE { NW_SOCK_STREAM, NW_SOCK_DGRAM }

enum	E_NW_PROTOCOL { NW_PROTOCOL_TCP, NW_PROTOCOL_UDP }

enum	E_NW_LINK_STATUS { NW_LINK_ACTIVE, NW_LINK_INACTIVE, NW_LINK_DISABLED }

enum	E_NW_ERROR { NW_OK, NW_ERROR, NW_BAD_PARAM, NW_PENDING }

Functions
BOOLEAN	STB_NWInitialise (void)
	Initialises the socket API, must be called once before using API. More...

BOOLEAN	STB_NWSelectInterface (E_NW_INTERFACE iface)
	Sets the network interface that will be used for all network or IP operations. More...

E_NW_INTERFACE	STB_NWGetSelectedInterface (void)
	Returns the selected interface. More...

E_NW_LINK_STATUS	STB_NWGetLinkStatus (void)
	Get the selected interface link status. More...

NW_handle	STB_NWStartEthernetMonitor (NW_eth_callback func)
	Start monitoring the ethernet status. More...

void	STB_NWStopEthernetMonitor (NW_handle hdl)
	Stop monitoring the ethernet status.

BOOLEAN	STB_NWGetMACAddress (E_NW_INTERFACE iface, U8BIT *mac_addr)
	Gets the MAC address of the default ethernet connection. More...

U16BIT	STB_NWLookupAddress (U8BIT name, S_NW_ADDR_INFO *nw_addrs)
	Performs a lookup to find the IP address(es) of the given host name. More...

void *	STB_NWOpenSocket (E_NW_AF af, E_NW_TYPE type, E_NW_PROTOCOL protocol, BOOLEAN nonblock)
	Opens (creates) a new socket for subsequent use. More...

BOOLEAN	STB_NWCloseSocket (void *socket)
	Closes (destroys) a socket instance. More...

BOOLEAN	STB_NWBind (void socket, U8BIT address, U32BIT port)
	Binds (names) a socket in the local address space. More...

BOOLEAN	STB_NWSetReuseaddr (void *socket, BOOLEAN state)
	Sets the socket option SO_REUSEADDR. More...

BOOLEAN	STB_NWGetReuseaddr (void socket, BOOLEAN state)
	Gets the socket option SO_REUSEADDR. More...

BOOLEAN	STB_NWAddMembership (void socket, U8BIT group_address)
	Sets the ip option IP_ADD_MEMBERSHIP. More...

BOOLEAN	STB_NWDropMembership (void socket, U8BIT group_address)
	Sets the ip option IP_DROP_MEMBERSHIP. More...

BOOLEAN	STB_NWGetSocketName (void socket, E_NW_AF af, U8BIT address, U32BIT port)
	Gets the socket's "name" (family, address and port) More...

E_NW_ERROR	STB_NWConnect (void socket, U8BIT address, U32BIT port)
	Connects the socket to a remote host. More...

BOOLEAN	STB_NWListen (void *socket, S32BIT backlog)
	Put socket into state of waiting for incoming connection. More...

void *	STB_NWAccept (void socket, U8BIT address, U32BIT *port)
	Accepts an incoming connection attempt on a socket. More...

S32BIT	STB_NWSend (void socket, U8BIT buf, U32BIT num_bytes)
	Sends data on a connected socket. More...

S32BIT	STB_NWReceive (void socket, U8BIT buf, U32BIT max_bytes)
	Receives data from a connected socket. More...

S32BIT	STB_NWReceiveFrom (void socket, U8BIT buf, U32BIT max_bytes, U8BIT address, U32BIT port)
	Receives a datagram and returns the data and its source address. More...

S32BIT	STB_NWSendTo (void socket, U8BIT buf, U32BIT num_bytes, U8BIT *address, U32BIT port)
	Sends data to a specific destination. More...

BOOLEAN	STB_NWSockIsSet (void socket, S_NW_SOCKSET socks)
	Returns whether a specified socket is a member of a specified set. More...

void	STB_NWSockZero (S_NW_SOCKSET *socks)
	Clears the socket set. More...

void	STB_NWSockClear (void socket, S_NW_SOCKSET socks)
	Clears the specified socket from the specified set. More...

void	STB_NWSockSet (void socket, S_NW_SOCKSET socks)
	Sets a specificed socket in a specified set. More...

S32BIT	STB_NWSelect (S_NW_SOCKSET read_sockets, S_NW_SOCKSET write_sockets, S_NW_SOCKSET *except_sockets, S32BIT timeout_ms)
	Determines the status of one or more sockets, blocking if necessary. More...

U16BIT	STB_NWGetWirelessAccessPoints (S_NW_ACCESS_POINT **access_points)
	Scans and returns all access points visible on the wireless network. More...

void	STB_NWFreeWirelessAccessPoints (S_NW_ACCESS_POINT *access_points, U16BIT num_aps)
	Frees the array of access points returned by STB_NWGetWirelessAccessPoints. More...

BOOLEAN	STB_NWConnectToAccessPoint (U8BIT essid, U8BIT password)
	Attempts to connect to the wireless network with the given SSID. If the network is open then 'password' can be NULL. More...

Detailed Description

Socket functions.

Date: 24/06/2009

Author: Sergio Panseri

Function Documentation

void* STB_NWAccept	(	void *	socket,
		U8BIT *	address,
		U32BIT *	port
	)

Accepts an incoming connection attempt on a socket.

Parameters

void*	socket the handle of the socket in the listening state
U8BIT*	address pointer to the returned address (string) of connecting entity
U32BIT*	port pointer to the returned port of connecting entity

Returns: handle of new socket actually connected, NULL if failed

BOOLEAN STB_NWAddMembership	(	void *	socket,
		U8BIT *	group_address
	)

Sets the ip option IP_ADD_MEMBERSHIP.

Parameters

void*	socket the handle of the socket
U8BIT	*group_address address to add

Returns: TRUE successfully set, FALSE failed to set

BOOLEAN STB_NWBind	(	void *	socket,
		U8BIT *	address,
		U32BIT	port
	)

Binds (names) a socket in the local address space.

Parameters

socket	the handle of the socket to be bound
address	the string address (NULL to let OS choose)
port	the port number to be bound to (zero to let OS choose)

Returns: TRUE successfully bound, FALSE failed to bind

BOOLEAN STB_NWCloseSocket ( void * socket )

Closes (destroys) a socket instance.

Parameters

socket handle of the socket to be closed

Returns: TRUE success, FALSE error

E_NW_ERROR STB_NWConnect	(	void *	socket,
		U8BIT *	address,
		U32BIT	port
	)

Connects the socket to a remote host.

Parameters

void*	socket the handle of the socket
U8BIT*	address address string
U32BIT	port port

Returns: TRUE successfully connected, FALSE failed to set

BOOLEAN STB_NWConnectToAccessPoint	(	U8BIT *	essid,
		U8BIT *	password
	)

Attempts to connect to the wireless network with the given SSID. If the network is open then 'password' can be NULL.

Parameters

essid	network to connect to
password	password to be used for an encrypted network, can be NULL for an open network

Returns: TRUE if connected successfully to the network, FALSE otherwise

BOOLEAN STB_NWDropMembership	(	void *	socket,
		U8BIT *	group_address
	)

Sets the ip option IP_DROP_MEMBERSHIP.

Parameters

void*	socket the handle of the socket
U8BIT	*group_address address to drop

Returns: TRUE successfully set, FALSE failed to set

void STB_NWFreeWirelessAccessPoints	(	S_NW_ACCESS_POINT *	access_points,
		U16BIT	num_aps
	)

Frees the array of access points returned by STB_NWGetWirelessAccessPoints.

Parameters

access_points	array of access points to be freed
num_aps	number of access points in the array

E_NW_LINK_STATUS STB_NWGetLinkStatus ( void )

Get the selected interface link status.

Returns: NW_LINK_ACTIVE cable connected, NW_LINK_INACTIVE cable dis-connected NW_LINK_DISABLED no ethernet device or other error

BOOLEAN STB_NWGetMACAddress	(	E_NW_INTERFACE	iface,
		U8BIT *	mac_addr
	)

Gets the MAC address of the default ethernet connection.

Parameters

interface	NW_WIRED or NW_WIRELESS
mac_address	6 byte array in which the address will be returned with the most significant byte in mac_addr[0]

Return values

TRUE	if address is returned, FALSE otherwise

BOOLEAN STB_NWGetReuseaddr	(	void *	socket,
		BOOLEAN *	state
	)

Gets the socket option SO_REUSEADDR.

Parameters

void	*socket the handle of the socket
BOOLEAN	*state pointer to the returned state, TRUE or FALSE if the option is active/inactive

Returns: TRUE successfully got, FALSE failed to get

E_NW_INTERFACE STB_NWGetSelectedInterface ( void )

Returns the selected interface.

Returns: Selected interface

BOOLEAN STB_NWGetSocketName	(	void *	socket,
		E_NW_AF *	af,
		U8BIT *	address,
		U32BIT *	port
	)

Gets the socket's "name" (family, address and port)

Parameters

void*	socket the handle of the socket
E_NW_AF*	af pointer to the returned family
U8BIT*	address pointer to the returned address string
U32BIT*	port pointer to the returned port

Returns: TRUE successfully set, FALSE failed to set

U16BIT STB_NWGetWirelessAccessPoints ( S_NW_ACCESS_POINT ** access_points )

Scans and returns all access points visible on the wireless network.

Parameters

access_points pointer to an array that will be allocated containing info on each access point found

Returns: number of access points found

BOOLEAN STB_NWInitialise ( void )

Initialises the socket API, must be called once before using API.

Returns: TRUE Socket API initialised ok, FALSE error

BOOLEAN STB_NWListen	(	void *	socket,
		S32BIT	backlog
	)

Put socket into state of waiting for incoming connection.

Parameters

void*	socket the handle of the socket to begin listening
backlog	the maximum length of the queue of pending connections

Returns: TRUE successfully connected, FALSE failed to set

U16BIT STB_NWLookupAddress	(	U8BIT *	name,
		S_NW_ADDR_INFO **	nw_addrs
	)

Performs a lookup to find the IP address(es) of the given host name.

Parameters

name	host name
nw_addrs	array of structures containing the results of the lookup. This array must be deleted using STB_MEMFreeSysRAM.

Returns: The number of addresses returned in the array

void* STB_NWOpenSocket	(	E_NW_AF	af,
		E_NW_TYPE	type,
		E_NW_PROTOCOL	protocol,
		BOOLEAN	nonblock
	)

Opens (creates) a new socket for subsequent use.

Parameters

af	the address family that the socket will be used with
type	the stream type the socket will be used with
protocol	the protocol the socket will be used with

Returns: The socket handle, or NULL if failed

S32BIT STB_NWReceive	(	void *	socket,
		U8BIT *	buf,
		U32BIT	max_bytes
	)

Receives data from a connected socket.

Parameters

void*	socket the handle of the socket from which to read
U8BIT*	buf the buffer to hold the read data
U32BIT	max_bytes the maximum bytes the caller can accept in the buffer

Returns: the number of bytes read, -1 if there was an error reading 0 if the connection was closed

S32BIT STB_NWReceiveFrom	(	void *	socket,
		U8BIT *	buf,
		U32BIT	max_bytes,
		U8BIT *	address,
		U32BIT *	port
	)

Receives a datagram and returns the data and its source address.

Parameters

void*	socket the handle of the socket from which to read
U8BIT*	buf the buffer to hold the read data
U32BIT	max_bytes the maximum bytes the caller can accept in the buffer
U8BIT*	address the source address of the data in string form
U32BIT*	port the source port of the data

Returns: the number of bytes read, -1 if there was an error reading 0 if the connection was closed

S32BIT STB_NWSelect	(	S_NW_SOCKSET *	read_sockets,
		S_NW_SOCKSET *	write_sockets,
		S_NW_SOCKSET *	except_sockets,
		S32BIT	timeout_ms
	)

Determines the status of one or more sockets, blocking if necessary.

Parameters

S_NW_SOCKSET	*read_sockets set of sockets to be checked for readability
S_NW_SOCKSET	*write_sockets set of sockets to be checked for writability
S_NW_SOCKSET	*exceptfds set of sockets to be checked for errors
U32BIT	timeout_ms maximum number of milliseconds to wait (-1 to block, 0 to return immediately)

Returns: the total number of sockets that are ready, 0 time out exceeded, -1 an error occured

BOOLEAN STB_NWSelectInterface ( E_NW_INTERFACE iface )

Sets the network interface that will be used for all network or IP operations.

Parameters

interface network interface type to use

Return values

TRUE	if interface is available, FALSE otherwise

S32BIT STB_NWSend	(	void *	socket,
		U8BIT *	buf,
		U32BIT	num_bytes
	)

Sends data on a connected socket.

Parameters

void*	socket the handle of the (connected) socket on which to send
U8BIT*	buf the buffer holding the data to be sent
U32BIT	num_bytes the number of bytes in buf to be sent

Returns: the number of bytes sent (may be less than num_bytes)' -1 if failed

S32BIT STB_NWSendTo	(	void *	socket,
		U8BIT *	buf,
		U32BIT	num_bytes,
		U8BIT *	address,
		U32BIT	port
	)

Sends data to a specific destination.

Parameters

void*	socket the handle of the socket on which to send
U8BIT*	buf the buffer holding the data to be sent
U32BIT	num_bytes the number of bytes in buf to be sent
U8BIT*	address the address (in string form) of the target socket
U32BIT	port the port number of the target socket

Returns: the number of bytes sent (may be less than num_bytes), -1 if failed

BOOLEAN STB_NWSetReuseaddr	(	void *	socket,
		BOOLEAN	state
	)

Sets the socket option SO_REUSEADDR.

Parameters

void	*socket the handle of the socket to be bound
BOOLEAN	state TRUE or FALSE to activate/deactivate the option REUSEADDR

Returns: TRUE successfully set, FALSE failed to set

void STB_NWSockClear	(	void *	socket,
		S_NW_SOCKSET *	socks
	)

Clears the specified socket from the specified set.

Parameters

void*	socket The socket to clear
S_NW_SOCKSET	*socks The set of sockets

BOOLEAN STB_NWSockIsSet	(	void *	socket,
		S_NW_SOCKSET *	socks
	)

Returns whether a specified socket is a member of a specified set.

Parameters

void*	socket The socket to check
S_NW_SOCKSET	*socks The set of sockets to check

Returns: TRUE socket is a member of set, FALSE socket is not a member of set

void STB_NWSockSet	(	void *	socket,
		S_NW_SOCKSET *	socks
	)

Sets a specificed socket in a specified set.

Parameters

void*	socket The socket to set
S_NW_SOCKSET	*socks The set of sockets

void STB_NWSockZero ( S_NW_SOCKSET * socks )

Clears the socket set.

Parameters

S_NW_SOCKSET *socks The set of sockets to check

NW_handle STB_NWStartEthernetMonitor ( NW_eth_callback func )

Start monitoring the ethernet status.

Parameters

func	callback function to notify status change to ethernet device

Returns: handle

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation