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

Network stream abstraction. More...

Collaboration diagram for Transport layer sockets:


 Transport Layer Security


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

Data Structures

struct  vlc_tls
 Transport layer socket. More...


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


void vlc_tls_SessionDelete (vlc_tls_t *)
 Destroys a TLS session down. More...
static int vlc_tls_GetFD (vlc_tls_t *tls)
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_creds_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.

Function Documentation

◆ vlc_tls_Close()

static void vlc_tls_Close ( vlc_tls_t session)

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, VLC_API, vlc_tls_SessionDelete(), vlc_tls_SocketOpen(), vlc_tls_SocketOpenAddrInfo(), vlc_tls_SocketOpenTCP(), vlc_tls_SocketOpenTLS(), and vlc_tls_SocketPair().

Referenced by httpd_ClientDestroy(), 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)

◆ vlc_tls_GetLine()

char* vlc_tls_GetLine ( vlc_tls_t )

Receives a text line through a socket.

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

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

References unlikely, and vlc_tls_Read().

Referenced by vlc_chunked_read(), and vlc_tls_GetFD().

◆ vlc_tls_Read()

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

Receives data through a socket.

This dequeues incoming data from a transport layer socket.

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)
At end of stream, the number of bytes returned may be shorter than requested regardless of the "waitall" flag.
the number of bytes actually dequeued, or -1 on error.

References pollfd::events, pollfd::fd, POLLIN, vlc_tls::readv, vlc_killed(), vlc_poll_i11e(), and vlc_tls_GetFD().

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

◆ vlc_tls_SessionDelete()

void vlc_tls_SessionDelete ( vlc_tls_t )

Destroys a TLS session down.

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::close, vlc_restorecancel(), and vlc_savecancel().

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

◆ vlc_tls_Shutdown()

static int vlc_tls_Shutdown ( vlc_tls_t tls,
bool  duplex 

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.

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)
-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::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.

This function is transitional. Do not use it directly.

References vlc_tls_SocketAlloc().

Referenced by httpdLoop(), and vlc_tls_Close().

◆ 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.
aia filled addrinfo structure (the ai_next member is ignored)
defer_connectwhether to attempt a TCP Fast Open connection or not

Referenced by vlc_tls_Close().

◆ 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.

The function currently iterates through the addrinfo linked list. Future versions may implement different behaviour (e.g. RFC6555).
a transport layer socket on success or NULL on error

References msg_Dbg, msg_Err, p, vlc_tls_socket::tls, vlc_getaddrinfo_i11e(), vlc_strerror_c(), and vlc_tls_SocketOpenAddrInfo().

Referenced by vlc_https_connect_proxy(), and vlc_tls_Close().

◆ vlc_tls_SocketOpenTLS()

vlc_tls_t* vlc_tls_SocketOpenTLS ( vlc_tls_creds_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_SessionCreate().

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

Referenced by vlc_https_connect(), and vlc_tls_Close().

◆ vlc_tls_SocketPair()

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

Creates a connected pair of transport-layer sockets.

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

Referenced by vlc_tls_Close().

◆ vlc_tls_Write()

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