NDK Stack Documentation: inc/socket.h File Reference


Functions
_extern SOCKET	accept (SOCKET s, PSA pName, int *plen)
_extern int	bind (SOCKET s, PSA pName, int len)
_extern int	connect (SOCKET s, PSA pName, int len)
_extern int	getpeername (SOCKET s, PSA pName, int *plen)
_extern int	getsockname (SOCKET s, PSA pName, int *plen)
_extern int	getsockopt (SOCKET s, int level, int op, void pbuf, int pbufsize)
_extern int	listen (SOCKET s, int maxcon)
_extern int	recv (SOCKET s, void *pbuf, int size, int flags)
_extern int	recvfrom (SOCKET s, void pbuf, int size, int flags, PSA pName, int plen)
_extern int	recvnc (SOCKET s, void *ppbuf, int flags, HANDLE pHandle)
_extern int	recvncfrom (SOCKET s, void *ppbuf, int flags, PSA pName, int plen, HANDLE *pHandle)
_extern int	send (SOCKET s, void *pbuf, int size, int flags)
_extern int	sendto (SOCKET s, void *pbuf, int size, int flags, PSA pName, int len)
_extern int	setsockopt (SOCKET s, int level, int op, void *pbuf, int bufsize)
_extern int	shutdown (SOCKET s, int how)
_extern SOCKET	socket (int domain, int type, int protocol)
_extern int	getsendncbuff (SOCKET s, UINT32 bufSize, void *phBuf, HANDLE phPkt)
_extern int	sendnc (SOCKET s, void *pbuf, int size, HANDLE hPkt, int flags)
_extern int	pipe (HANDLE pfd1, HANDLE pfd2)

Detailed Description

Function Documentation

_extern SOCKET accept	(	SOCKET	s,
		PSA	pName,
		int *	plen
	)

Description
This function extracts the first pending connection request in the socket queue and spawns a new socket to accept the incoming connection request. This function call is valid only for connection-oriented socket types like TCP.

Parameters:

`[in]`	s	Handle to local bound socket that is waiting/listening on any incoming connections. The argument s is a socket that has been created using "socket" function call, bound to a local address using "bind" and listening for connections with "listen" function calls.
`[in]`	pName	Handle to the sockaddr structure that holds the peer host's address and port information.
`[in]`	plen	Holds the length of the sockaddr structure being passed as argument to this function.
`[out]`	pName	Handle to the sockaddr structure that holds the connected peer's address and port information. The exact format of this is based on the address family. Valid only when this function returns success.
`[out]`	plen	Holds the length of the connected peer's sockaddr structure. The exact length depends on the address family of the socket created. Valid only when the function returns success.

Return values:

	Success	- Handle to the new socket created
	Error	- INVALID_SOCKET

_extern int bind	(	SOCKET	s,
		PSA	pName,
		int	len
	)

Description
This function assigns a name to an unnamed socket. When a socket is created using "socket()" call, it exists in a name space (address family) but has no name assigned. The bind() function requests that name be assigned to the socket.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pName	Handle to the sockaddr structure that holds the local address and port information that needs to be assigned to the socket.
`[in]`	len	Holds the length of the sockaddr structure being passed as argument to this function. This in turn depends on the address family of the socket.

Return values:

	Success	- 0
	Error	- -1

_extern int connect	(	SOCKET	s,
		PSA	pName,
		int	len
	)

Description
This function establishes a logical connection from the socket specified by s to the foreign name (address) specified by pName.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pName	Handle to the sockaddr structure that holds the remote host's address and port information to which the socket needs to connect to. For UDP/SOCK_DGRAM socket pName specifies the address to which packets would be sent by default or can be received from. For TCP/SOCK_STREAM socket this call attempts to make a connection to the socket that is bound to address specified by pName.
`[in]`	len	Holds the length of the sockaddr structure being passed as argument to this function. This in turn depends on the address family of the socket.

Return values:

	Success	- 0
	Error	- -1

_extern int getpeername	(	SOCKET	s,
		PSA	pName,
		int *	plen
	)

Description
The getpeername() function retrieves the peer address of the specified socket, store this address in the sockaddr structure pointed to by the pName argument, and store the length of this address in plen argument.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[out]`	pName	Handle to the sockaddr structure that holds the remote host's address and port information to which the socket is connected to. Valid only when this function returns success.
`[out]`	plen	Holds the length of the sockaddr structure being passed as result from this function. Valid only when this function returns success.

Return values:

	Success	- 0
	Error	- -1

_extern int getsendncbuff	(	SOCKET	s,
		UINT32	bufSize,
		void **	phBuf,
		HANDLE *	phPkt
	)

Description
This function allocates bufSize bytes memory for the data buffer and required memory for the packet buffer to hold this data. On successful memory allocation, it initializes the phBuf and phPkt pointers with the data buffer and packet buffer handles. The data buffer obtained from this API can be used by the application to fill in required data. The application then would need to use the data buffer and packet buffer handles in its call to sendnc() API to send the packet out without any copy on transmit path by the stack. The packet and data buffers are freed up automatically once the packet transmission is completed in the ethernet driver. However, if for some reason the application would like to free the buffer and packet obtained using this call, it can to do so by passing the packet buffer handle to sendncfree() API call and it would free up both the packet and data buffers.

This API is currently only supported for AF_RAWETH family sockets.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	bufSize	Size of data buffer to allocate memory for.
`[in]`	phBuf	Pointer to data buffer handle in which the application can fill in the required data to send using sendnc() API.

Parameters:

[in] phPkt Pointer to the packet buffer handle which holds the data buffer in turn.

Return values:

	Success	- 0
	Error	- -1

_extern int getsockname	(	SOCKET	s,
		PSA	pName,
		int *	plen
	)

Description
The getsockname() function retrieves the local address of the specified socket, store this address in the sockaddr structure pointed to by the pName argument, and store the length of this address in plen argument.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[out]`	pName	Handle to the sockaddr structure that holds the local host's address and port information to which the socket is bound to. Valid only when this function returns success.
`[out]`	plen	Holds the length of the sockaddr structure being passed as result from this function. Valid only when this function returns success.

Return values:

	Success	- 0
	Error	- -1

_extern int getsockopt	(	SOCKET	s,
		int	level,
		int	op,
		void *	pbuf,
		int *	pbufsize
	)

Description
This function returns the options associated with a socket.

Parameters:

`[in]`	s	Socket handle
`[in]`	level	Option level (SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6,IPPROTO_TCP)
`[in]`	op	Socket option to get
`[in]`	pbuf	Pointer to memory buffer
`[in]`	pbufsize	Pointer to size of memory buffer

Return values:

	Success	- 0
	Error	- -1

_extern int listen	(	SOCKET	s,
		int	maxcon
	)

Description
This function enables the socket to wait for any incoming connection requests. It also configures the size of the pending connection request queue of the socket. This call is applicable only for connection oriented sockets (SOCK_STREAM/TCP).

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	maxcon	Specifies the maximum length of the queue of pending connections.

Return values:

	Success	- 0
	Error	- -1

_extern int pipe	(	HANDLE *	pfdret1,
		HANDLE *	pfdret2
	)

Description
Creates a pre-connected full duplex pipe. The returned file descriptors can be used with all the fd file descriptor functions, as well as the send() and recv() socket functions.

Parameters:

`[in]`	pfdret1	Pointer to file descriptor to first end of pipe.
`[in]`	pfdret2	Pointer to file descriptor to second end of pipe.

Return values:

	Success	- 0
	Error	- -1

_extern int recv	(	SOCKET	s,
		void *	pbuf,
		int	size,
		int	flags
	)

Description
This function is used to read data received on a specified socket.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pbuf	Specifies the buffer to which the data has to be copied to.
`[in]`	size	Specifies the maximum size of the buffer.
`[in]`	flags	Options flags

Return values:

	Success	- Number of bytes of data received successfully
	Error	- -1

_extern int recvfrom	(	SOCKET	s,
		void *	pbuf,
		int	size,
		int	flags,
		PSA	pName,
		int *	plen
	)

Description
This function attempts to receive data from a socket. It is normally called with unconnected, non-connection oriented sockets. The data is placed into the buffer specified by pbuf, up to a maximum length specified by size. The options in flags can be used to change the default behavior of the operation. The name (address) of the sender is written to pName.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pbuf	Specifies the buffer to which the data has to be copied to.
`[in]`	size	Specifies the maximum size of the buffer.
`[in]`	flags	Options flags
`[out]`	pName	Pointer to place name (address) of sender
`[out]`	plen	Pointer to size of pName

Return values:

	Success	- Number of bytes of data received successfully
	Error	- -1

_extern int recvnc	(	SOCKET	s,
		void **	ppbuf,
		int	flags,
		HANDLE *	phFrag
	)

Description
This function is used to read data received on a specified socket without copying. This is supported only on IPv4/AF_INET family and Raw ethernet/AF_RAWETH sockets.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[out]`	ppbuf	Pointer to receive data buffer pointer.
`[in]`	flags	Options flags
`[out]`	phFrag	Pointer to receive buffer handle.

Return values:

	Success	- Number of bytes of data received successfully
	Error	- -1

Returns 0 on connection oriented sockets where the connection has been closed by the peer (or socket shutdown for read)

_extern int recvncfrom	(	SOCKET	s,
		void **	ppbuf,
		int	flags,
		PSA	pName,
		int *	plen,
		HANDLE *	phFrag
	)

Description
This function attempts to receive data from a socket. It is normally called with unconnected, non-connection oriented sockets. A pointer to data is returned in ppbuf. A system handle used to free the buffer is returned in phFrag. Both of these pointers must be valid. The name (address) of the sender is written to pName. This function is only valid for IPv4/AF_INET family sockets.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[out]`	ppbuf	Pointer to receive data buffer pointer.
`[in]`	flags	Options flags
`[out]`	pName	Pointer to place name (address) of sender
`[out]`	plen	Pointer to size of pName
`[out]`	phFrag	Pointer to receive buffer handle.

Return values:

	Success	- Number of bytes of data received successfully
	Error	- -1

Returns 0 on connection oriented sockets where the connection has been closed by the peer (or socket shutdown for read)

_extern int send	(	SOCKET	s,
		void *	pbuf,
		int	size,
		int	flags
	)

Description
This function attempts to send data on a socket. It is used on connected sockets only. The data to send is contained in the buffer specified by pbuf, with a length specified by size. The options in flags can be used to change the default behavior of the operation. The functions returns the length of the data transmitted on successful completion.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pbuf	Data buffer holding data to transmit
`[in]`	size	Size of data.
`[in]`	flags	Options flags

Return values:

	Success	- Number of bytes of data sent successfully
	Error	- -1

_extern int sendnc	(	SOCKET	s,
		void *	pbuf,
		int	size,
		HANDLE	hPkt,
		int	flags
	)

Description
This function attempts to send data on a socket without copy. The data to send is contained in the buffer specified by pbuf, with a length specified by size. Also, a valid handle to the packet buffer hPkt needs to be specified. This packet handle and the buffer pointer should have been obtained from getsendncbuf() call before calling this API. The options in flags can be used to change the default behavior of the operation. The functions returns the length of the data transmitted on successful completion.

This API is currently only supported for AF_RAWETH family sockets.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pbuf	Data buffer holding data to transmit
`[in]`	size	Size of data.
`[in]`	hPkt	packet handle obtained previously from getsendncbuf() call.
`[in]`	flags	Options flags

Return values:

	Success	- Number of bytes of data sent successfully
	Error	- -1

_extern int sendto	(	SOCKET	s,
		void *	pbuf,
		int	size,
		int	flags,
		PSA	pName,
		int	len
	)

Description
This function attempts to send data on a socket to a specified destination. It is used on unconnected, non-connection oriented \ sockets only. The data to send is contained in the buffer specified by pbuf, with a length specified by size. The options in flags can be used to change the default behavior of the operation.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	pbuf	Data buffer holding data to transmit
`[in]`	size	Size of data.
`[in]`	flags	Options flags
`[out]`	pName	Pointer to name (address) of destination
`[out]`	len	size of pName

Return values:

	Success	- Number of bytes of data sent successfully
	Error	- -1

_extern int setsockopt	(	SOCKET	s,
		int	level,
		int	op,
		void *	pbuf,
		int	bufsize
	)

Description
This function sets the option values associated with a socket.

Parameters:

`[in]`	s	Socket handle
`[in]`	level	Option level (SOL_SOCKET, IPPROTO_IP, IPPROTO_IPV6,IPPROTO_TCP)
`[in]`	op	Socket option to set
`[in]`	pbuf	Pointer to memory buffer
`[in]`	bufsize	Size of memory buffer pointed to by pbuf

Return values:

	Success	- 0
	Error	- -1

_extern int shutdown	(	SOCKET	s,
		int	how
	)

Description
This function causes all or part of a full-duplex connection on the socket associated with a socket to be shut down. If how is SHUT_RD (0), further receives will be disallowed. If how is SHUT_WR (1), further sends will be disallowed. If how is SHUT_RDWR (2), further sends and receives will be disallowed.

Parameters:

`[in]`	s	Handle to a socket obtained using "socket" function call.
`[in]`	how	Manner of shutdown.

Return values:

	Success	- 0
	Error	- -1

_extern SOCKET socket	(	int	domain,
		int	type,
		int	protocol
	)

Description
This function creates a socket, an endpoint for communication and returns the socket in the form of a file descriptor.

Parameters:

`[in]`	domain	Socket domain/family. Valid values are AF_INET/AF_INET6.
`[in]`	type	Socket type (SOCK_DGRAM, SOCK_STREAM, SOCK_RAW).
`[in]`	protocol	Socket protocol (Normally IPPROTO_TCP or IPPROTO_UDP, but can be anything when type is set to SOCK_RAW)

Return values:

	Success	- socket handle
	Error	- INVALID_SOCKET

inc/socket.h File Reference

Functions

Detailed Description

Function Documentation