wget2 2.1.0
|
Functions | |
int | wget_net_init (void) |
int | wget_net_deinit (void) |
void | wget_tcp_set_dns (wget_tcp *tcp, wget_dns *dns) |
void | wget_tcp_set_tcp_fastopen (wget_tcp *tcp, bool tcp_fastopen) |
bool | wget_tcp_get_tcp_fastopen (wget_tcp *tcp) |
void | wget_tcp_set_tls_false_start (wget_tcp *tcp, bool false_start) |
bool | wget_tcp_get_tls_false_start (wget_tcp *tcp) |
void | wget_tcp_set_protocol (wget_tcp *tcp, int protocol) |
int | wget_tcp_get_protocol (wget_tcp *tcp) |
void | wget_tcp_set_preferred_family (wget_tcp *tcp, int family) |
int | wget_tcp_get_preferred_family (wget_tcp *tcp) |
void | wget_tcp_set_family (wget_tcp *tcp, int family) |
int | wget_tcp_get_family (wget_tcp *tcp) |
int | wget_tcp_get_local_port (wget_tcp *tcp) |
void | wget_tcp_set_connect_timeout (wget_tcp *tcp, int timeout) |
void | wget_tcp_set_timeout (wget_tcp *tcp, int timeout) |
int | wget_tcp_get_timeout (wget_tcp *tcp) |
void | wget_tcp_set_bind_address (wget_tcp *tcp, const char *bind_address) |
void | wget_tcp_set_bind_interface (wget_tcp *tcp, const char *bind_interface) |
void | wget_tcp_set_ssl (wget_tcp *tcp, bool ssl) |
bool | wget_tcp_get_ssl (wget_tcp *tcp) |
const char * | wget_tcp_get_ip (wget_tcp *tcp) |
void | wget_tcp_set_ssl_hostname (wget_tcp *tcp, const char *hostname) |
const char * | wget_tcp_get_ssl_hostname (wget_tcp *tcp) |
wget_tcp * | wget_tcp_init (void) |
void | wget_tcp_deinit (wget_tcp **_tcp) |
int | wget_tcp_ready_2_transfer (wget_tcp *tcp, int flags) |
int | wget_tcp_connect (wget_tcp *tcp, const char *host, uint16_t port) |
int | wget_tcp_tls_start (wget_tcp *tcp) |
void | wget_tcp_tls_stop (wget_tcp *tcp) |
ssize_t | wget_tcp_read (wget_tcp *tcp, char *buf, size_t count) |
ssize_t | wget_tcp_write (wget_tcp *tcp, const char *buf, size_t count) |
ssize_t | wget_tcp_vprintf (wget_tcp *tcp, const char *fmt, va_list args) |
ssize_t | wget_tcp_printf (wget_tcp *tcp, const char *fmt,...) |
void | wget_tcp_close (wget_tcp *tcp) |
TCP sockets and DNS cache management functions.
The following features are supported:
Most functions here take a wget_tcp
structure as argument.
The wget_tcp
structure represents a TCP connection. You create it with wget_tcp_init() and destroy it with wget_tcp_deinit(). You can connect to a remote host with wget_tcp_connect(), or listen for incoming connections (and accept them) with wget_tcp_listen() and wget_tcp_accept(). You end a connection with wget_tcp_close().
There are several knobs you can use to customize the behavior of most functions here. The list that follows describes the most important parameters, although you can look at the getter and setter functions here to see them all (wget_tcp_get_xxx
, wget_tcp_set_xxx
).
AF_INET
or AF_INET6
most of the time. The first one forces the library to use that family, failing if it cannot find any IP address with it. The second one is just a hint, about which family you would prefer; it will try to get an address of that family if possible, and will get another one if not.When you create a new wget_tcp
with wget_tcp_init(), it is initialized with the following parameters:
AF_UNSPEC
(basically means "I don't care, pick the first one available"). int wget_net_init | ( | void | ) |
Initialize the resources needed for network operations.
int wget_net_deinit | ( | void | ) |
Free the resources allocated by wget_net_init().
void wget_tcp_set_dns | ( | wget_tcp * | tcp, |
wget_dns * | dns | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
[in] | protocol | The protocol, either WGET_PROTOCOL_HTTP_2_0 or WGET_PROTOCOL_HTTP_1_1. |
Set the protocol for the connection provided, or globally.
If tcp
is NULL, theprotocol will be set globally (for all connections). Otherwise, only for the provided connection (tcp
).
void wget_tcp_set_tcp_fastopen | ( | wget_tcp * | tcp, |
bool | tcp_fastopen | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
[in] | tcp_fastopen | 1 or 0, whether to enable or disable TCP Fast Open. |
Enable or disable TCP Fast Open (RFC 7413), if available.
This function is a no-op on systems where TCP Fast Open is not supported.
If tcp
is NULL, TCP Fast Open is enabled or disabled globally.
bool wget_tcp_get_tcp_fastopen | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
Tells whether TCP Fast Open is enabled or not.
You can enable and disable it with wget_tcp_set_tcp_fastopen().
void wget_tcp_set_tls_false_start | ( | wget_tcp * | tcp, |
bool | false_start | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
[in] | false_start | 1 or 0, whether to enable or disable TLS False Start. |
Enable or disable TLS False Start (RFC 7918).
If tcp
is NULL, TLS False Start is enabled or disabled globally.
bool wget_tcp_get_tls_false_start | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
Tells whether TLS False Start is enabled or not.
You can enable and disable it with wget_tcp_set_tls_false_start().
void wget_tcp_set_protocol | ( | wget_tcp * | tcp, |
int | protocol | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
[in] | protocol | The protocol, either WGET_PROTOCOL_HTTP_2_0 or WGET_PROTOCOL_HTTP_1_1. |
Set the protocol for the connection provided, or globally.
If tcp
is NULL, theprotocol will be set globally (for all connections). Otherwise, only for the provided connection (tcp
).
int wget_tcp_get_protocol | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
Get protocol used with the provided connection, or globally (if tcp
is NULL).
void wget_tcp_set_preferred_family | ( | wget_tcp * | tcp, |
int | family | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
[in] | family | One of the socket families defined in <socket.h> , such as AF_INET or AF_INET6 . |
Tells the preferred address family that should be used when establishing a TCP connection.
wget_tcp_resolve() will favor that and pick an address of that family if possible.
If tcp
is NULL, the preferred address family will be set globally.
int wget_tcp_get_preferred_family | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
<socket.h>
, such as AF_INET
or AF_INET6
.Get the preferred address family that was previously set with wget_tcp_set_preferred_family().
void wget_tcp_set_family | ( | wget_tcp * | tcp, |
int | family | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
[in] | family | One of the socket families defined in <socket.h> , such as AF_INET or AF_INET6 . |
Tell the address family that will be used when establishing a TCP connection.
wget_tcp_resolve() will pick an address of that family, or fail if it cannot find one.
If tcp
is NULL, the address family will be set globally.
int wget_tcp_get_family | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
<socket.h>
, such as AF_INET
or AF_INET6
.Get the address family that was previously set with wget_tcp_set_family().
int wget_tcp_get_local_port | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
Get the port number the TCP connection tcp
is bound to on the local machine.
void wget_tcp_set_connect_timeout | ( | wget_tcp * | tcp, |
int | timeout | ||
) |
[in] | tcp | A TCP connection. |
[in] | timeout | The timeout value. |
Set the timeout for the TCP connection.
This is the maximum time to wait until the remote host accepts our connection.
The following two values are special:
0
: No timeout, immediate.-1
: Infinite timeout. Wait indefinitely. void wget_tcp_set_timeout | ( | wget_tcp * | tcp, |
int | timeout | ||
) |
[in] | tcp | A TCP connection. |
[in] | timeout | The timeout value. |
Set the timeout (in milliseconds) for wget_tcp_read(), wget_tcp_write() and wget_tcp_accept().
The following two values are special:
0
: No timeout, immediate.-1
: Infinite timeout. Wait indefinitely. int wget_tcp_get_timeout | ( | wget_tcp * | tcp | ) |
[in] | tcp | A TCP connection. |
Get the timeout value that was set with wget_tcp_set_timeout().
void wget_tcp_set_bind_address | ( | wget_tcp * | tcp, |
const char * | bind_address | ||
) |
[in] | tcp | A TCP connection. Might be NULL. |
[in] | bind_address | An IP address or host name. |
Set the IP address/hostname the socket tcp
will bind to on the local machine when connecting to a remote host.
The hostname can explicitly set the port after a colon (':').
This is mainly relevant to wget_tcp_connect().
void wget_tcp_set_bind_interface | ( | wget_tcp * | tcp, |
const char * | bind_interface | ||
) |
[in] | tcp | A TCP connection. Might be NULL. |
[in] | bind_interface | A network interface name. |
Set the Network Interface the socket tcp
will bind to on the local machine when connecting to a remote host.
This is mainly relevant to wget_tcp_connect().
void wget_tcp_set_ssl | ( | wget_tcp * | tcp, |
bool | ssl | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
[in] | ssl | Flag to enable or disable SSL/TLS on the given connection. |
Enable or disable SSL/TLS.
If tcp
is NULL, TLS will be enabled globally. Otherwise, TLS will be enabled only for the provided connection.
bool wget_tcp_get_ssl | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
Tells whether TLS is enabled or not.
const char * wget_tcp_get_ip | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
Returns the IP address of a wget_tcp
instance.
void wget_tcp_set_ssl_hostname | ( | wget_tcp * | tcp, |
const char * | hostname | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
[in] | hostname | A hostname. The value of the SNI field. |
Sets the TLS Server Name Indication (SNI). For more info see RFC 6066, sect. 3.
SNI basically does at the TLS layer what the Host:
header field does at the application (HTTP) layer. The server might use this information to locate an appropriate X.509 certificate from a pool of certificates, or to direct the request to a specific virtual host, for instance.
const char * wget_tcp_get_ssl_hostname | ( | wget_tcp * | tcp | ) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
Returns the value that was set to SNI with a previous call to wget_tcp_set_ssl_hostname().
wget_tcp * wget_tcp_init | ( | void | ) |
wget_tcp
structure, with pre-defined parameters.Create a new wget_tcp
structure, that represents a TCP connection. It can be destroyed with wget_tcp_deinit().
This function does not establish or modify a TCP connection in any way. That can be done with the other functions in this file, such as wget_tcp_connect() or wget_tcp_listen() and wget_tcp_accept().
void wget_tcp_deinit | ( | wget_tcp ** | _tcp | ) |
[in] | _tcp | A pointer to a wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL. |
Release a TCP connection (created with wget_tcp_init()).
The wget_tcp
structure will be freed and _tcp
will be set to NULL.
If _tcp
is NULL, the SNI field will be cleared.
Does not free the internal DNS cache, so that other connections can reuse it. Call wget_dns_cache_free() if you want to free it.
int wget_tcp_ready_2_transfer | ( | wget_tcp * | tcp, |
int | flags | ||
) |
Test whether the given connection (tcp
) is ready to read or write.
The parameter flags
can have one or both (with bitwise OR) of the following values:
WGET_IO_READABLE
: Is data available for reading?WGET_IO_WRITABLE
: Can we write immediately (without having to wait until the TCP buffer frees)? int wget_tcp_connect | ( | wget_tcp * | tcp, |
const char * | host, | ||
uint16_t | port | ||
) |
[in] | tcp | A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). |
[in] | host | Hostname or IP address to connect to. |
[in] | port | port number |
<wget.h>
).Open a TCP connection with a remote host.
This function will use TLS if it has been enabled for this wget_tcp
. You can enable it with wget_tcp_set_ssl(). Additionally, you can also use wget_tcp_set_ssl_hostname() to set the Server Name Indication (SNI).
You can set which IP address and port on the local machine will the socket be bound to with wget_tcp_set_bind_address(). Otherwise the socket will bind to any address and port chosen by the operating system.
You can also set which Network Interface on the local machine will the socket be bound to with wget_tcp_bind_interface().
This function will try to use TCP Fast Open if enabled and available. If TCP Fast Open fails, it will fall back to the normal TCP handshake, without raising an error. You can enable TCP Fast Open with wget_tcp_set_tcp_fastopen().
If the connection fails, WGET_E_CONNECT
is returned.
int wget_tcp_tls_start | ( | wget_tcp * | tcp | ) |
[in] | tcp | An active connection. |
<wget.h>
). Start TLS for this connection.This will typically be called by wget_tcp_accept().
If the socket is listening (e.g. wget_tcp_listen(), wget_tcp_accept()), it will expect the client to perform a TLS handshake, and fail if it doesn't.
If this is a client connection (e.g. wget_tcp_connect()), it will try perform a TLS handshake with the server.
void wget_tcp_tls_stop | ( | wget_tcp * | tcp | ) |
[in] | tcp | An active connection. |
Stops TLS, but does not close the connection. Data will be transmitted in the clear from now on.
ssize_t wget_tcp_read | ( | wget_tcp * | tcp, |
char * | buf, | ||
size_t | count | ||
) |
[in] | tcp | An active TCP connection. |
[in] | buf | Destination buffer, at least count bytes long. |
[in] | count | Length of the buffer buf . |
Read count
bytes of data from the TCP connection represented by tcp
and store them in the buffer buf
.
This function knows whether the provided connection is over TLS or not and it will do the right thing.
The tcp->timeout
parameter is taken into account by this function as well. It specifies how long should this function wait until there's data available to read (in milliseconds). The default timeout is -1, which means to wait indefinitely.
The following two values are special:
0
: No timeout, immediate.-1
: Infinite timeout. Wait indefinitely until a new connection comes.You can set the timeout with wget_tcp_set_timeout().
In particular, the returned value will be zero if no data was available for reading before the timeout elapsed.
ssize_t wget_tcp_write | ( | wget_tcp * | tcp, |
const char * | buf, | ||
size_t | count | ||
) |
[in] | tcp | An active TCP connection. |
[in] | buf | A buffer, at least count bytes long. |
[in] | count | Number of bytes from buf to send through tcp . |
Write count
bytes of data from the buffer buf
to the TCP connection represented by tcp
.
This function knows whether the provided connection is over TLS or not and it will do the right thing.
TCP Fast Open will be used if it's available and enabled. You can enable TCP Fast Open with wget_tcp_set_tcp_fastopen().
This function honors the timeout
parameter. If the write operation fails because the socket buffer is full, then it will wait at most that amount of milliseconds. If after the timeout the socket is still unavailable for writing, this function returns zero.
The following two values are special:
0
: No timeout. The socket must be available immediately.-1
: Infinite timeout. Wait indefinitely until the socket becomes available.You can set the timeout with wget_tcp_set_timeout().
ssize_t wget_tcp_vprintf | ( | wget_tcp * | tcp, |
const char * | fmt, | ||
va_list | args | ||
) |
[in] | tcp | An active TCP connection. |
[in] | fmt | Format string (like in printf(3) ). |
[in] | args | va_args argument list (like in vprintf(3) ) |
Write data in vprintf-style format, to the connection tcp
.
It uses wget_tcp_write().
ssize_t wget_tcp_printf | ( | wget_tcp * | tcp, |
const char * | fmt, | ||
... | |||
) |
[in] | tcp | An active TCP connection. |
[in] | fmt | Format string (like in printf(3) ). |
Write data in printf-style format, to the connection tcp
.
It uses wget_tcp_vprintf(), which in turn uses wget_tcp_write().
void wget_tcp_close | ( | wget_tcp * | tcp | ) |
[in] | tcp | An active TCP connection |
Close a TCP connection.