platform/inc/stbhwnet.h File Reference

Socket functions. More...

Go to the source code of this file.

Data Structures
struct	S_NW_SOCKSET
struct	S_NW_ADDR_INFO
struct	S_NW_ACCESS_POINT
Defines
#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 )(void)
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.
BOOLEAN	STB_NWSelectInterface (E_NW_INTERFACE iface)
	Sets the network interface that will be used for all network or IP operations.
E_NW_LINK_STATUS	STB_NWGetLinkStatus (void)
	Get the ethernet link status.
NW_handle	STB_NWStartEthernetMonitor (NW_eth_callback func)
	Start monitoring the ethernet status.
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.
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.
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.
BOOLEAN	STB_NWCloseSocket (void *socket)
	Closes (destroys) a socket instance.
BOOLEAN	STB_NWBind (void *socket, U8BIT *address, U32BIT port)
	Binds (names) a socket in the local address space.
BOOLEAN	STB_NWSetReuseaddr (void *socket, BOOLEAN state)
	Sets the socket option SO_REUSEADDR.
BOOLEAN	STB_NWGetReuseaddr (void *socket, BOOLEAN *state)
	Gets the socket option SO_REUSEADDR.
BOOLEAN	STB_NWAddMembership (void *socket, U8BIT *group_address)
	Sets the ip option IP_ADD_MEMBERSHIP.
BOOLEAN	STB_NWDropMembership (void *socket, U8BIT *group_address)
	Sets the ip option IP_DROP_MEMBERSHIP.
BOOLEAN	STB_NWGetSocketName (void *socket, E_NW_AF *af, U8BIT *address, U32BIT *port)
	Gets the socket's "name" (family, address and port)
E_NW_ERROR	STB_NWConnect (void *socket, U8BIT *address, U32BIT port)
	Connects the socket to a remote host.
BOOLEAN	STB_NWListen (void *socket, S32BIT backlog)
	Put socket into state of waiting for incoming connection.
void *	STB_NWAccept (void *socket, U8BIT *address, U32BIT *port)
	Accepts an incoming connection attempt on a socket.
S32BIT	STB_NWSend (void *socket, U8BIT *buf, U32BIT num_bytes)
	Sends data on a connected socket.
S32BIT	STB_NWReceive (void *socket, U8BIT *buf, U32BIT max_bytes)
	Receives data from a connected socket.
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.
S32BIT	STB_NWSendTo (void *socket, U8BIT *buf, U32BIT num_bytes, U8BIT *address, U32BIT port)
	Sends data to a specific destination.
BOOLEAN	STB_NWSockIsSet (void *socket, S_NW_SOCKSET *socks)
	Returns whether a specified socket is a member of a specified set.
void	STB_NWSockZero (S_NW_SOCKSET *socks)
	Clears the socket set.
void	STB_NWSockClear (void *socket, S_NW_SOCKSET *socks)
	Clears the specified socket from the specified set.
void	STB_NWSockSet (void *socket, S_NW_SOCKSET *socks)
	Sets a specificed socket in a specified set.
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.
U16BIT	STB_NWGetWirelessAccessPoints (S_NW_ACCESS_POINT **access_points)
	Scans and returns all access points visible on the wireless network.
void	STB_NWFreeWirelessAccessPoints (S_NW_ACCESS_POINT *access_points, U16BIT num_aps)
	Frees the array of access points returned by STB_NWGetWirelessAccessPoints.
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.

---

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 ethernet 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

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