libgpac
Documentation of the core library of GPAC

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

+ Collaboration diagram for Socket:

Macros

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

Typedefs

typedef struct __tag_socket GF_Socket
 abstracted socket object More...
 
typedef struct __tag_sock_group GF_SockGroup
 abstracted socket group object More...
 

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

GF_Socketgf_sk_new (u32 SocketType)
 socket constructor More...
 
GF_Socketgf_sk_new_ex (u32 SocketType, const char *netcap_id)
 socket constructor More...
 
void gf_sk_del (GF_Socket *sock)
 socket destructor More...
 
void gf_sk_reset (GF_Socket *sock)
 reset internal buffer More...
 
GF_Err gf_sk_set_buffer_size (GF_Socket *sock, Bool send_buffer, u32 new_size)
 socket buffer size control More...
 
GF_Err gf_sk_set_block_mode (GF_Socket *sock, Bool NonBlockingOn)
 blocking mode control More...
 
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 More...
 
GF_Err gf_sk_connect (GF_Socket *sock, const char *peer_name, u16 port, const char *local_ip)
 connects a socket More...
 
GF_Err gf_sk_send (GF_Socket *sock, const u8 *buffer, u32 length)
 data emission More...
 
GF_Err gf_sk_send_ex (GF_Socket *sock, const u8 *buffer, u32 length, u32 *written)
 data emission More...
 
GF_Err gf_sk_receive (GF_Socket *sock, u8 *buffer, u32 length, u32 *read)
 data reception More...
 
GF_Err gf_sk_listen (GF_Socket *sock, u32 max_conn)
 socket listening More...
 
GF_Err gf_sk_accept (GF_Socket *sock, GF_Socket **new_conn)
 socket accept More...
 
GF_Err gf_sk_server_mode (GF_Socket *sock, Bool server_on)
 server socket mode More...
 
GF_Err gf_sk_get_host_name (char *buffer)
 get local host name More...
 
GF_Err gf_sk_get_local_ip (GF_Socket *sock, char *buffer)
 get local IP More...
 
GF_Err gf_sk_get_local_info (GF_Socket *sock, u16 *port, u32 *sock_type)
 get local info More...
 
GF_Err gf_sk_get_remote_address (GF_Socket *sock, char *buffer)
 get remote address More...
 
GF_Err gf_sk_set_remote (GF_Socket *sock, char *address, u16 port)
 set remote address More...
 
GF_Err gf_sk_setup_multicast (GF_Socket *sock, const char *multi_ip_add, u16 multi_port, u32 TTL, Bool no_bind, const char *ifce_ip_or_name)
 multicast setup More...
 
GF_Err gf_sk_setup_multicast_ex (GF_Socket *sock, const char *multi_ip_add, u16 multi_port, u32 TTL, Bool no_bind, const char *ifce_ip_or_name, const char **src_ip_inc, u32 nb_src_ip_inc, const char **src_ip_exc, u32 nb_src_ip_exc)
 source-specific multicast setup More...
 
u32 gf_sk_is_multicast_address (const char *multi_ip_add)
 multicast address test More...
 
s32 gf_sk_get_handle (GF_Socket *sock)
 gets socket handle More...
 
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

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

Typedef Documentation

◆ GF_Socket

typedef struct __tag_socket GF_Socket

The abstracted socket object allows you to build client and server applications very simply with support for unicast and multicast Available tools are socket and socket groups and some helper functions for network time

◆ GF_SockGroup

typedef struct __tag_sock_group GF_SockGroup

The abstracted socket group object allows querying multiple sockets in a group

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

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_sk_new()

GF_Socket* gf_sk_new ( u32  SocketType)

Constructs a socket object

Parameters
SocketTypethe socket type to create, either UDP or TCP
Returns
the socket object or NULL if network initialization failure

◆ gf_sk_new_ex()

GF_Socket* gf_sk_new_ex ( u32  SocketType,
const char *  netcap_id 
)

Constructs a socket object with a specific netcap configuration ID

Parameters
SocketTypethe socket type to create, either UDP or TCP
netcap_idID of netcap configuration to use, may be null (see gpac -h netcap)
Returns
the socket object or NULL if network initialization failure

◆ gf_sk_del()

void gf_sk_del ( GF_Socket sock)

Deletes a socket object

Parameters
sockthe socket object

◆ gf_sk_reset()

void gf_sk_reset ( GF_Socket sock)

Forces the internal socket buffer to be reseted (discarded)

Parameters
sockthe socket object

◆ gf_sk_set_buffer_size()

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

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
sockthe socket object
send_bufferif 0, sets the size of the reception buffer, otherwise sets the size of the emission buffer
new_sizenew 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 
)

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
sockthe socket object
NonBlockingOnset 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 
)

Binds the given socket to the specified port.

Parameters
local_ipthe local interface IP address if desired. If NULL, the default interface will be used.
sockthe socket object
portport number to bind this socket to
peer_namethe remote server address, if NULL, will use localhost
peer_portremote port number to connect the socket to
optionslist 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 to a remote peer on a given port

Parameters
sockthe socket object
peer_namethe remote server address (IP or DNS)
portremote port number to connect the socket to
local_ipthe 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 
)

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

Parameters
sockthe socket object
bufferthe data buffer to send
lengththe 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 
)

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
sockthe socket object
bufferthe data buffer to send
lengththe data length to send
writtenset 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 
)

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

Parameters
sockthe socket object
bufferthe reception buffer where data is written. Passing NULL will only probe for data in socket (eg only do select() ).
lengththe allocated size of the reception buffer
readthe 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 
)

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

Parameters
sockthe socket object
max_connthe 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 
)

Accepts an incoming connection on a listening socket

Parameters
sockthe socket object
new_connthe 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 
)

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

Parameters
sockthe socket object
server_onsets server mode on or off
Returns
error if any

◆ gf_sk_get_host_name()

GF_Err gf_sk_get_host_name ( char *  buffer)

Retrieves local host name.

Parameters
bufferdestination 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 
)

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

Parameters
sockthe socket object
bufferdestination 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 
)

Gets local socket info of a socket

Parameters
sockthe socket object
portlocal port number of the socket
sock_typesocket 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 
)

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

Parameters
sockthe socket object
bufferdestination 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 
)

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

Parameters
sockthe socket object
addressthe remote peer address
portthe 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,
const char *  ifce_ip_or_name 
)

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

Parameters
sockthe socket object
multi_ip_addthe multicast IP address
multi_portthe multicast port number
TTLthe multicast TTL (Time-To-Live)
no_bindif sets, only join the multicast
ifce_ip_or_namethe local interface IP address or name 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,
const char *  ifce_ip_or_name,
const char **  src_ip_inc,
u32  nb_src_ip_inc,
const char **  src_ip_exc,
u32  nb_src_ip_exc 
)

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

Parameters
sockthe socket object
multi_ip_addthe multicast IP address
multi_portthe multicast port number
TTLthe multicast TTL (Time-To-Live)
no_bindif sets, only join the multicast
ifce_ip_or_namethe local interface IP address or name if desired. If NULL, the default interface will be used.
src_ip_incIP of sources to receive from
nb_src_ip_incnumber of sources to receive from
src_ip_excIP of sources to exclude
nb_src_ip_excnumber of sources to exclude
Returns
error if any

◆ gf_sk_is_multicast_address()

u32 gf_sk_is_multicast_address ( const char *  multi_ip_add)

Tests whether an IP address is a multicast one or not

Parameters
multi_ip_addthe 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 the socket low-level handle as used by OpenSSL.

Parameters
sockthe 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
sockthe socket object
usec_waitwait 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
sockthe socket object
bufferthe reception buffer where data is written
lengththe allocated size of the reception buffer
readthe 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
sockthe 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
sockthe socket object
modethe 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)