Socket

Sockets (TCP, UDP unicast, multicast) More...

Macros
#define	GF_MAX_IP_NAME_LEN   1025
#define	GF_SOCK_TYPE_TCP   0x01
#define	GF_SOCK_TYPE_UDP   0x02

Enumerations
enum	{ GF_SOCK_REUSE_PORT = 1 , GF_SOCK_FORCE_IPV6 = 1<<1 , GF_SOCK_FAKE_BIND = 1<<2 }
enum	GF_SockSelectMode { GF_SK_SELECT_BOTH =0 , GF_SK_SELECT_READ , GF_SK_SELECT_WRITE }

Functions
const char *	gf_errno_str (int errnoval)
	error code description
GF_Socket *	gf_sk_new (u32 SocketType)
	socket constructor
void	gf_sk_del (GF_Socket *sock)
	socket destructor
void	gf_sk_reset (GF_Socket *sock)
	reset internal buffer
GF_Err	gf_sk_set_buffer_size (GF_Socket *sock, Bool send_buffer, u32 new_size)
	socket buffer size control
GF_Err	gf_sk_set_block_mode (GF_Socket *sock, Bool NonBlockingOn)
	blocking mode control
GF_Err	gf_sk_bind (GF_Socket *sock, const char *local_ip, u16 port, const char *peer_name, u16 peer_port, u32 options)
	socket binding
GF_Err	gf_sk_connect (GF_Socket *sock, const char *peer_name, u16 port, const char *local_ip)
	connects a socket
GF_Err	gf_sk_send (GF_Socket *sock, const u8 *buffer, u32 length)
	data emission
GF_Err	gf_sk_send_ex (GF_Socket *sock, const u8 *buffer, u32 length, u32 *written)
	data emission
GF_Err	gf_sk_receive (GF_Socket *sock, u8 *buffer, u32 length, u32 *read)
	data reception
GF_Err	gf_sk_listen (GF_Socket *sock, u32 max_conn)
	socket listening
GF_Err	gf_sk_accept (GF_Socket *sock, GF_Socket **new_conn)
	socket accept
GF_Err	gf_sk_server_mode (GF_Socket *sock, Bool server_on)
	server socket mode
GF_Err	gf_sk_get_host_name (char *buffer)
	get local host name
GF_Err	gf_sk_get_local_ip (GF_Socket *sock, char *buffer)
	get local IP
GF_Err	gf_sk_get_local_info (GF_Socket *sock, u16 *port, u32 *sock_type)
	get local info
GF_Err	gf_sk_get_remote_address (GF_Socket *sock, char *buffer)
	get remote address
GF_Err	gf_sk_set_remote (GF_Socket *sock, char *address, u16 port)
	set remote address
GF_Err	gf_sk_setup_multicast (GF_Socket *sock, const char *multi_ip_add, u16 multi_port, u32 TTL, Bool no_bind, char *local_interface_ip)
	multicast setup
GF_Err	gf_sk_setup_multicast_ex (GF_Socket *sock, const char *multi_ip_add, u16 multi_port, u32 TTL, Bool no_bind, char *local_interface_ip, const char **src_ip_inc, u32 nb_src_ip_inc, const char **src_ip_exc, u32 nb_src_ip_exc)
	source-specific multicast setup
u32	gf_sk_is_multicast_address (const char *multi_ip_add)
	multicast address test
s32	gf_sk_get_handle (GF_Socket *sock)
	gets socket handle
void	gf_sk_set_usec_wait (GF_Socket *sock, u32 usec_wait)
GF_Err	gf_sk_receive_no_select (GF_Socket *sock, u8 *buffer, u32 length, u32 *read)
GF_Err	gf_sk_probe (GF_Socket *sock)
GF_Err	gf_sk_select (GF_Socket *sock, GF_SockSelectMode mode)

Detailed Description

Sockets (TCP, UDP unicast, multicast)

Macro Definition Documentation

GF_MAX_IP_NAME_LEN

#define GF_MAX_IP_NAME_LEN   1025

Buffer size to pass for IP address retrieval

GF_SOCK_TYPE_TCP

#define GF_SOCK_TYPE_TCP   0x01

socket is a TCP socket

GF_SOCK_TYPE_UDP

#define GF_SOCK_TYPE_UDP   0x02

socket is a UDP socket

Enumeration Type Documentation

anonymous enum

anonymous enum

Socket options

Enumerator
GF_SOCK_REUSE_PORT	Reuses port.
GF_SOCK_FORCE_IPV6	Forces IPV6 if available.
GF_SOCK_FAKE_BIND	Does not perfom the actual bind, only keeps address and port.

GF_SockSelectMode

enum GF_SockSelectMode

socket selection mode

Enumerator
GF_SK_SELECT_BOTH	select for either read or write operations
GF_SK_SELECT_READ	select for read operations
GF_SK_SELECT_WRITE	select for write operations

Function Documentation

gf_errno_str()

const char * gf_errno_str

(

int

errnoval

)

error code description

Returns text description of given errno code

Parameters

errnoval

the error value to test

Returns

its description

gf_sk_new()

GF_Socket * gf_sk_new

(

u32

SocketType

)

socket constructor

Constructs a socket object

Parameters

SocketType

the socket type to create, either UDP or TCP

Returns

the socket object or NULL if network initialization failure

gf_sk_del()

void gf_sk_del

(

GF_Socket *

sock

)

socket destructor

Deletes a socket object

Parameters

sock	the socket object

gf_sk_reset()

void gf_sk_reset

(

GF_Socket *

sock

)

reset internal buffer

Forces the internal socket buffer to be reseted (discarded)

Parameters

sock	the socket object

gf_sk_set_buffer_size()

GF_Err gf_sk_set_buffer_size	(	GF_Socket *	sock,
		Bool	send_buffer,
		u32	new_size
	)

socket buffer size control

Sets the size of the internal buffer of the socket. The socket MUST be bound or connected before.

Warning

This operation may fail depending on the provider, hardware...

Parameters

sock	the socket object
send_buffer	if 0, sets the size of the reception buffer, otherwise sets the size of the emission buffer
new_size	new size of the buffer in bytes.

Returns

error if any

gf_sk_set_block_mode()

GF_Err gf_sk_set_block_mode	(	GF_Socket *	sock,
		Bool	NonBlockingOn
	)

blocking mode control

Sets the blocking mode of a socket on or off. A blocking socket will wait for the net operation to be possible while a non-blocking one would return an error. By default, sockets are created in blocking mode

Parameters

sock	the socket object
NonBlockingOn	set to 1 to use non-blocking sockets, 0 otherwise

Returns

error if any

gf_sk_bind()

GF_Err gf_sk_bind	(	GF_Socket *	sock,
		const char *	local_ip,
		u16	port,
		const char *	peer_name,
		u16	peer_port,
		u32	options
	)

socket binding

Binds the given socket to the specified port.

Parameters

local_ip	the local interface IP address if desired. If NULL, the default interface will be used.
sock	the socket object
port	port number to bind this socket to
peer_name	the remote server address, if NULL, will use localhost
peer_port	remote port number to connect the socket to
options	list of option for the bind operation.

Returns

error if any

gf_sk_connect()

GF_Err gf_sk_connect	(	GF_Socket *	sock,
		const char *	peer_name,
		u16	port,
		const char *	local_ip
	)

connects a socket

Connects a socket to a remote peer on a given port

Parameters

sock	the socket object
peer_name	the remote server address (IP or DNS)
port	remote port number to connect the socket to
local_ip	the local (client) address (IP or DNS) if any, NULL otherwise.

Returns

error if any

gf_sk_send()

GF_Err gf_sk_send	(	GF_Socket *	sock,
		const u8 *	buffer,
		u32	length
	)

data emission

Sends a buffer on the socket. The socket must be in a bound or connected mode

Parameters

sock	the socket object
buffer	the data buffer to send
length	the data length to send

Returns

error if any

gf_sk_send_ex()

GF_Err gf_sk_send_ex	(	GF_Socket *	sock,
		const u8 *	buffer,
		u32	length,
		u32 *	written
	)

data emission

Sends a buffer on the socket. The socket must be in a bound or connected mode. This function is usually needed for non-blocking sockets

Parameters

sock	the socket object
buffer	the data buffer to send
length	the data length to send
written	set to number of written bytes - may be NULL

Returns

error if any

gf_sk_receive()

GF_Err gf_sk_receive	(	GF_Socket *	sock,
		u8 *	buffer,
		u32	length,
		u32 *	read
	)

data reception

Fetches data on a socket. The socket must be in a bound or connected state

Parameters

sock	the socket object
buffer	the reception buffer where data is written. Passing NULL will only probe for data in socket (eg only do select() ).
length	the allocated size of the reception buffer
read	the actual number of bytes received

Returns

error if any, GF_IP_NETWORK_EMPTY if nothing to read

gf_sk_listen()

GF_Err gf_sk_listen	(	GF_Socket *	sock,
		u32	max_conn
	)

socket listening

Sets the socket in a listening state. This socket must have been bound to a port before

Parameters

sock	the socket object
max_conn	the maximum number of simultaneous connection this socket will accept

Returns

error if any

gf_sk_accept()

GF_Err gf_sk_accept	(	GF_Socket *	sock,
		GF_Socket **	new_conn
	)

socket accept

Accepts an incoming connection on a listening socket

Parameters

sock	the socket object
new_conn	the resulting connection socket object

Returns

error if any, GF_IP_NETWORK_EMPTY if nothing to read

gf_sk_server_mode()

GF_Err gf_sk_server_mode	(	GF_Socket *	sock,
		Bool	server_on
	)

server socket mode

Disable the Nable algo (e.g. set TCP_NODELAY) and set the KEEPALIVE on

Parameters

sock	the socket object
server_on	sets server mode on or off

Returns

error if any

gf_sk_get_host_name()

GF_Err gf_sk_get_host_name

(

char *

buffer

)

get local host name

Retrieves local host name.

Parameters

buffer

destination buffer for name. Buffer must be GF_MAX_IP_NAME_LEN long

Returns

error if any

gf_sk_get_local_ip()

GF_Err gf_sk_get_local_ip	(	GF_Socket *	sock,
		char *	buffer
	)

get local IP

Gets local IP address of a connected socket, typically used for server after an ACCEPT

Parameters

sock	the socket object
buffer	destination buffer for IP address. Buffer must be GF_MAX_IP_NAME_LEN long

Returns

error if any

gf_sk_get_local_info()

GF_Err gf_sk_get_local_info	(	GF_Socket *	sock,
		u16 *	port,
		u32 *	sock_type
	)

get local info

Gets local socket info of a socket

Parameters

sock	the socket object
port	local port number of the socket
sock_type	socket type (UDP or TCP)

Returns

error if any

gf_sk_get_remote_address()

GF_Err gf_sk_get_remote_address	(	GF_Socket *	sock,
		char *	buffer
	)

get remote address

Gets the remote address of a peer. The socket MUST be connected.

Parameters

sock	the socket object
buffer	destination buffer for IP address. Buffer must be GF_MAX_IP_NAME_LEN long

Returns

error if any

gf_sk_set_remote()

GF_Err gf_sk_set_remote	(	GF_Socket *	sock,
		char *	address,
		u16	port
	)

set remote address

Sets the remote address of a socket. This is used by connectionless sockets using SendTo and ReceiveFrom

Parameters

sock	the socket object
address	the remote peer address
port	the remote peer port

Returns

error if any

gf_sk_setup_multicast()

GF_Err gf_sk_setup_multicast	(	GF_Socket *	sock,
		const char *	multi_ip_add,
		u16	multi_port,
		u32	TTL,
		Bool	no_bind,
		char *	local_interface_ip
	)

multicast setup

Performs multicast setup (BIND and JOIN) for the socket object

Parameters

sock	the socket object
multi_ip_add	the multicast IP address
multi_port	the multicast port number
TTL	the multicast TTL (Time-To-Live)
no_bind	if sets, only join the multicast
local_interface_ip	the local interface IP address if desired. If NULL, the default interface will be used.

Returns

error if any

gf_sk_setup_multicast_ex()

GF_Err gf_sk_setup_multicast_ex	(	GF_Socket *	sock,
		const char *	multi_ip_add,
		u16	multi_port,
		u32	TTL,
		Bool	no_bind,
		char *	local_interface_ip,
		const char **	src_ip_inc,
		u32	nb_src_ip_inc,
		const char **	src_ip_exc,
		u32	nb_src_ip_exc
	)

source-specific multicast setup

Performs multicast setup (BIND and JOIN) for the socket object using allowed and block sources

Parameters

sock	the socket object
multi_ip_add	the multicast IP address
multi_port	the multicast port number
TTL	the multicast TTL (Time-To-Live)
no_bind	if sets, only join the multicast
local_interface_ip	the local interface IP address if desired. If NULL, the default interface will be used.
src_ip_inc	IP of sources to receive from
nb_src_ip_inc	number of sources to receive from
src_ip_exc	IP of sources to exclude
nb_src_ip_exc	number of sources to exclude

Returns

error if any

gf_sk_is_multicast_address()

u32 gf_sk_is_multicast_address

(

const char *

multi_ip_add

)

multicast address test

Tests whether an IP address is a multicast one or not

Parameters

multi_ip_add

the multicast IP address to test

Returns

1 if the address is a multicast one, 0 otherwise

gf_sk_get_handle()

s32 gf_sk_get_handle

(

GF_Socket *

sock

)

gets socket handle

Gets the socket low-level handle as used by OpenSSL.

Parameters

sock	the socket object

Returns

the socket handle

gf_sk_set_usec_wait()

void gf_sk_set_usec_wait	(	GF_Socket *	sock,
		u32	usec_wait
	)

Sets the socket wait time in microseconds. Default wait time is 500 microseconds. Any value >= 1000000 will reset to default.

Parameters

sock	the socket object
usec_wait	wait time in microseconds

gf_sk_receive_no_select()

GF_Err gf_sk_receive_no_select	(	GF_Socket *	sock,
		u8 *	buffer,
		u32	length,
		u32 *	read
	)

Fetches data on a socket without performing any select (wait), to be used with socket group on sockets that are set in the selected socket group

Parameters

sock	the socket object
buffer	the reception buffer where data is written
length	the allocated size of the reception buffer
read	the actual number of bytes received

Returns

error if any, GF_IP_NETWORK_EMPTY if nothing to read

gf_sk_probe()

GF_Err gf_sk_probe

(

GF_Socket *

sock

)

Checks if connection has been closed by remote peer

Parameters

sock	the socket object

Returns

error if any (GF_IP_CONNECTION_CLOSED if connection is closed)

gf_sk_select()

GF_Err gf_sk_select	(	GF_Socket *	sock,
		GF_SockSelectMode	mode
	)

Checks if socket can is ready for read or write

Parameters

sock	the socket object
mode	the operation mode desired

Returns

GF_OK if ready, GF_IP_NETWORK_EMPTY if not ready, otherwise error if any (GF_IP_CONNECTION_CLOSED if connection is closed)