| Home | Libraries | People | FAQ | More

###### websocket::stream::control_callback (1 of 2 overloads)

Set a callback to be invoked on each incoming control frame.

<h7> Synopsis </h7>

    void
    control_callback(
        std::function< void(frame_type, string_view)> cb);

<h7> Description </h7>

Sets the callback to be invoked whenever a ping, pong, or close control frame is received during a call to one of the following functions:

- `websocket::stream::read`
- `websocket::stream::read_some`
- `websocket::stream::async_read`
- `websocket::stream::async_read_some`

Unlike completion handlers, the callback will be invoked for each control frame during a call to any synchronous or asynchronous read function. The operation is passive, with no associated error code, and triggered by reads. For close frames, the close reason code may be obtained by calling the function `websocket::stream::reason`.

<h7> Parameters </h7>

Name | Description
--- | ---

`cb`

The function object to call, which must be invocable with this equivalent signature:

    void
    callback(
        frame_type kind,       // The type of frame
        string_view payload    // The payload in the frame
    );

The implementation type-erases the callback which may require a dynamic allocation. To prevent the possibility of a dynamic allocation, use `std::ref` to wrap the callback. If the read operation which receives the control frame is an asynchronous operation, the callback will be invoked using the same method as that used to invoke the final handler.

<h7> Remarks </h7>

Incoming ping and close frames are automatically handled. Pings are responded to with pongs, and a close frame is responded to with a close frame leading to the closure of the stream. It is not necessary to manually send pings, pongs, or close frames from inside the control callback. Attempting to manually send a close frame from inside the control callback after receiving a close frame will result in undefined behavior.