Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

session.h File Reference

OpenTok Session. More...

#include "capabilities.h"
#include "config.h"
#include "publisher.h"
#include "subscriber.h"
#include "stream.h"

Data Structures

struct  otc_session_capabilities
struct  otc_custom_ice_config
struct  otc_signal_options
struct  otc_session_callbacks

Typedefs

typedef struct otc_session otc_session
typedef struct otc_session_settings otc_session_settings

Enumerations

enum  otc_session_error_code {
  OTC_SESSION_AUTHORIZATION_FAILURE, OTC_SESSION_BLOCKED_COUNTRY, OTC_SESSION_CONNECTION_DROPPED, OTC_SESSION_CONNECTION_FAILED,
  OTC_SESSION_CONNECTION_LIMIT_EXCEEDED, OTC_SESSION_CONNECTION_REFUSED, OTC_SESSION_CONNECTION_TIMED_OUT, OTC_SESSION_FORCE_UNPUBLISH_OR_INVALID_STREAM = 1535,
  OTC_SESSION_ILLEGAL_STATE, OTC_SESSION_INTERNAL_ERROR, OTC_SESSION_INVALID_SESSION, OTC_SESSION_INVALID_SIGNAL_TYPE,
  OTC_SESSION_NOT_CONNECTED, OTC_SESSION_NO_MESSAGING_SERVER, OTC_SESSION_NULL_OR_INVALID_PARAMETER, OTC_SESSION_PUBLISHER_NOT_FOUND,
  OTC_SESSION_SIGNAL_DATA_TOO_LONG, OTC_SESSION_SIGNAL_TYPE_TOO_LONG, OTC_SESSION_STATE_FAILED = 1020, OTC_SESSION_SUBSCRIBER_NOT_FOUND,
  OTC_SESSION_UNEXPECTED_GET_SESSION_INFO_REPONSE
}

Functions

otc_sessionotc_session_new (const char *apikey, const char *session_id, const struct otc_session_callbacks *callbacks)
otc_session_settingsotc_session_settings_new ()
otc_status otc_session_settings_set_connection_events_suppressed (otc_session_settings *settings, otc_bool suppress)
otc_status otc_session_settings_set_custom_ice_config (otc_session_settings *settings, const struct otc_custom_ice_config *custom_ice_config)
otc_status otc_session_settings_set_proxy_url (otc_session_settings *settings, const char *proxy_url)
otc_status otc_session_settings_set_ip_whitelist (otc_session_settings *settings, otc_bool ip_whitelist)
otc_status otc_session_settings_delete (otc_session_settings *settings)
otc_sessionotc_session_new_with_settings (const char *apikey, const char *session_id, const struct otc_session_callbacks *callbacks, otc_session_settings *settings)
otc_status otc_session_delete (otc_session *session)
otc_status otc_session_connect (otc_session *session, const char *token)
otc_status otc_session_disconnect (otc_session *session)
otc_status otc_session_publish (otc_session *session, otc_publisher *publisher)
otc_status otc_session_unpublish (otc_session *session, otc_publisher *publisher)
otc_status otc_session_subscribe (otc_session *session, otc_subscriber *subscriber)
otc_status otc_session_unsubscribe (otc_session *session, otc_subscriber *subscriber)
otc_status otc_session_send_signal (otc_session *session, const char *type, const char *signal)
otc_status otc_session_send_signal_to_connection (otc_session *session, const char *type, const char *signal, const otc_connection *connection)
otc_status otc_session_send_signal_with_options (otc_session *session, const char *type, const char *signal, struct otc_signal_options signal_options)
otc_status otc_session_send_signal_to_connection_with_options (otc_session *session, const char *type, const char *signal, const otc_connection *connection, struct otc_signal_options signal_options)
otc_status otc_session_report_issue (struct otc_session *session, const char *issue_description, char **issue_id)
char * otc_session_get_id (const otc_session *session)
otc_connectionotc_session_get_connection (const otc_session *session)
struct otc_session_capabilities otc_session_get_capabilities (const otc_session *session)
void * otc_session_get_user_data (const otc_session *session)

Detailed Description

OpenTok Session.

This file includes the type definition for an OpenTok session along with several function declarations useful when dealing with a session.

Typedef Documentation

◆ otc_session

typedef struct otc_session otc_session

OpenTok session type definition.

◆ otc_session_settings

OpenTok session settings type definition.

Enumeration Type Documentation

◆ otc_session_error_code

Error code enumeration for OpenTok sessions.

This enumeration represents several error codes associated with a session.

Enumerator
OTC_SESSION_AUTHORIZATION_FAILURE 

An invalid API key or token was provided.

OTC_SESSION_BLOCKED_COUNTRY 

Unable to connect to the session. Terms of service violation: export compliance.

OTC_SESSION_CONNECTION_DROPPED 

The connection to the OpenTok messaging server was dropped.

OTC_SESSION_CONNECTION_FAILED 

Connecting to the session failed.

OTC_SESSION_CONNECTION_LIMIT_EXCEEDED 

The client tried to connect to a session that has exceeded the limit for simultaneous connections.

OTC_SESSION_CONNECTION_REFUSED 

A socket could not be opened to the messaging server. Check that outbound ports 443 and 8080 are accessible.

OTC_SESSION_CONNECTION_TIMED_OUT 

The connection timed out while attempting to connect to the session

OTC_SESSION_FORCE_UNPUBLISH_OR_INVALID_STREAM 

Invalid stream.

OTC_SESSION_ILLEGAL_STATE 

A method has been invoked at an illegal or inappropriate time for this session. For example, attempting to connect an already connected session will return this error.

OTC_SESSION_INTERNAL_ERROR 

Thread dispatch failure, out of memory, parse error, etc.

OTC_SESSION_INVALID_SESSION 

An invalid session ID was provided.

OTC_SESSION_INVALID_SIGNAL_TYPE 

You attempted to send a signal with an invalid type.

OTC_SESSION_NOT_CONNECTED 

The session is not connected, and the requested action requires an active session connection.

OTC_SESSION_NO_MESSAGING_SERVER 

No messaging server is available for this session.

OTC_SESSION_NULL_OR_INVALID_PARAMETER 

A parameter passed in is null or invalid.

OTC_SESSION_PUBLISHER_NOT_FOUND 

The publisher is unknown to this session. This is usually the result of attempting to unpublish a publisher that is not associated with the session.

OTC_SESSION_SIGNAL_DATA_TOO_LONG 

You attempted to send a signal with a data string that is greater than the maximum length (8KB).

OTC_SESSION_SIGNAL_TYPE_TOO_LONG 

You attempted to send a signal with a type string that is greater than the maximum length.

OTC_SESSION_STATE_FAILED 

The connection timed out while attempting to get the session’s state.

OTC_SESSION_SUBSCRIBER_NOT_FOUND 

The subscriber is unknown to this session. This is usually the result of attempting to unsubscribe a subscriber that is not associated with the session.

OTC_SESSION_UNEXPECTED_GET_SESSION_INFO_REPONSE 

Unexpected response.

Function Documentation

◆ otc_session_connect()

otc_status otc_session_connect ( otc_session session,
const char *  token 
)

Connects the client to an OpenTok session.

Parameters
sessionThe otc_session struct representing the OpenTok session to connect to.
tokenThe client token for connecting to the session. See Token Creation Overview.
Returns
Return value indicating either error or success.

◆ otc_session_delete()

otc_status otc_session_delete ( otc_session session)

Releases resources associated with the session.

Parameters
sessionThe otc_session instance.

◆ otc_session_disconnect()

otc_status otc_session_disconnect ( otc_session session)

Disconnects the client from this session. All of the client's subscribers and publishers will also be will be disconnected from the session.

Parameters
sessionThe otc_session struct representing the OpenTok session to disconnect from.
Returns
Return value indicating either error or success.

◆ otc_session_get_capabilities()

struct otc_session_capabilities otc_session_get_capabilities ( const otc_session session)

Gets the capabilities of the client connecxted to the session. All otc_session_capabilities members are undefined until otc_session_callbacks.on_connected has been called.

Parameters
sessionThe otc_session struct representing the OpenTok session.
Returns
The otc_session_capabilities instance.

◆ otc_session_get_connection()

otc_connection* otc_session_get_connection ( const otc_session session)

Gets the connection object associated with this session.

Parameters
sessionThe otc_session struct representing the OpenTok session.
Returns
The otc_connection instance.

◆ otc_session_get_id()

char* otc_session_get_id ( const otc_session session)

Gets the unique session ID for this session.

◆ otc_session_get_user_data()

void* otc_session_get_user_data ( const otc_session session)

Gets the user data associated with the session. See otc_session_callbacks.user_data.

Parameters
sessionThe otc_session struct representing the OpenTok session.
Returns
A pointer to the user data.

◆ otc_session_new()

otc_session* otc_session_new ( const char *  apikey,
const char *  session_id,
const struct otc_session_callbacks callbacks 
)

Creates a new otc_session struct instance. Pass this into the otc_session_connect function to connect to the OpenTok session.

See also otc_session_new_with_settings for initializing a otc_session struct with advanced options.

Parameters
apikeyThe API key for the OpenTok project. See See the your TokBox account page.
session_idThe session ID.
callbacksThe otc_session_callbacks structure containing callback functions for events related to the session.
Returns
The otc_session struct, representing the OpenTok session.

◆ otc_session_new_with_settings()

otc_session* otc_session_new_with_settings ( const char *  apikey,
const char *  session_id,
const struct otc_session_callbacks callbacks,
otc_session_settings settings 
)

Creates a new OpenTok session with advanced settings. These include settings for suppressing connection events, custom TURN servers, the IP proxy feature, and the IP whitelist feature.

Parameters
apikeyThe API key for the OpenTok project. See See the your TokBox account page.
session_idThe session ID.
callbacksThe otc_session_callbacks structure containing callback functions for events related to the session.
settingsThe otc_session_settings struct With advanced settings for the session.
Returns
The struct, representing the OpenTok session.
See also
otc_session_new.

◆ otc_session_publish()

otc_status otc_session_publish ( otc_session session,
otc_publisher publisher 
)

Starts a publisher streaming to the session.

Parameters
sessionThe otc_session struct representing the OpenTok session to publish to.
publisherThe otc_publisher struct representing the publisher.
Returns
Return value indicating either error or success.

◆ otc_session_report_issue()

otc_status otc_session_report_issue ( struct otc_session session,
const char *  issue_description,
char **  issue_id 
)

Report that your app experienced an issue. You can use the issue ID with the Inspector tool or when discussing an issue with the Vonage Video API support team.

Parameters
sessionThe otc_session struct representing the OpenTok session.
issue_descriptionA description string.
issue_idA pointer to a string that will be set the unique identifier for the reported issue.
Returns
Return value indicating either error or success.

◆ otc_session_send_signal()

otc_status otc_session_send_signal ( otc_session session,
const char *  type,
const char *  signal 
)

Sends a signal to all clients connected to the session. See otc_session_send_signal_with_options, otc_session_send_signal_to_connection, and otc_session_send_signal_to_connection_with_options. Also see the Signaling overview.

Parameters
sessionThe otc_session struct representing the OpenTok session.
typeThe optional type string value for the signal.
signalThe optional data string value for the signal.
Returns
Return value indicating either error or success.

◆ otc_session_send_signal_to_connection()

otc_status otc_session_send_signal_to_connection ( otc_session session,
const char *  type,
const char *  signal,
const otc_connection connection 
)

Sends a signal to a specific client connected to the session. See otc_session_send_signal_to_connection_with_options, otc_session_send_signal, and {}. Also see the Signaling overview.

Parameters
sessionThe otc_session struct representing the OpenTok session.
typeThe optional type string value for the signal.
signalThe optional data string value for the signal.
connectionThe otc_connection struct corresponding to the client to receive the signal.
Returns
Return value indicating either error or success.

◆ otc_session_send_signal_to_connection_with_options()

otc_status otc_session_send_signal_to_connection_with_options ( otc_session session,
const char *  type,
const char *  signal,
const otc_connection connection,
struct otc_signal_options  signal_options 
)

Sends a signal to a specific client, with specified options. See otc_session_send_signal, {}, and { otc_session_send_signal_with_options}. Also see the Signaling overview.

Parameters
sessionThe otc_session struct representing the OpenTok session.
typeThe optional type string value for the signal.
signalThe optional data string value for the signal.
connectionThe otc_connection struct corresponding to the client to receive the signal.
signal_optionsThe otc_signal_options struct with options for the signal.
Returns
Return value indicating either error or success.

◆ otc_session_send_signal_with_options()

otc_status otc_session_send_signal_with_options ( otc_session session,
const char *  type,
const char *  signal,
struct otc_signal_options  signal_options 
)

Sends a signal to all clients connected to the session, with specified options. See otc_session_send_signal, {}, and { otc_session_send_signal_to_connection_with_options}. Also see the Signaling overview.

Parameters
sessionThe otc_session struct representing the OpenTok session.
typeThe optional type string value for the signal.
signalThe optional data string value for the signal.
signal_optionsThe otc_signal_options struct with options for the signal.
Returns
Return value indicating either error or success.

◆ otc_session_settings_delete()

otc_status otc_session_settings_delete ( otc_session_settings settings)

Deletes an otc_session_settings instance.

◆ otc_session_settings_new()

otc_session_settings* otc_session_settings_new ( )

Creates a new otc_session_settings instance, used to set up advanced session settings. Call the following functions to configure these settings before calling the otc_session_new_with_settings function to create a session with these settings:

◆ otc_session_settings_set_connection_events_suppressed()

otc_status otc_session_settings_set_connection_events_suppressed ( otc_session_settings settings,
otc_bool  suppress 
)

Prevent connection events, to support large interactive video sessions. This prevents otc_session_callbacks.on_connection_created and otc_session_callbacks.on_connection_dropped callback functions from being invoked when other clients connect to or disconnect from the session. (Also, the OpenTok server does not send these events to the client.) For more information, see Suppressing connection events in the OpenTok developer guides.

◆ otc_session_settings_set_custom_ice_config()

otc_status otc_session_settings_set_custom_ice_config ( otc_session_settings settings,
const struct otc_custom_ice_config custom_ice_config 
)

Enables custom ICE sever configuration. This is part of the configurable TURN feature.

◆ otc_session_settings_set_ip_whitelist()

otc_status otc_session_settings_set_ip_whitelist ( otc_session_settings settings,
otc_bool  ip_whitelist 
)

Pass in OTC_TRUE to have the client use the IP address white list. This feature is available as an add-on feature for Enterprise partners.

◆ otc_session_settings_set_proxy_url()

otc_status otc_session_settings_set_proxy_url ( otc_session_settings settings,
const char *  proxy_url 
)

Sets the IP proxy URL. See the IP Proxy developer guide.

◆ otc_session_subscribe()

otc_status otc_session_subscribe ( otc_session session,
otc_subscriber subscriber 
)

Starts subscribing to (receiving a stream for) a subscriber's audio-video stream in this session.

Parameters
sessionThe otc_session struct representing the OpenTok session containing the subscriber's stream.
subscriberThe otc_subscriber struct representing the subscriber.
Returns
Return value indicating either error or success.

◆ otc_session_unpublish()

otc_status otc_session_unpublish ( otc_session session,
otc_publisher publisher 
)

Causes a publisher from a session (causing its stream to stop).

Parameters
sessionThe otc_session struct representing the OpenTok session to unpublish from.
publisherThe otc_publisher struct representing the publisher.
Returns
Return value indicating either error or success.

◆ otc_session_unsubscribe()

otc_status otc_session_unsubscribe ( otc_session session,
otc_subscriber subscriber 
)

Stops subscribing to (receiving a stream for) a specified subscriber in the session.

Parameters
sessionThe otc_session struct representing the OpenTok session containing the subscriber's stream.
subscriberThe otc_subscriber struct representing the subscriber.
Returns
Return value indicating either error or success.