VLC  4.0.0-dev
Modules | Files | Data Structures | Typedefs | Functions

Network stream abstraction. More...

Collaboration diagram for Transport layer sockets:

Modules

 Transport Layer Security
 

Files

file  stream.c
 Transport-layer stream abstraction.
 
file  vlc_tls.h
 Transport layer functions.
 

Data Structures

struct  vlc_tls
 Transport layer socket. More...
 
struct  vlc_tls_operations
 

Typedefs

typedef struct vlc_tls vlc_tls_t
 Transport layer socket. More...
 

Functions

void vlc_tls_SessionDelete (vlc_tls_t *)
 Destroys a TLS session. More...
 
static int vlc_tls_GetPollFD (vlc_tls_t *tls, short *events)
 Generates an event polling description. More...
 
static int vlc_tls_GetFD (vlc_tls_t *tls)
 Returns the underlying file descriptor. More...
 
ssize_t vlc_tls_Read (vlc_tls_t *, void *buf, size_t len, bool waitall)
 Receives data through a socket. More...
 
char * vlc_tls_GetLine (vlc_tls_t *)
 Receives a text line through a socket. More...
 
ssize_t vlc_tls_Write (vlc_tls_t *, const void *buf, size_t len)
 Sends data through a socket. More...
 
static int vlc_tls_Shutdown (vlc_tls_t *tls, bool duplex)
 Shuts a connection down. More...
 
static void vlc_tls_Close (vlc_tls_t *session)
 Closes a connection and its underlying resources. More...
 
vlc_tls_tvlc_tls_SocketOpen (int fd)
 Creates a transport-layer stream from a socket. More...
 
int vlc_tls_SocketPair (int family, int protocol, vlc_tls_t *[2])
 Creates a connected pair of transport-layer sockets. More...
 
vlc_tls_tvlc_tls_SocketOpenAddrInfo (const struct addrinfo *ai, bool defer_connect)
 Creates a transport-layer stream from a struct addrinfo. More...
 
vlc_tls_tvlc_tls_SocketOpenTCP (vlc_object_t *obj, const char *hostname, unsigned port)
 Creates a transport-layer TCP stream from a name and port. More...
 
vlc_tls_tvlc_tls_SocketOpenTLS (vlc_tls_client_t *crd, const char *hostname, unsigned port, const char *service, const char *const *alpn, char **alp)
 Initiates a TLS session over TCP. More...
 

Detailed Description

Network stream abstraction.

Originally intended for the TLS protocol (Transport Layer Security), the Transport Layer Sockets now provides a generic abstraction for connection-oriented full-duplex I/O byte streams, such as TCP/IP sockets and TLS protocol sessions.

Typedef Documentation

◆ vlc_tls_t

typedef struct vlc_tls vlc_tls_t

Transport layer socket.

Transport layer sockets are full-duplex, meaning data can be sent and received at the same time. As such, it is permitted for two threads to use the same TLS simultaneously, if one thread is receiving data while the other is sending data. However receiving or sending data from two threads concurrently is undefined behaviour.

The following functions are treated as sending data:

The following functions are treated as receiving data:

Function Documentation

◆ vlc_tls_Close()

static void vlc_tls_Close ( vlc_tls_t session)
inlinestatic

Closes a connection and its underlying resources.

This function closes the transport layer socket, and terminates any underlying connection. For instance, if the TLS protocol is used over a TCP stream, this function terminates both the TLS session, and then underlying TCP/IP connection.

To close a connection but retain any underlying resources, use vlc_tls_SessionDelete() instead.

References vlc_tls::p, p, and vlc_tls_SessionDelete().

Referenced by httpd_ClientDestroy(), httpdLoop(), vlc_h1_conn_destroy(), vlc_h1_stream_fatal(), vlc_h2_conn_destroy(), vlc_https_connect_proxy(), and vlc_https_request().

◆ vlc_tls_GetFD()

static int vlc_tls_GetFD ( vlc_tls_t tls)
inlinestatic

Returns the underlying file descriptor.

This function returns the file descriptor underlying the transport layer stream object. This function is reentrant and is not a cancellation point.

References vlc_tls_GetPollFD().

Referenced by httpd_ClientIP(), httpd_ServerIP(), and vlc_tls_WaitConnect().

◆ vlc_tls_GetLine()

char* vlc_tls_GetLine ( vlc_tls_t session)

Receives a text line through a socket.

This dequeues one line of text from a transport layer socket.

Returns
a heap-allocated nul-terminated string, or NULL on error

References unlikely, and vlc_tls_Read().

Referenced by vlc_chunked_read().

◆ vlc_tls_GetPollFD()

static int vlc_tls_GetPollFD ( vlc_tls_t tls,
short *  events 
)
inlinestatic

Generates an event polling description.

This function provides the necessary informations to make an event polling description for use with poll() or similar event multiplexing functions.

This function is necessary both for receiving and sending data, therefore it is reentrant. It is not a cancellation point.

Parameters
eventsa pointer to a mask of poll events (e.g. POLLIN, POLLOUT) [IN/OUT]
Returns
the file descriptor to poll

References vlc_tls_operations::get_fd, and vlc_tls::ops.

Referenced by httpdLoop(), vlc_https_recv(), vlc_https_send(), vlc_tls_ClientSessionCreate(), vlc_tls_GetFD(), vlc_tls_ProxyGetFD(), vlc_tls_Read(), and vlc_tls_Write().

◆ vlc_tls_Read()

ssize_t vlc_tls_Read ( vlc_tls_t session,
void *  buf,
size_t  len,
bool  waitall 
)

Receives data through a socket.

This dequeues incoming data from a transport layer socket.

Parameters
bufreceived buffer start address [OUT]
lenbuffer length (in bytes)
waitallwhether to wait for the exact buffer length (true), or for any amount of data (false)
Note
At end of stream, the number of bytes returned may be shorter than requested regardless of the "waitall" flag.
Returns
the number of bytes actually dequeued, or -1 on error.

References pollfd::events, pollfd::fd, vlc_tls::ops, POLLIN, vlc_tls_operations::readv, vlc_killed(), vlc_poll_i11e(), and vlc_tls_GetPollFD().

Referenced by vlc_chunked_read(), vlc_h1_stream_read(), vlc_https_headers_recv(), and vlc_tls_GetLine().

◆ vlc_tls_SessionDelete()

void vlc_tls_SessionDelete ( vlc_tls_t session)

Destroys a TLS session.

All resources associated with the TLS session are released.

If the session was established successfully, then shutdown cleanly, the underlying socket can be reused. Otherwise, it must be closed. Either way, this function does not close the underlying socket: Use vlc_tls_Close() instead to close it at the same.

This function is non-blocking and is not a cancellation point.

References vlc_tls_operations::close, vlc_tls::ops, vlc_restorecancel(), and vlc_savecancel().

Referenced by cleanup_tls(), httpdLoop(), vlc_tls_ClientSessionCreate(), vlc_tls_Close(), vlc_tls_SocketOpenAddrInfo(), vlc_tls_SocketOpenTLS(), and vlc_tls_SocketPair().

◆ vlc_tls_Shutdown()

static int vlc_tls_Shutdown ( vlc_tls_t tls,
bool  duplex 
)
inlinestatic

Shuts a connection down.

This sends the connection close notification.

If the TLS protocol is used, this provides a secure indication to the other end that no further data will be sent. If using plain TCP/IP, this sets the FIN flag.

Data can still be received until a close notification is received from the other end.

Parameters
duplexwhether to stop receiving data as well
Return values
0the session was terminated securely and cleanly (the underlying socket can be reused for other purposes)
Returns
-1 the session was terminated locally, but either a notification could not be sent or received (the underlying socket cannot be reused and must be closed)

References vlc_tls::ops, and vlc_tls_operations::shutdown.

Referenced by vlc_h1_conn_destroy(), vlc_h1_stream_fatal(), vlc_h2_conn_destroy(), and vlc_tls_ProxyShutdown().

◆ vlc_tls_SocketOpen()

vlc_tls_t* vlc_tls_SocketOpen ( int  fd)

Creates a transport-layer stream from a socket.

Creates a transport-layer I/O stream from a socket file descriptor. Data will be sent and received directly through the socket. This can be used either to share common code between non-TLS and TLS cases, or for testing purposes.

This function is not a cancellation point.

Deprecated:
This function is transitional. Do not use it directly.

References vlc_tls_SocketAlloc().

Referenced by httpdLoop().

◆ vlc_tls_SocketOpenAddrInfo()

vlc_tls_t* vlc_tls_SocketOpenAddrInfo ( const struct addrinfo *  ai,
bool  defer_connect 
)

Creates a transport-layer stream from a struct addrinfo.

This function tries to allocate a socket using the specified addrinfo structure. Normally, the vlc_tls_SocketOpenTCP() function takes care of this. But in some cases, it cannot be used, notably:

  • if the remote destination is not resolved (directly) from getaddrinfo(),
  • if the socket type is not SOCK_STREAM,
  • if the transport protocol is not TCP (IPPROTO_TCP), or
  • if TCP Fast Open should be attempted.
Note
If the defer_connect flag is true , data must be sent with a data sending function (other than vlc_tls_Shutdown()) before data can be received. Notwithstanding the thread-safety and reentrancy promises of vlc_tls_t, the owner of the stream object is responsible for ensuring that data will be sent at least once before any attempt to receive data. Otherwise defer_connect must be false .
Parameters
aia filled addrinfo structure (the ai_next member is ignored)
defer_connectwhether to attempt a TCP Fast Open connection or not

◆ vlc_tls_SocketOpenTCP()

vlc_tls_t* vlc_tls_SocketOpenTCP ( vlc_object_t obj,
const char *  hostname,
unsigned  port 
)

Creates a transport-layer TCP stream from a name and port.

This function resolves a hostname, and attempts to establish a TCP/IP connection to the specified host and port number.

Parameters
objoptional object to log errors (may be NULL)
hostnameremote host name or IP address literal to connect to
portremote TCP port number to connect to
Note
The function currently iterates through the addrinfo linked list. Future versions may implement different behaviour (e.g. RFC6555).
Returns
a transport layer socket on success or NULL on error

Referenced by vlc_https_connect_proxy().

◆ vlc_tls_SocketOpenTLS()

vlc_tls_t* vlc_tls_SocketOpenTLS ( vlc_tls_client_t crd,
const char *  hostname,
unsigned  port,
const char *  service,
const char *const *  alpn,
char **  alp 
)

Initiates a TLS session over TCP.

This function resolves a hostname, attempts to establish a TCP/IP connection to the specified host and port number, and finally attempts to establish a TLS session over the TCP/IP stream.

See also vlc_tls_SocketOpenTCP() and vlc_tls_ClientSessionCreate().

References msg_Dbg, msg_Err, name, p, vlc_getaddrinfo_i11e(), vlc_strerror_c(), vlc_tls_ClientSessionCreate(), vlc_tls_SessionDelete(), and vlc_tls_SocketOpenAddrInfo().

Referenced by vlc_https_connect().

◆ vlc_tls_SocketPair()

int vlc_tls_SocketPair ( int  family,
int  protocol,
vlc_tls_t pair[2] 
)

Creates a connected pair of transport-layer sockets.

References net_Close, unlikely, vlc_socketpair(), vlc_tls_SessionDelete(), and vlc_tls_SocketAlloc().

◆ vlc_tls_Write()

ssize_t vlc_tls_Write ( vlc_tls_t session,
const void *  buf,
size_t  len 
)