libwget-net - TCP sockets

       Generated automatically by Doxygen for wget2 from the source code.

wget2                                             Version 2.2.0                                   libwget-net(3)

       TCP sockets and DNS cache management functions.

       The following features are supported:

       • TCP Fast Open (RFC 7413)

       • SSL/TLS

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

       • Timeout:  maximum  time to wait for an operation to complete. For example, for wget_tcp_read(), it sets
         the maximum time to wait until some data is available to read. Most functions here can be  non-blocking
         (with  timeout  = 0) returning immediately or they can block indefinitely until something happens (with
         timeout = -1). For any value greater than zero, the timeout is taken as milliseconds.

       • Family and preferred family: these are used to determine which  address  family  should  be  used  when
         resolving  a  host name or IP address. You probably use 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.

       • SSL/TLS: do you want to use TLS?

       When you create a new wget_tcp with wget_tcp_init(), it is initialized with the following parameters:

       • Timeout: -1

       • Connection timeout (max. time to wait for a connection to be accepted by the remote host): -1

       • DNS timeout (max. time to wait for a DNS query to return): -1

       • Family: AF_UNSPEC (basically means 'I don't care, pick the first one available').

intwget_net_init(void)Returns
           0 for success, else failure

       Initialize the resources needed for network operations.

   intwget_net_deinit(void)Returns
           0 for success, else failure

       Free the resources allocated by wget_net_init().

   voidwget_tcp_set_dns(wget_tcp*tcp,wget_dns*dns)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().
           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).

   voidwget_tcp_set_tcp_fastopen(wget_tcp*tcp,booltcp_fastopen)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.
           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.

   boolwget_tcp_get_tcp_fastopen(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           1 if TCP Fast Open is enabled, 0 otherwise.

       Tells whether TCP Fast Open is enabled or not.

       You can enable and disable it with wget_tcp_set_tcp_fastopen().

   voidwget_tcp_set_tls_false_start(wget_tcp*tcp,boolfalse_start)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.
           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.

   boolwget_tcp_get_tls_false_start(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           1 if TLS False Start is enabled, 0 otherwise.

       Tells whether TLS False Start is enabled or not.

       You can enable and disable it with wget_tcp_set_tls_false_start().

   voidwget_tcp_set_protocol(wget_tcp*tcp,intprotocol)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().
           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).

   intwget_tcp_get_protocol(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().

       Returns
           The protocol with this connection, currently WGET_PROTOCOL_HTTP_2_0 or WGET_PROTOCOL_HTTP_1_1.

       Get protocol used with the provided connection, or globally (if tcp is NULL).

   voidwget_tcp_set_preferred_family(wget_tcp*tcp,intfamily)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.
           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.

   intwget_tcp_get_preferred_family(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           One of the socket families defined in <socket.h>, such as AF_INET or AF_INET6.

       Get the preferred address family that was previously set with wget_tcp_set_preferred_family().

   voidwget_tcp_set_family(wget_tcp*tcp,intfamily)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.
           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.

   intwget_tcp_get_family(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           One of the socket families defined in <socket.h>, such as AF_INET or AF_INET6.

       Get the address family that was previously set with wget_tcp_set_family().

   intwget_tcp_get_local_port(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           The local port.

       Get the port number the TCP connection tcp is bound to on the local machine.

   voidwget_tcp_set_connect_timeout(wget_tcp*tcp,inttimeout)Parameterstcp A TCP connection.
           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.

   voidwget_tcp_set_timeout(wget_tcp*tcp,inttimeout)Parameterstcp A TCP connection.
           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.

   intwget_tcp_get_timeout(wget_tcp*tcp)Parameterstcp A TCP connection.

       Returns
           The timeout value that was set with wget_tcp_set_timeout().

       Get the timeout value that was set with wget_tcp_set_timeout().

   voidwget_tcp_set_bind_address(wget_tcp*tcp,constchar*bind_address)Parameterstcp A TCP connection. Might be NULL.
           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().

   voidwget_tcp_set_bind_interface(wget_tcp*tcp,constchar*bind_interface)Parameterstcp A TCP connection. Might be NULL.
           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().

   voidwget_tcp_set_ssl(wget_tcp*tcp,boolssl)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().
           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.

   boolwget_tcp_get_ssl(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().

       Returns
           1 if TLs is enabled, 0 otherwise.

       Tells whether TLS is enabled or not.

   constchar*wget_tcp_get_ip(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().

       Returns
           IP address as string, NULL if not available.

       Returns the IP address of a wget_tcp instance.

   voidwget_tcp_set_ssl_hostname(wget_tcp*tcp,constchar*hostname)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.
           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.

   constchar*wget_tcp_get_ssl_hostname(wget_tcp*tcp)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init(). Might be NULL.

       Returns
           A hostname. The value of the SNI field.

       Returns the value that was set to SNI with a previous call to wget_tcp_set_ssl_hostname().

   wget_tcp*wget_tcp_init(void)Returns
           A new 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().

   voidwget_tcp_deinit(wget_tcp**_tcp)Parameters_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.

   intwget_tcp_ready_2_transfer(wget_tcp*tcp,intflags)
       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)?

   intwget_tcp_connect(wget_tcp*tcp,constchar*host,uint16_tport)Parameterstcp A wget_tcp structure representing a TCP connection, returned by wget_tcp_init().
           host Hostname or IP address to connect to.
           port port number

       Returns
           WGET_E_SUCCESS (0) on success, or a  negative  integer  on  error  (some  of  WGET_E_XXX  defined  in
           <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.

   intwget_tcp_tls_start(wget_tcp*tcp)Parameterstcp An active connection.

       Returns
           WGET_E_SUCCESS (0) on success, or a  negative  integer  on  error  (one  of  WGET_E_XXX,  defined  in
           <wget.h>).StartTLSforthisconnection.

       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.

   voidwget_tcp_tls_stop(wget_tcp*tcp)Parameterstcp An active connection.

       Stops TLS, but does not close the connection. Data will be transmitted in the clear from now on.

   ssize_twget_tcp_read(wget_tcp*tcp,char*buf,size_tcount)Parameterstcp An active TCP connection.
           buf Destination buffer, at least count bytes long.
           count Length of the buffer buf.

       Returns
           Number of bytes read

       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_twget_tcp_write(wget_tcp*tcp,constchar*buf,size_tcount)Parameterstcp An active TCP connection.
           buf A buffer, at least count bytes long.
           count Number of bytes from buf to send through tcp.

       Returns
           The number of bytes written, or -1 on error.

       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_twget_tcp_vprintf(wget_tcp*tcp,constchar*fmt,va_listargs)Parameterstcp An active TCP connection.
           fmt Format string (like in printf(3)).
           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_twget_tcp_printf(wget_tcp*tcp,constchar*fmt,...)Parameterstcp An active TCP connection.
           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().

   voidwget_tcp_close(wget_tcp*tcp)Parameterstcp An active TCP connection

       Close a TCP connection.

       libwget-net - TCP sockets

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)