otc_session_callbacks

Session callback functions.

This struct is a set of function pointers to callback functions for events related to an OpenTok session.

All callbacks will not be made on the application or main thread but on an internal thread. The application should return the callback as quickly as possible to avoid blocking the internal thread.

Data passed into a callback function (other than session and user_data) will be released after the callback is called. Make a copy of the data if you need to retain it.

Properties

Name	Type	Description
`user_data`	void *	A pointer to data you set related to the session.
`reserved`	void *	A void pointer to a memory area holding reserved resources used for the internal implementation.

Callbacks

Name	Description
`on_connected(session, user_data)`	Called when the `otc_session_connect` function successfully connects the client to an OpenTok session.
`on_disconnected(session, user_data)`	Called when the client is no longer connected to the OpenTok session.
`on_connection_created(session, user_data, connection)`	Called when a new connection (from another client) is created.
`on_connection_dropped(session, user_data, connection)`	Called when another client's connection to the session is dropped.
`on_stream_received(session, user_data, stream)`	Called when a there is a new stream in this OpenTok session.
`on_stream_dropped(session, user_data, stream)`	Called when another client's stream is dropped from this OpenTok session.
`on_stream_has_audio_changed(session, user_data, stream, has_audio)`	Called when a stream toggles audio on or off.
`on_stream_has_video_changed(session, user_data, stream, has_video)`	Called when a stream toggles video on or off.
`on_stream_has_captions_changed(session, user_data, stream, has_captions)`	Called when a stream toggles captions on or off.
`on_stream_video_dimensions_changed(session, user_data, stream, width, height)`	Called when the video dimensions of a stream in the session change.
`on_stream_video_type_changed(session, user_data, stream, type)`	Called when the video type of a stream in the session changes.
`on_signal_received(session, user_data, type, signal, connection)`	Called when a signal is received in the session.
`on_reconnection_started(session, user_data)`	Called when the local client has lost its connection to the OpenTok session and is trying to reconnect.
`on_reconnected(session, user_data)`	Called when the local client has reconnected to the OpenTok session after its network connection was lost temporarily.
`on_archive_started(session, user_data, archive_id, name)`	Called when an archive of the session starts recording.
`on_archive_stopped(session, user_data, archive_id)`	Called when an archive of the session stops being recorded.
`on_error(session, user_data, error_string, error)`	Called when the session fails.
`on_mute_forced(session, user_data, mute_info)`	Called when a moderator mutes streams in the session or disables the mute state in the session.

on_connected(session, user_data)

Called when the otc_session_connect function successfully connects the client to an OpenTok session.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.

on_disconnected(session, user_data)

Called when the client is no longer connected to the OpenTok session.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.

on_connection_created(session, user_data, connection)

Called when a new connection (from another client) is created.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`connection`	const otc_connection *	The `otc_connection` struct corresponding to the client connecting to the session.

on_connection_dropped(session, user_data, connection)

Called when another client's connection to the session is dropped.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`connection`	const otc_connection *	The `otc_connection` struct corresponding to the client disconnecting from the session.

on_stream_received(session, user_data, stream)

Called when a there is a new stream in this OpenTok session. Call the otc_session_subscribe function to subscribe to the stream.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *	The `otc_stream` struct representing the new stream.

on_stream_dropped(session, user_data, stream)

Called when another client's stream is dropped from this OpenTok session.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *	The `otc_stream` struct representing the stream.

on_stream_has_audio_changed(session, user_data, stream, has_audio)

Called when a stream toggles audio on or off.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *	The `otc_stream` struct representing the new stream.
`has_audio`	otc_bool	Whether the stream now has audio (OTC_TRUE) or not (OTC_FALSE).

on_stream_has_video_changed(session, user_data, stream, has_video)

Called when a stream toggles video on or off.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *	Whether the stream now has video (OTC_TRUE) or not (OTC_FALSE).
`has_video`	otc_bool

on_stream_has_captions_changed(session, user_data, stream, has_captions)

Called when a stream toggles captions on or off.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *	A pointer to the otc_stream struct representing the stream.
`has_captions`	otc_bool	Whether the stream now has captions (OTC_TRUE) or not (OTC_FALSE).

on_stream_video_dimensions_changed(session, user_data, stream, width, height)

Called when the video dimensions of a stream in the session change.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *
`width`	int	The new width of the stream, in pixels.
`height`	int	The new beigbt of the stream, in pixels.

on_stream_video_type_changed(session, user_data, stream, type)

Called when the video type of a stream in the session changes.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`stream`	const otc_stream *
`type`	enum otc_stream_video_type	The new stream type.

on_signal_received(session, user_data, type, signal, connection)

Called when a signal is received in the session. See the Signaling overview documentation.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`type`	const char *	The type string for the signal (if one was provided when the signal was sent).
`signal`	const char *	The data string for the signal (if one was provided when the signal was sent).
`connection`	const otc_connection *	The `otc_connection` representing the client that sent the signal.

on_reconnection_started(session, user_data)

Called when the local client has lost its connection to the OpenTok session and is trying to reconnect.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.

on_reconnected(session, user_data)

Called when the local client has reconnected to the OpenTok session after its network connection was lost temporarily.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.

on_archive_started(session, user_data, archive_id, name)

Called when an archive of the session starts recording. See the Archiving developer guide.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *
`archive_id`	const char *	The archive ID.
`name`	const char *	The name of the archive (if one was provided when the archive was created).

on_archive_stopped(session, user_data, archive_id)

Called when an archive of the session stops being recorded.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`archive_id`	const char *	The archive ID.

on_error(session, user_data, error_string, error)

Called when the session fails.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`error_string`	const char *	The error string.
`error`	enum otc_session_error_code	The error code (of type `otc_session_error_code`).

on_mute_forced(session, user_data, mute_info)

Called when a moderator mutes streams in the session or disables the mute state in the session.

Parameters:

Name	Type	Description
`session`	otc_session *	A pointer to the otc_session struct.
`user_data`	void *	A pointer to the user_data you set for the session.
`mute_info`	otc_on_mute_forced_info *	Check the `active` property of this struct. It is set to `OTC_TRUE` when a moderator has muted audio in the session. It is set to `OTC_FALSE` when a moderator disables the mute audio state in the session.