Internet sockets

Collaboration diagram for Internet sockets:

Macros
#define	net_errno   errno
#define	net_Close(fd)   ((void)vlc_close(fd))
#define	net_Connect(a, b, c, d, e)   net_Connect(VLC_OBJECT(a), b, c, d, e)
#define	net_ListenTCP(a, b, c)
#define	net_Accept(a, b)    net_Accept(VLC_OBJECT(a), b)
#define	net_ConnectDgram(a, b, c, d, e)    net_ConnectDgram(VLC_OBJECT(a), b, c, d, e)
#define	net_OpenDgram(a, b, c, d, e, g)    net_OpenDgram(VLC_OBJECT(a), b, c, d, e, g)
#define	net_Read(a, b, c, d)   net_Read(VLC_OBJECT(a),b,c,d)
#define	net_Write(a, b, c, d)   net_Write(VLC_OBJECT(a),b,c,d)

Functions
int	vlc_socket (int pf, int type, int proto, bool nonblock)
	Creates a socket file descriptor.
int	vlc_socketpair (int pf, int type, int proto, int fds[2], bool nonblock)
	Creates a pair of socket file descriptors.
int	vlc_accept (int lfd, struct sockaddr *addr, socklen_t *alen, bool nonblock)
	Accepts an inbound connection request on a listening socket.
ssize_t	vlc_send (int fd, const void *buf, size_t buflen, int flags)
	Sends data.
ssize_t	vlc_sendto (int fd, const void *buf, size_t buflen, int flags, const struct sockaddr *dst, socklen_t dstlen)
	Sends data to a peer.
ssize_t	vlc_sendmsg (int fd, const struct msghdr *msg, int flags)
	Sends a socket message.
int	net_Socket (vlc_object_t *obj, int family, int socktype, int proto)
int	net_Connect (vlc_object_t *p_this, const char *psz_host, int i_port, int socktype, int protocol)
int *	net_Listen (vlc_object_t *p_this, const char *psz_host, unsigned i_port, int socktype, int protocol)
int	net_Accept (vlc_object_t *obj, int *fds)
	Accepts an new connection on a set of listening sockets.
int	net_ConnectDgram (vlc_object_t *p_this, const char *psz_host, unsigned i_port, int hlim, int proto)
static int	net_ConnectUDP (vlc_object_t *obj, const char *host, unsigned port, int hlim)
int	net_OpenDgram (vlc_object_t *p_this, const char *psz_bind, unsigned i_bind, const char *psz_server, unsigned i_server, int proto)
static int	net_ListenUDP1 (vlc_object_t *obj, const char *host, unsigned port)
void	net_ListenClose (int *fd)
int	net_SetCSCov (int fd, int sendcov, int recvcov)
	net_SetCSCov: Sets the send and receive checksum coverage of a socket:
ssize_t	net_Read (vlc_object_t *p_this, int fd, void *p_data, size_t i_data)
	Reads data from a socket.
ssize_t	net_Write (vlc_object_t *p_this, int fd, const void *p_data, size_t i_data)
	Writes data to a socket.
int	vlc_close (int)
	Closes a file descriptor.

Detailed Description

Macro Definition Documentation

net_Accept

#define net_Accept	(		a,
			b
	)		net_Accept(VLC_OBJECT(a), b)

net_Close

#define net_Close

(

fd

)

((void)vlc_close(fd))

net_Connect

#define net_Connect	(		a,
			b,
			c,
			d,
			e
	)		net_Connect(VLC_OBJECT(a), b, c, d, e)

net_ConnectDgram

#define net_ConnectDgram	(		a,
			b,
			c,
			d,
			e
	)		net_ConnectDgram(VLC_OBJECT(a), b, c, d, e)

net_errno

#define net_errno   errno

net_ListenTCP

#define net_ListenTCP	(		a,
			b,
			c
	)

Value:

                                          net_Listen(VLC_OBJECT(a), b, c, \
                                          SOCK_STREAM, IPPROTO_TCP)

net_OpenDgram

#define net_OpenDgram	(		a,
			b,
			c,
			d,
			e,
			g
	)		net_OpenDgram(VLC_OBJECT(a), b, c, d, e, g)

net_Read

#define net_Read	(		a,
			b,
			c,
			d
	)		net_Read(VLC_OBJECT(a),b,c,d)

net_Write

#define net_Write	(		a,
			b,
			c,
			d
	)		net_Write(VLC_OBJECT(a),b,c,d)

Function Documentation

net_Accept()

int net_Accept	(	vlc_object_t *	obj,
		int *	fds
	)

Accepts an new connection on a set of listening sockets.

If there are no pending connections, this function will wait.

Note

If the thread needs to handle events other than incoming connections, you need to use poll() and net_AcceptSingle() instead.

Deprecated:

This function exists for backward compatibility. Use vlc_accept() or vlc_accept_i11e() in new code.

Parameters

obj	VLC object for logging and object kill signal
fds	listening socket set

Returns

-1 on error (may be transient error due to network issues), a new socket descriptor on success.

References pollfd::events, pollfd::fd, msg_Dbg, msg_Err, net_errno, poll(), POLLIN, pollfd::revents, vlc_accept(), vlc_assert_unreachable, and vlc_strerror_c().

net_Connect()

int net_Connect	(	vlc_object_t *	p_this,
		const char *	psz_host,
		int	i_port,
		int	socktype,
		int	protocol
	)

References AI_IDN, AI_NUMERICSERV, pollfd::events, pollfd::fd, MS_FROM_VLC_TICK, msg_Dbg, msg_Err, msg_Warn, net_Close, net_errno, net_Socket(), POLLOUT, var_InheritInteger(), vlc_getaddrinfo_i11e(), vlc_killed(), vlc_poll_i11e(), vlc_strerror_c(), VLC_TICK_FROM_MS, VLC_TICK_INVALID, and vlc_tick_now().

net_ConnectDgram()

int net_ConnectDgram	(	vlc_object_t *	p_this,
		const char *	psz_host,
		unsigned	i_port,
		int	hlim,
		int	proto
	)

References AI_IDN, AI_NUMERICSERV, i_port, msg_Dbg, msg_Err, msg_Warn, net_Close, net_SetDSCP(), net_SetMcastHopLimit(), net_SetMcastOut(), net_Socket(), var_InheritInteger(), var_InheritString(), vlc_getaddrinfo(), and vlc_strerror_c().

net_ConnectUDP()

static int net_ConnectUDP ( vlc_object_t *  obj, const char *  host, unsigned  port, int  hlim  )

inlinestatic

References net_ConnectDgram.

Referenced by AddressCreate().

net_Listen()

int * net_Listen	(	vlc_object_t *	p_this,
		const char *	psz_host,
		unsigned	i_port,
		int	socktype,
		int	protocol
	)

References AI_IDN, AI_NUMERICSERV, i_port, msg_Dbg, msg_Err, net_Close, net_errno, net_Socket(), rootwrap_bind(), vlc_getaddrinfo(), and vlc_strerror_c().

net_ListenClose()

void net_ListenClose

(

int *

fd

)

References net_Close, and p.

Referenced by httpd_HostCreate(), and httpd_HostDelete().

net_ListenUDP1()

static int net_ListenUDP1 ( vlc_object_t *  obj, const char *  host, unsigned  port  )

inlinestatic

References net_OpenDgram.

net_OpenDgram()

int net_OpenDgram	(	vlc_object_t *	p_this,
		const char *	psz_bind,
		unsigned	i_bind,
		const char *	psz_server,
		unsigned	i_server,
		int	proto
	)

References AI_IDN, AI_NUMERICSERV, msg_Dbg, msg_Err, net_Close, net_errno, net_ListenSingle(), net_SetupDgramSocket(), net_SockAddrIsMulticast(), net_Socket(), net_SourceSubscribe(), vlc_getaddrinfo(), and vlc_strerror_c().

net_Read()

ssize_t net_Read	(	vlc_object_t *	p_this,
		int	fd,
		void *	p_data,
		size_t	i_data
	)

Reads data from a socket.

This blocks until all requested data is received or the end of the stream is reached.

This function is a cancellation point.

Returns

-1 on error, or the number of bytes of read.

net_SetCSCov()

int net_SetCSCov	(	int	fd,
		int	sendcov,
		int	recvcov
	)

net_SetCSCov: Sets the send and receive checksum coverage of a socket:

Parameters

fd	socket
sendcov	payload coverage of sent packets (bytes), -1 for full
recvcov	minimum payload coverage of received packets, -1 for full

References SOL_DCCP, SOL_UDPLITE, VLC_EGENERIC, VLC_SUCCESS, and VLC_UNUSED.

Referenced by OpenURL().

net_Socket()

int net_Socket	(	vlc_object_t *	obj,
		int	family,
		int	socktype,
		int	proto
	)

References IPPROTO_IPV6, msg_Err, net_errno, SOL_DCCP, var_InheritString(), vlc_socket(), and vlc_strerror_c().

Referenced by net_Connect(), net_ConnectDgram(), net_Listen(), net_ListenSingle(), and net_OpenDgram().

net_Write()

ssize_t net_Write	(	vlc_object_t *	p_this,
		int	fd,
		const void *	p_data,
		size_t	i_data
	)

Writes data to a socket.

This blocks until all data is written or an error occurs.

This function is a cancellation point.

Returns

the total number of bytes written, or -1 if an error occurs before any data is written.

References pollfd::fd, msg_Err, vlc_killed(), vlc_send_i11e(), vlc_strerror_c(), and vlc_testcancel().

vlc_accept()

int vlc_accept	(	int	lfd,
		struct sockaddr *	addr,
		socklen_t *	alen,
		bool	nonblock
	)

Accepts an inbound connection request on a listening socket.

This function creates a connected socket from a listening socket, much like the standard accept() function. However, the new file descriptor has the close-on-exec flag set atomically. See also vlc_socket().

Parameters

lfd	listening socket file descriptor
addr	pointer to the peer address or NULL [OUT]
alen	pointer to the length of the peer address or NULL [OUT]
nonblock	whether to put the new socket in non-blocking mode

Returns

a new file descriptor or -1 on error

References vlc_socket_setup().

Referenced by httpdLoop(), net_Accept(), and vlc_accept_i11e().

vlc_close()

int vlc_close

(

int

fd

)

Closes a file descriptor.

This closes a file descriptor. If this is a last file descriptor for the underlying open file, the file is closed too; the exact semantics depend on the type of file.

Note

The file descriptor is always closed when the function returns, even if the function returns an error. The sole exception is if the file descriptor was not currently valid, and thus cannot be closed (errno will then be set to EBADF).

Parameters

fd	file descriptor

Returns

Normally, zero is returned. If an I/O error is detected before or while closing, the function may return -1. Such an error is unrecoverable since the descriptor is closed.

A nul return value does not necessarily imply that all pending I/O succeeded, since I/O might still occur asynchronously afterwards.

References unlikely.

Referenced by config_SaveConfigFile(), httpdLoop(), picture_Allocate(), picture_Deallocate(), TsStorageNew(), vlc_datagram_Close(), vlc_fopen(), vlc_frame_FilePath(), vlc_getProxyUrl(), vlc_poll_i11e_cleanup(), vlc_poll_i11e_inner(), vlc_rand_init(), and vlc_spawn_inner().

vlc_send()

ssize_t vlc_send	(	int	fd,
		const void *	buf,
		size_t	buflen,
		int	flags
	)

Sends data.

Like send(), this function sends raw data to the peer of a connection-mode socket, or to the predefined peer of a connection-less socket. Unlike send(), this function never triggers a signal; if the peer hung up, it returns an error.

Parameters

fd	socket to send data through
buf	start address of data
buflen	byte size of data
flags	socket send flags (see send() documentation)

Returns

number of bytes actually sent, or -1 on error (errno is set)

References vlc_sendto().

vlc_sendmsg()

ssize_t vlc_sendmsg	(	int	fd,
		const struct msghdr *	msg,
		int	flags
	)

Sends a socket message.

Like sendmsg(), this function sends a message through a socket. Unlike sendmsg(), this function never triggers a signal; if the peer hung up, it returns an error.

Parameters

fd	socket to send data through
msg	message to send (see sendmsg() documentation)
flags	socket send flags (see sendmsg() documentation)

Returns

number of bytes actually sent, or -1 on error (errno is set)

References MSG_NOSIGNAL, and sendmsg().

Referenced by vlc_datagram_Send(), vlc_sendmsg_i11e(), vlc_sendto(), vlc_tls_ConnectWrite(), and vlc_tls_SocketWrite().

vlc_sendto()

ssize_t vlc_sendto	(	int	fd,
		const void *	buf,
		size_t	buflen,
		int	flags,
		const struct sockaddr *	dst,
		socklen_t	dstlen
	)

Sends data to a peer.

This function operates like sendto() with the exception that it never triggers a signal.

This function mainly exists for the sakes of completeness and consistency:

• To send data on a connection-mode socket, using vlc_send() is simpler.
• To send data on a connection-less socket, sendto() and/or send() can be used directly.

Parameters

fd	socket to send data through
buf	start address of data
buflen	byte size of data
flags	socket send flags (see send() documentation)
dst	destination address (ignored for connection-mode sockets)
dstlen	byte size of destination address

Returns

number of bytes actually sent, or -1 on error (errno is set)

References vlc_sendmsg().

Referenced by vlc_send().

vlc_socket()

int vlc_socket	(	int	pf,
		int	type,
		int	proto,
		bool	nonblock
	)

Creates a socket file descriptor.

This function creates a socket, similar to the standard socket() function. However, the new file descriptor has the close-on-exec flag set atomically, so as to avoid leaking the descriptor to child processes.

The non-blocking flag can also optionally be set.

Parameters

pf	protocol family
type	socket type
proto	network protocol
nonblock	true to create a non-blocking socket

Returns

a new file descriptor or -1 on error

References vlc_socket_setup().

Referenced by net_Socket(), and vlc_tls_SocketAddrInfo().

vlc_socketpair()

int vlc_socketpair	(	int	pf,
		int	type,
		int	proto,
		int	fds[2],
		bool	nonblock
	)

Creates a pair of socket file descriptors.

This function creates a pair of sockets that are mutually connected, much like the standard socketpair() function. However, the new file descriptors have the close-on-exec flag set atomically. See also vlc_socket().

Parameters

pf	protocol family
type	socket type
proto	network protocol
fds	the output array storing the file descriptor pair
nonblock	true to create non-blocking sockets

Return values

0	on success
-1	on failure

References vlc_socket_setup().

Referenced by vlc_pipe(), and vlc_tls_SocketPair().