Socket Abstraction
[Input/Output]

Detailed Description

The PJLIB socket abstraction layer is a thin and very portable abstraction for socket API. It provides API similar to BSD socket API. The abstraction is needed because BSD socket API is not always available on all platforms, therefore it wouldn't be possible to create a trully portable network programs unless we provide such abstraction.

Applications can use this API directly in their application, just as they would when using traditional BSD socket API, provided they call pj_init() first.

Examples

For some examples on how to use the socket API, please see:

Define Documentation

#define pj_AF_INET ( ) PJ_AF_INET

Get PJ_AF_INET value.

#define pj_AF_INET6 ( ) PJ_AF_INET6

Get PJ_AF_INET6 value.

#define pj_AF_IRDA ( ) PJ_AF_IRDA

Get PJ_AF_IRDA value.

#define PJ_AF_LOCAL PJ_AF_UNIX;

POSIX name for AF_UNIX

#define pj_AF_PACKET ( ) PJ_AF_PACKET

Get PJ_AF_PACKET value.

#define pj_AF_UNIX ( ) PJ_AF_UNIX

Get PJ_AF_UNIX value.

#define pj_AF_UNSPEC ( ) PJ_AF_UNSPEC

Get PJ_AF_UNSPEC value

#define PJ_IN6ADDR_ANY_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } } }

Initializer value for pj_in6_addr.

#define PJ_IN6ADDR_LOOPBACK_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } }

Initializer value for pj_in6_addr.

#define PJ_INADDR_ANY ((pj_uint32_t)0)

Address to accept any incoming messages.

#define PJ_INADDR_BROADCAST ((pj_uint32_t)0xffffffff)

Address to send to all hosts.

#define PJ_INADDR_NONE ((pj_uint32_t)0xffffffff)

Address indicating an error return

#define PJ_INET6_ADDRSTRLEN 46

Maximum length of text representation of an IPv6 address.

#define PJ_INET_ADDRSTRLEN 16

Maximum length of text representation of an IPv4 address.

#define PJ_INVALID_SOCKET (-1)

Constant for invalid socket returned by pj_sock_socket() and pj_sock_accept().

#define pj_IP_TOS ( ) PJ_IP_TOS

Get PJ_IP_TOS constant

#define pj_IPTOS_LOWDELAY ( ) PJ_IP_TOS_LOWDELAY

Get PJ_IPTOS_LOWDELAY constant

#define pj_IPTOS_MINCOST ( ) PJ_IP_TOS_MINCOST

Get PJ_IPTOS_MINCOST constant

#define pj_IPTOS_RELIABILITY ( ) PJ_IP_TOS_RELIABILITY

Get PJ_IPTOS_RELIABILITY constant

#define pj_IPTOS_THROUGHPUT ( ) PJ_IP_TOS_THROUGHPUT

Get PJ_IPTOS_THROUGHPUT constant

#define pj_MSG_DONTROUTE ( ) PJ_MSG_DONTROUTE

Get PJ_MSG_DONTROUTE constant

#define pj_MSG_OOB ( ) PJ_MSG_OOB

Get PJ_MSG_OOB constant

#define pj_MSG_PEEK ( ) PJ_MSG_PEEK

Get PJ_MSG_PEEK constant

#define pj_SO_RCVBUF ( ) PJ_SO_RCVBUF

Get PJ_SO_RCVBUF constant

#define pj_SO_SNDBUF ( ) PJ_SO_SNDBUF

Get PJ_SO_SNDBUF constant

#define pj_SO_TYPE ( ) PJ_SO_TYPE

Get PJ_SO_TYPE constant

#define pj_SOCK_DGRAM ( ) PJ_SOCK_DGRAM

Get PJ_SOCK_DGRAM constant

#define pj_SOCK_RAW ( ) PJ_SOCK_RAW

Get PJ_SOCK_RAW constant

#define pj_SOCK_RDM ( ) PJ_SOCK_RDM

Get PJ_SOCK_RDM constant

#define pj_SOCK_STREAM ( ) PJ_SOCK_STREAM

Get PJ_SOCK_STREAM constant

#define pj_SOL_IP ( ) PJ_SOL_IP

Get PJ_SOL_IP constant

#define pj_SOL_IPV6 ( ) PJ_SOL_IPV6

Get PJ_SOL_IPV6 constant

#define pj_SOL_SOCKET ( ) PJ_SOL_SOCKET

Get PJ_SOL_SOCKET constant

#define pj_SOL_TCP ( ) PJ_SOL_TCP

Get PJ_SOL_TCP constant

#define pj_SOL_UDP ( ) PJ_SOL_UDP

Get PJ_SOL_UDP constant

#define PJ_SOMAXCONN 5

Maximum length specifiable by pj_sock_listen(). If the build system doesn't override this value, then the lowest denominator (five, in Win32 systems) will be used.

Enumeration Type Documentation

enum pj_socket_sd_type

Flag to be specified in pj_sock_shutdown().

Enumerator:

PJ_SD_RECEIVE	No more receive.
PJ_SHUT_RD	Alias for SD_RECEIVE.
PJ_SD_SEND	No more sending.
PJ_SHUT_WR	Alias for SD_SEND.
PJ_SD_BOTH	No more send and receive.
PJ_SHUT_RDWR	Alias for SD_BOTH.

Function Documentation

pj_in_addr pj_gethostaddr ( void )

Get host's IP address, which the the first IP address that is resolved from the hostname.

Returns:: The host's IP address, PJ_INADDR_NONE if the host IP address can not be identified.

const pj_str_t* pj_gethostname ( void )

Get system's host name.

Returns:: The hostname, or empty string if the hostname can not be identified.

pj_uint32_t pj_htonl ( pj_uint32_t hostlong )

Convert 32-bit value from host byte order to network byte order.

Parameters:

hostlong

32-bit host value.

Returns:: 32-bit network value.

pj_uint16_t pj_htons ( pj_uint16_t hostshort )

Convert 16-bit value from host byte order to network byte order.

Parameters:

hostshort

16-bit host value.

Returns:: 16-bit network value.

pj_in_addr pj_inet_addr ( const pj_str_t * cp )

Convert address string with numbers and dots to binary IP address.

Parameters:

The IP address in numbers and dots notation.

Returns:: If success, the IP address is returned in network byte order. If failed, PJ_INADDR_NONE will be returned.

Remarks:: This is an obsolete interface to pj_inet_aton(); it is obsolete because -1 is a valid address (255.255.255.255), and pj_inet_aton() provides a cleaner way to indicate error return.

pj_in_addr pj_inet_addr2 ( const char * cp )

Convert address string with numbers and dots to binary IP address.

Parameters:

The IP address in numbers and dots notation.

Returns:: If success, the IP address is returned in network byte order. If failed, PJ_INADDR_NONE will be returned.

Remarks:: This is an obsolete interface to pj_inet_aton(); it is obsolete because -1 is a valid address (255.255.255.255), and pj_inet_aton() provides a cleaner way to indicate error return.

int pj_inet_aton	(	const pj_str_t *	cp,
		struct pj_in_addr *	inp
	)

This function converts the Internet host address cp from the standard numbers-and-dots notation into binary data and stores it in the structure that inp points to.

Parameters:

	cp	IP address in standard numbers-and-dots notation.
	inp	Structure that holds the output of the conversion.

Returns:: nonzero if the address is valid, zero if not.

char* pj_inet_ntoa ( pj_in_addr inaddr )

Convert an Internet host address given in network byte order to string in standard numbers and dots notation.

Parameters:

inaddr

The host address.

Returns:: The string address.

pj_status_t pj_inet_ntop	(	int	af,
		const void *	src,
		char *	dst,
		int	size
	)

This function converts a numeric address into a text string suitable for presentation. It supports both IPv4 and IPv6 address conversion.

See also:: pj_sockaddr_print()

Parameters:

	af	Specify the family of the address. This can be PJ_AF_INET or PJ_AF_INET6.
	src	Points to a buffer holding an IPv4 address if the af argument is PJ_AF_INET, or an IPv6 address if the af argument is PJ_AF_INET6; the address must be in network byte order.
	dst	Points to a buffer where the function stores the resulting text string; it shall not be NULL.
	size	Specifies the size of this buffer, which shall be large enough to hold the text string (PJ_INET_ADDRSTRLEN characters for IPv4, PJ_INET6_ADDRSTRLEN characters for IPv6).

Returns:: PJ_SUCCESS if conversion was successful.

char* pj_inet_ntop2	(	int	af,
		const void *	src,
		char *	dst,
		int	size
	)

Converts numeric address into its text string representation.

See also:: pj_sockaddr_print()

Parameters:

	af	Specify the family of the address. This can be PJ_AF_INET or PJ_AF_INET6.
	src	Points to a buffer holding an IPv4 address if the af argument is PJ_AF_INET, or an IPv6 address if the af argument is PJ_AF_INET6; the address must be in network byte order.
	dst	Points to a buffer where the function stores the resulting text string; it shall not be NULL.
	size	Specifies the size of this buffer, which shall be large enough to hold the text string (PJ_INET_ADDRSTRLEN characters for IPv4, PJ_INET6_ADDRSTRLEN characters for IPv6).

Returns:: The address string or NULL if failed.

pj_status_t pj_inet_pton	(	int	af,
		const pj_str_t *	src,
		void *	dst
	)

This function converts an address in its standard text presentation form into its numeric binary form. It supports both IPv4 and IPv6 address conversion.

Parameters:

	af	Specify the family of the address. The PJ_AF_INET and PJ_AF_INET6 address families shall be supported.
	src	Points to the string being passed in.
	dst	Points to a buffer into which the function stores the numeric address; this shall be large enough to hold the numeric address (32 bits for PJ_AF_INET, 128 bits for PJ_AF_INET6).

Returns:: PJ_SUCCESS if conversion was successful.

pj_uint32_t pj_ntohl ( pj_uint32_t netlong )

Convert 32-bit value from network byte order to host byte order.

Parameters:

netlong

32-bit network value.

Returns:: 32-bit host value.

pj_uint16_t pj_ntohs ( pj_uint16_t netshort )

Convert 16-bit value from network byte order to host byte order.

Parameters:

netshort

16-bit network value.

Returns:: 16-bit host value.

pj_status_t pj_sock_accept	(	pj_sock_t	serverfd,
		pj_sock_t *	newsock,
		pj_sockaddr_t *	addr,
		int *	addrlen
	)

Accept new connection on the specified connection oriented server socket.

Parameters:

	serverfd	The server socket.
	newsock	New socket on success, of PJ_INVALID_SOCKET if failed.
	addr	A pointer to sockaddr type. If the argument is not NULL, it will be filled by the address of connecting entity.
	addrlen	Initially specifies the length of the address, and upon return will be filled with the exact address length.

Returns:: Zero on success, or the error number.

pj_status_t pj_sock_bind	(	pj_sock_t	sockfd,
		const pj_sockaddr_t *	my_addr,
		int	addrlen
	)

This function gives the socket sockfd the local address my_addr. my_addr is addrlen bytes long. Traditionally, this is called assigning a name to a socket. When a socket is created with pj_sock_socket(), it exists in a name space (address family) but has no name assigned.

Parameters:

	sockfd	The socket desriptor.
	my_addr	The local address to bind the socket to.
	addrlen	The length of the address.

Returns:: Zero on success.

pj_status_t pj_sock_bind_in	(	pj_sock_t	sockfd,
		pj_uint32_t	addr,
		pj_uint16_t	port
	)

Bind the IP socket sockfd to the given address and port.

Parameters:

	sockfd	The socket descriptor.
	addr	Local address to bind the socket to, in host byte order.
	port	The local port to bind the socket to, in host byte order.

Returns:: Zero on success.

pj_status_t pj_sock_close ( pj_sock_t sockfd )

Close the socket descriptor.

Parameters:

sockfd

The socket descriptor.

Returns:: Zero on success.

pj_status_t pj_sock_connect	(	pj_sock_t	sockfd,
		const pj_sockaddr_t *	serv_addr,
		int	addrlen
	)

The file descriptor sockfd must refer to a socket. If the socket is of type PJ_SOCK_DGRAM then the serv_addr address is the address to which datagrams are sent by default, and the only address from which datagrams are received. If the socket is of type PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET, this call attempts to make a connection to another socket. The other socket is specified by serv_addr, which is an address (of length addrlen) in the communications space of the socket. Each communications space interprets the serv_addr parameter in its own way.

Parameters:

	sockfd	The socket descriptor.
	serv_addr	Server address to connect to.
	addrlen	The length of server address.

Returns:: Zero on success.

pj_status_t pj_sock_getpeername	(	pj_sock_t	sockfd,
		pj_sockaddr_t *	addr,
		int *	namelen
	)

Return the address of peer which is connected to socket sockfd.

Parameters:

	sockfd	The socket descriptor.
	addr	Pointer to sockaddr structure to which the address will be returned.
	namelen	Initially the length of the addr. Upon return the value will be set to the actual length of the address.

Returns:: Zero on success.

pj_status_t pj_sock_getsockname	(	pj_sock_t	sockfd,
		pj_sockaddr_t *	addr,
		int *	namelen
	)

Return the current name of the specified socket.

Parameters:

	sockfd	The socket descriptor.
	addr	Pointer to sockaddr structure to which the address will be returned.
	namelen	Initially the length of the addr. Upon return the value will be set to the actual length of the address.

Returns:: Zero on success.

pj_status_t pj_sock_getsockopt	(	pj_sock_t	sockfd,
		pj_uint16_t	level,
		pj_uint16_t	optname,
		void *	optval,
		int *	optlen
	)

Get socket option associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level.

Parameters:

	sockfd	The socket descriptor.
	level	The level which to get the option from.
	optname	The option name.
	optval	Identifies the buffer which the value will be returned.
	optlen	Initially contains the length of the buffer, upon return will be set to the actual size of the value.

Returns:: Zero on success.

pj_status_t pj_sock_listen	(	pj_sock_t	sockfd,
		int	backlog
	)

Listen for incoming connection. This function only applies to connection oriented sockets (such as PJ_SOCK_STREAM or PJ_SOCK_SEQPACKET), and it indicates the willingness to accept incoming connections.

Parameters:

	sockfd	The socket descriptor.
	backlog	Defines the maximum length the queue of pending connections may grow to.

Returns:: Zero on success.

pj_status_t pj_sock_recv	(	pj_sock_t	sockfd,
		void *	buf,
		pj_ssize_t *	len,
		unsigned	flags
	)

Receives data stream or message coming to the specified socket.

Parameters:

	sockfd	The socket descriptor.
	buf	The buffer to receive the data or message.
	len	On input, the length of the buffer. On return, contains the length of data received.
	flags	Flags (such as pj_MSG_PEEK()).

Returns:: PJ_SUCCESS or the error code.

pj_status_t pj_sock_recvfrom	(	pj_sock_t	sockfd,
		void *	buf,
		pj_ssize_t *	len,
		unsigned	flags,
		pj_sockaddr_t *	from,
		int *	fromlen
	)

Receives data stream or message coming to the specified socket.

Parameters:

	sockfd	The socket descriptor.
	buf	The buffer to receive the data or message.
	len	On input, the length of the buffer. On return, contains the length of data received.
	flags	Flags (such as pj_MSG_PEEK()).
	from	If not NULL, it will be filled with the source address of the connection.
	fromlen	Initially contains the length of from address, and upon return will be filled with the actual length of the address.

Returns:: PJ_SUCCESS or the error code.

pj_status_t pj_sock_send	(	pj_sock_t	sockfd,
		const void *	buf,
		pj_ssize_t *	len,
		unsigned	flags
	)

Transmit data to the socket.

Parameters:

	sockfd	Socket descriptor.
	buf	Buffer containing data to be sent.
	len	On input, the length of the data in the buffer. Upon return, it will be filled with the length of data sent.
	flags	Flags (such as pj_MSG_DONTROUTE()).

Returns:: PJ_SUCCESS or the status code.

pj_status_t pj_sock_sendto	(	pj_sock_t	sockfd,
		const void *	buf,
		pj_ssize_t *	len,
		unsigned	flags,
		const pj_sockaddr_t *	to,
		int	tolen
	)

Transmit data to the socket to the specified address.

Parameters:

	sockfd	Socket descriptor.
	buf	Buffer containing data to be sent.
	len	On input, the length of the data in the buffer. Upon return, it will be filled with the length of data sent.
	flags	Flags (such as pj_MSG_DONTROUTE()).
	to	The address to send.
	tolen	The length of the address in bytes.

Returns:: PJ_SUCCESS or the status code.

pj_status_t pj_sock_setsockopt	(	pj_sock_t	sockfd,
		pj_uint16_t	level,
		pj_uint16_t	optname,
		const void *	optval,
		int	optlen
	)

Manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level.

Parameters:

	sockfd	The socket descriptor.
	level	The level which to get the option from.
	optname	The option name.
	optval	Identifies the buffer which contain the value.
	optlen	The length of the value.

Returns:: PJ_SUCCESS or the status code.

pj_status_t pj_sock_shutdown	(	pj_sock_t	sockfd,
		int	how
	)

The shutdown call causes all or part of a full-duplex connection on the socket associated with sockfd to be shut down.

Parameters:

	sockfd	The socket descriptor.
	how	If how is PJ_SHUT_RD, further receptions will be disallowed. If how is PJ_SHUT_WR, further transmissions will be disallowed. If how is PJ_SHUT_RDWR, further receptions andtransmissions will be disallowed.

Returns:: Zero on success.

pj_status_t pj_sock_socket	(	int	family,
		int	type,
		int	protocol,
		pj_sock_t *	sock
	)

Socket Abstraction [Input/Output]

Detailed Description

Examples

Data Structures

Defines

Enumerations

Functions

Variables

Define Documentation

Enumeration Type Documentation

Function Documentation

Socket Abstraction
[Input/Output]