| Home | Libraries | People | FAQ | More

##### websocket::stream::async_pong

Send a websocket pong control frame asynchronously.

###### Synopsis

    template<
        class WriteHandler = net::default_completion_token_t<executor_type>>
    DEDUCED
    async_pong(
        ping_data const& payload,
        WriteHandler&& handler = net::default_completion_token_t< executor_type >{});

###### Description

This function is used to asynchronously send a pong frame, which is usually sent automatically in response to a ping frame from the remote peer.

- The pong frame is written.
- An error occurs.

The algorithm, known as a composed asynchronous operation, is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to `ping`, `pong`, `async_ping`, or `async_pong` are performed until this operation completes. If a close frame is sent or received before the pong frame is sent, the error received by this completion handler will be `net::error::operation_aborted`. WebSocket allows pong frames to be sent at any time, without first receiving a ping. An unsolicited pong sent in this fashion may indicate to the remote peer that the connection is still active.

###### Parameters

Name | Description
--- | ---
`payload` | The payload of the pong message, which may be empty. The implementation will not access the contents of this object after the initiating function returns.

`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(
        error_code const& ec     // Result of operation
    );

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`.

###### Per-Operation Cancellation

This asynchronous operation supports cancellation for the following net::cancellation_type values:

- `net::cancellation_type::terminal`
- `net::cancellation_type::total`

`total`cancellation succeeds if the operation is suspended due to ongoing control operations such as a ping/pong. `terminal` cancellation succeeds when supported by the underlying stream. `terminal` cancellation leaves the stream in an undefined state, so that only closing it is guaranteed to succeed.