plucky (3) ne_session_create.3.gz

Provided by: libneon27-gnutls-dev_0.34.0-1_amd64 bug

NAME
       ne_session_create, ne_close_connection, ne_session_destroy - set up HTTP sessions


SYNOPSIS
       #include <ne_session.h>

       ne_session *ne_session_create(const char *scheme, const char *host, unsigned int port);

       void ne_close_connection(ne_session *session);

       void ne_session_destroy(ne_session *session);


DESCRIPTION
       An ne_session object represents an HTTP session - a logical grouping of a sequence of HTTP requests made
       to a certain server. Any requests made using the session can use a persistent connection, share cached
       authentication credentials and any other common attributes.

       A new HTTP session is created using the ne_session_create function; the host and port parameters specify
       the origin server to use, along with the scheme (usually "http"). Before the first use of
       ne_session_create in a process, ne_sock_init must have been called to perform any global initialization
       needed by any libraries used by neon.

       To enable SSL/TLS for the session, pass the string "https" as the scheme, and either register a
       certificate verification function (see ne_ssl_set_verify) or trust the appropriate certificate (see
       ne_ssl_trust_cert, ne_ssl_trust_default_ca).

       The host parameter must follow the definition of host host in RFC 3986[1], which can be an IP-literal or
       registered (DNS) hostname. Valid examples of each: "198.51.100.42" (IPv4 literal address),
       "[2001:db8::42]" (IPv6 literal, which MUST be enclosed in square brackets), or "www.example.com" (DNS
       hostname). The RFC 6874[2] syntax for scoped IPv6 link-local literal addresses is also permitted, for
       example "[fe80::1%25eth0]".

       The scheme parameter is used to determine the URI for resources identified during request handling. Other
       than special handling of the string "https", no other interpretation or checking of the scheme is
       performed. For example, if an HTTP-to-FTP proxy is configured, a scheme of "ftp" could be used to access
       resources.

       To use a proxy server for the session, it must be configured (see ne_session_proxy) before any requests
       are created from session object.

       Further per-session options may be changed using the ne_set_session_flag interface.

       If it is known that the session will not be used for a significant period of time, ne_close_connection
       can be called to close the connection, if one remains open. Use of this function is entirely optional,
       but it must not be called if there is a request active using the session.

       Once a session has been completed, ne_session_destroy must be called to destroy the resources associated
       with the session. Any subsequent use of the session pointer produces undefined behaviour. The session
       object must not be destroyed until after all associated request objects have been destroyed.


NOTES
       If a hostname is passed to ne_session_create, it will be resolved when the first request using the
       session is dispatched; a DNS resolution failure can only be detected at that time (using the NE_LOOKUP
       error code); see ne_request_dispatch for details.


RETURN VALUES
       ne_session_create will return a pointer to a new session object (and never NULL).


EXAMPLES
       Create and destroy a session:

           ne_session *sess;
           sess = ne_session_create("http", "host.example.com", 80);
           /* ... use sess ... */
           ne_session_destroy(sess);


SEE ALSO
       ne_ssl_set_verify, ne_ssl_trust_cert, ne_sock_init, ne_set_session_flag, ne_session_proxy


       Copyright © 2001-2024 Joe Orton


REFERENCES
        1. RFC 3986
           https://www.rfc-editor.org/rfc/rfc3986

        2. RFC 6874
           https://www.rfc-editor.org/rfc/rfc6874