| Home | Libraries | People | FAQ | More

###### basic_stream::async_connect (4 of 5 overloads)

Establishes a connection by trying each endpoint in a sequence asynchronously.

<h7> Synopsis </h7>

    template<
        class Iterator,
        class IteratorConnectHandler>
    async_connect(
        Iterator begin,
        Iterator end,
        IteratorConnectHandler&& handler);

<h7> Description </h7>

This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. The algorithm, known as a composed asynchronous operation, is implemented in terms of calls to the underlying socket's `async_connect` function. If the timeout timer expires while the operation is outstanding, the current connection attempt will be canceled and the completion handler will be invoked with the error `timeout`.

<h7> Parameters </h7>

Name | Description
--- | ---
`begin` | An iterator pointing to the start of a sequence of endpoints.
`end` | An iterator pointing to the end of a sequence of endpoints.

`handler`

The completion handler to invoke when the operation completes. The implementation takes ownership of the handler by performing a decay-copy. The equivalent function signature of the handler must be:

    void handler(
        // Result of operation. if the sequence is empty, set to
        // net::error::not_found. Otherwise, contains the
        // error from the last connection attempt.
        error_code const& error,

        // On success, an iterator denoting the successfully
        // connected endpoint. Otherwise, the end iterator.
        Iterator iterator
    );

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using `net::post`.