= 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
xref:nng_aio_result.3.adoc[`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
xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] with an _index_ of zero (0).

== RETURN VALUES

None.

== ERRORS

[horizontal]
`NNG_EADDRINVAL`:: The client 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

[.text-left]
xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
xref:nng_aio_result.3.adoc[nng_aio_result(3)],
xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)],
xref:nng_http_conn_close.3http.adoc[nng_http_conn_close(3http)],
xref:nng_http_conn_read.3http.adoc[nng_http_conn_read(3http)],
xref:nng_http_conn_write.3http.adoc[nng_http_conn_write(3http)],
xref:nng.7.adoc[nng(7)]