ne_session_create
Prev | neon API reference | Next

## Name

ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy — set up HTTP sessions

## Synopsis

    #include <ne_session.h>

`ne_session *ne_session_create(` | const char *scheme,
| const char *hostname,
| unsigned int port`)`;

`void ne_session_proxy(` | ne_session *session,
| const char *hostname,
| 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 `ne_session_create`, giving the `hostname` and `port` of the server to use, along with the `scheme` used to contact the server (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` parameter, 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).

If an HTTP proxy server should be used for the session, `ne_session_proxy` must be called giving the hostname and port on which to contact the proxy.

Further per-session options may be changed using the ne_set_request_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.

## Notes

The hostname passed to `ne_session_create` is 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

Prev | Up | Next
ne_malloc | Home | ne_set_session_flag