= nng_http_client_connect(3http)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_http_client_connect - establish HTTP client connection

== SYNOPSIS

[source, c]
-----------
#include <nng/nng.h>
#include <nng/supplemental/http/http.h>

void nng_http_client_connect(nng_http_client *client, nng_aio *aio);
-----------

== DESCRIPTION

The `nng_http_client_connect()` starts the process of establishing an HTTP
connection from _client_ to the server that was indicated in the URL that
_client_ was configured with.

The result of the operation will be stored in the _aio_ when the operation
is complete, and will be obtainable via
<<nng_aio_result.3#,`nng_aio_result()`>>.

On success, a pointer to the underlying HTTP client (type `nng_http_conn *`)
will be stored in the first output result of the _aio_, and can be
obtained by
<<nng_aio_get_output.3#,`nng_aio_get_output()`>> with an _index_ of zero (0).

== RETURN VALUES

None.

== ERRORS

`NNG_EADDRINVAL`:: The server is configured with an invalid address.
`NNG_ECANCELED`:: The operation was aborted.
`NNG_ECONNREFUSED`:: The TCP connection was refused by the server.
`NNG_ECONNRESET`:: The TCP connection was reset by the server.
`NNG_ENOMEM`:: Insufficient free memory exists.

== EXAMPLE

[source, c]
----
    nng_aio *aio;
    nng_url *url;
    nng_http_client *client;
    nng_http_conn *conn;
    int rv;

    // Error checks elided for clarity.
    nng_url_parse(&url, "http://www.google.com");
    nng_aio_alloc(&aio, NULL, NULL);
    nng_http_client_alloc(&client, url);

    nng_http_client_connect(client, aio);

    // Wait for connection to establish (or attempt to fail).
    nng_aio_wait(aio);

    if ((rv = nng_aio_result(aio)) != 0) {
            printf("Connection failed: %s\n", nng_strerror(rv));
    } else {
            // Connection established, get it.
            conn = nng_aio_get_output(aio, 0);

            // ... do something with it here

            // Close the connection when done to avoid leaking it.
            nng_http_conn_close(conn);
    }
----

== SEE ALSO

<<nng_aio_get_output.3#,nng_aio_get_output(3)>>,
<<nng_aio_result.3#,nng_aio_result(3)>>,
<<nng_aio_wait.3#,nng_aio_wait(3)>>,
<<nng_strerror.3#,nng_strerror(3)>>,
<<nng_http_client_alloc.3http#,nng_http_client_alloc(3http)>>,
<<nng_http_conn_close.3http#,nng_http_conn_close(3http)>>,
<<nng_http_conn_read.3http#,nng_http_conn_read(3http)>>,
<<nng_http_conn_write.3http#,nng_http_conn_write(3http)>>,
<<nng.7#,nng(7)>>