Cómo unirse a una sesión — macOS

Utilizando un ID de sesión y ficha, puedes conectarte a la sesión de OpenTok utilizando el SDK de OpenTok para macOS.

Este tema incluye las siguientes secciones:

Creación de una instancia de `otc_session` y funciones de devolución de llamada relacionadas con la sesión

Crear una estructura de tipo otc_session_callbacks, y punteros a funciones que apuntan a miembros de funciones de devolución de llamada. Por ejemplo:


char *session_user_data = strdup("Session user data");

static void on_session_connected(otc_session *session, void *user_data) {
  // You could publish a stream once you connect to the session.
}

static void on_session_stream_received(otc_session *session,
                                       void *user_data,
                                       const otc_stream *stream) {
  // You could call otc_subscriber_new() to subscribe to this stream
	// in response to this event.
}

static void on_session_stream_dropped(otc_session *session,
                                      void *user_data,
                                      const otc_stream *stream) {
  // If you have subscribed to this stream, you should
  // call otc_subscriber_delete() to delete the subscriber in response to this event.
}

static void on_disconnected(otc_session *session, void *user_data) {
  // Handle the on_disconnected event.
}

static void on_session_error(otc_session *session,
                             void *user_data,
                             const char *error_string,
                             enum otc_session_error_code error) {
  // Handle the error.
}

struct otc_session_callbacks session_callbacks = {0};
session_callbacks.user_data = session_user_data;
session_callbacks.on_connected = on_session_connected;
session_callbacks.on_stream_received = on_session_stream_received;
session_callbacks.on_stream_dropped = on_session_stream_dropped;
session_callbacks.on_disconnected = on_session_disconnected;
session_callbacks.on_error = on_session_error;

Utiliza el user_data miembro de la otc_session_callbacks estructura para almacenar datos a los que quizá quieras hacer referencia en las funciones de llamada de retorno. En este ejemplo, la definimos como un puntero a un objeto de cadena. Pero podría ser un puntero a una instancia de algún otro tipo que contenga información relevante.

Los demás miembros de la otc_session_callbacks La estructura está formada por funciones de devolución de llamada que se activan cuando se producen eventos relacionados con la sesión de OpenTok. El ejemplo anterior incluye funciones de devolución de llamada para lo siguiente:

on_connected -- Se invoca cuando el otc_session_connect() La función (véase más abajo) conecta correctamente la instancia a una sesión de OpenTok.
on_stream_received -- Se invoca cuando hay una nueva transmisión en la sesión de OpenTok (cuando otro cliente publica una transmisión en la sesión).
on_stream_dropped -- Se invoca cuando la transmisión de otro cliente se desconecta de la sesión de OpenTok. Esto puede ocurrir cuando el cliente deja de publicar la transmisión o si se interrumpe la conexión de red del cliente.
on_disconnected -- Se invoca cuando la aplicación se desconecta de la sesión de OpenTok (véase más abajo).
on_error -- Se invoca cuando se produce un error al conectarse a la sesión. Esta función incluye parámetros para una cadena de error y un código de error que viene definido por el otc_session_error_code enum.

Ninguna de las llamadas de retorno se realizará en el hilo de la aplicación ni en el hilo principal, sino en un hilo interno. La aplicación debe devolver la llamada de retorno lo antes posible para evitar bloquear el hilo interno.

Véase otc_session_callbacks Consulta la documentación de referencia del SDK de OpenTok para macOS para obtener más detalles sobre cada una de las funciones de devolución de llamada.

Tras inicializar el otc_session_callbacks llame a la estructura otc_session_new() función, pasando como parámetros la cadena de tu clave API de OpenTok, la cadena del ID de sesión de OpenTok y un puntero al otc_session_callbacks estructura:

otc_session *session = NULL;
session = otc_session_new(API_KEY, SESSION_ID, &session_callbacks);

El otc_session_new() La función devuelve un otc_session estructura, que representa una sesión de OpenTok.

Para utilizar la configuración avanzada de la sesión, llame al otc_session_new_with_settings(), en lugar del otc_session_new() función. Esta función toma un settings parámetro que es un puntero a un otc_session_settings struct que define los ajustes avanzados. Por ejemplo, el siguiente código utiliza el otc_session_settings_new () función para crear una instancia de un otc_session_settings estructuras y llamadas otc_session_settings_set_connection_events_suppressed(OTC_TRUE) para que el SDK omita los eventos de conexión, con el fin de permitir sesiones de vídeo interactivo de gran tamaño. A continuación, pasa el otc_session_settings struct en el otc_session_new_with_settings() función:

// Populate the session_callbacks struct, as in the previous example. Then...

otc_session_settings *session_settings = otc_session_settings_new();
otc_session_settings_set_connection_events_suppressed(session_settings, OTC_TRUE);
otc_session *session = otc_session_new_with_settings(API_KEY,
                                                     SESSION_ID,
                                                     &session_callbacks,
                                                     session_settings);

Además de otc_session_settings_set_connection_events_suppressed(), las siguientes funciones te permiten configurar opciones avanzadas para una sesión:

otc_session_settings_set_custom_ice_config() — Permite configurar el servidor ICE a medida. Esto forma parte del función TURN configurable.
otc_session_settings_set_ip_whitelist() — Esto respalda la función de dirección IP permitida disponible como un funcionalidad adicional.
otc_session_settings_set_proxy_url() — Establece una URL de proxy IP. Consulta el Guía del desarrollador del proxy IP.

Conectarse a una sesión

Una vez creadas las instancias de sesión y de editor, llama a la función otc_session_connect() función:

  otc_session_connect(session, TOKEN);

Esta función conecta al cliente a la sesión de OpenTok. Admite dos argumentos:

El otc_session instancia de estructura.
La cadena del token de OpenTok.

Una vez establecida la conexión, el on_connected función de devolución de llamada de la otc_session_callbacks struct. En caso de error, el on_error función de llamada de retorno de la otc_session_callbacks struct.

Desconectarse de una sesión

Para desconectarte de una sesión, llama al otc_session_disconnect() función:

otc_session_disconnect(session);

Si no vas a volver a conectarte a la sesión, deberías llamar al otc_session_delete() y otc_destroy() funciones:

otc_session_delete(session);
session = NULL;

otc_destroy();

Detectar cuándo te has desconectado

Cuando el cliente se desconecta de la sesión OpenTok, el on_disconnected función de devolución de llamada de la otc_session_callbacks struct.

Reconexión automática

Los clientes intentarán volver a conectarse automáticamente a una sesión de la que se hayan desconectado de forma inesperada (por ejemplo, debido a una interrupción de la conexión de red). No es necesario añadir ningún código para que los clientes se vuelvan a conectar automáticamente, a menos que quieras responder a los eventos que se producen cuando tu cliente se desconecta y vuelve a conectarse.

Cuando se interrumpe la conexión y el cliente intenta volver a conectarse, la función on_reconnection_started función de devolución de llamada de la otc_session_callbacks Se llama a la estructura. Cuando se restablece la conexión, la on_reconnected función de devolución de llamada de la otc_session_callbacks Se invoca la función `struct`. Si el cliente no puede restablecer la conexión, se desconecta de la sesión de OpenTok, y el on_disconnected función de devolución de llamada de la otc_session_callbacks struct.

En respuesta a estos eventos, tu aplicación puede (opcionalmente) mostrar notificaciones en la interfaz de usuario que indiquen los estados de desconexión temporal, reconexión y desconexión.

Cuando otro cliente se desconecta temporalmente de una sesión, el on_disconnected función de devolución de llamada de la otc_subscriber_callbacks Se invoca la estructura para que un suscriptor de una secuencia publicada por ese cliente. La on_reconnected función de devolución de llamada de la otc_subscriber_callbacks La estructura del suscriptor se invoca cuando (y si) el cliente se vuelve a conectar y el flujo se reanuda automáticamente. Para obtener más información, consulta el Reconexión automática sección de la guía para desarrolladores titulada «Suscribirse a flujos».

De forma predeterminada, cualquier señal que envíes mientras tu cliente esté temporalmente desconectado de una sesión se pone en cola y se envía cuando (y si) te vuelves a conectar correctamente. Para evitar que las señales se pongan en cola mientras estás desconectado, puedes utilizar la otc_session_send_signal_with_options() función o el otc_session_send_signal_to_connection_with_options () función y configura el retryAfterReconnect miembro a false en el otc_signal_options que pasas a la función. Para obtener más información, consulta Evitar que se envíen señales durante la reconexión automática.

Detección de la conexión y desconexión de otros clientes

Una vez que se haya conectado a una sesión, el on_connection_created función de devolución de llamada de la otc_session_callbacks La función `struct` se invoca cuando un nuevo cliente (que no sea el tuyo) se conecta a la sesión. La connection El parámetro de esa función es un puntero a una instancia de un otc_connection struct correspondiente al cliente que se conecta a la sesión.

El on_connection_dropped función de devolución de llamada de la otc_session_callbacks struct se invoca cuando un cliente (que no sea el tuyo) se desconecta de la sesión. El connection El parámetro de esa función es un puntero a la otc_connection struct correspondiente a la desconexión del cliente de la sesión.