Signaling

Use the Vonage Video signaling API to send text and data between clients connected to a session.

For conceptual information on the API, see the Signaling overview developer guide.

This topic includes the following sections:

• Sending a Signal to a Specific Client in a Session
• Sending a Signal to All Clients in a Session
• Receiving Signals in a Session
• Preventing Signals From Being Sent During Automatic Reconnection

Sending a Signal to a Specific Client in a Session

To send a signal to a specific client in a session, call the otc_session_send_signal_to_connection() function:

The type parameter is a string value that clients can filter on when listening for signals. Set this to an empty string if you do not need to set a type.

The signal parameter specifies the data payload (a string) you send with the message. The limit to the size of data is 8KB.

The connection parameter is a pointer to an otc_connection struct corresponding to a client connected to the session that you want to signal. You obtain references to otc_connection structs in the connection parameter of the on_connection_created callback function of the otc_session_callbacks instance .

Sending a Signal to All Clients in a Session

To send a signal to a all clients in a session, call the otc_session_send_signal() function:

The type parameter is a string value that clients can filter on when listening for signals. Set this to an empty string if you do not need to set a type.

The signal parameter specifies the data payload (a string) you send with the message. The limit to the size of data is 8KB.

Receiving Signals in a Session

The on_signal_received() callback function of the otc_session_callbacks struct is called when a signal is received in a session. It includes the following parameters:

• session — A pointer to the otc_session instance.
• user_data — A pointer to the user data.
• type — A pointer to the type string for the signal.
• signal — A pointer to the data string for the signal.
• connection — A pointer to the otc_connection instance identifying the client that sent the signal.

Note that you can use a REST API call to send a signal from your server, instead of from a client connected to the session. In this case, the connection parameter of the on_signal_received() is set to null.

Preventing Signals From Being Sent During Automatic Reconnection

Clients will attempt to automatically reconnect to a session they disconnect unexpectedly (for example, due to a drop in network connectivity).

By default, any signals you send while the client is temporarily disconnected from a session are queued and sent when (and if) it successfully reconnects.

You can set the retryAfterReconnect) member of the otc_signal_options struct that you pass into the otc_session_send_signal_with_options() function or the otc_session_send_signal_to_connection_with_options() function to false to prevent signals from being queued while the client is disconnected.

For more information, see Automatic reconnection.