Participar de uma sessão — macOS

Usando um ID da sessão e token, você pode se conectar à sessão do OpenTok usando o SDK do OpenTok para macOS.

Este tópico inclui as seguintes seções:

Criação de uma instância de `otc_session` e callbacks relacionados à sessão

Crie uma estrutura do tipo otc_session_callbacks, e ponteiros de função para membros de função de retorno de chamada. Por exemplo:


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;

Use o user_data membro do otc_session_callbacks estrutura para definir dados que você possa querer consultar nas funções de retorno de chamada. Neste exemplo, definimos isso como um ponteiro para um objeto de string. Mas poderia ser um ponteiro para uma instância de algum outro tipo que contenha informações significativas.

Os demais membros do otc_session_callbacks Essa estrutura consiste em funções de retorno de chamada que são chamadas quando ocorrem eventos relacionados à sessão do OpenTok. O exemplo anterior inclui funções de retorno de chamada para o seguinte:

  • on_connected -- É chamado quando o otc_session_connect() função (veja abaixo) conecta com sucesso a instância a uma sessão do OpenTok.

  • on_stream_received -- É chamado quando há um novo stream na sessão do OpenTok (quando outro cliente publica um stream na sessão).

  • on_stream_dropped -- É chamado quando o stream de outro cliente é removido da sessão do OpenTok. Isso pode ocorrer quando o cliente para de publicar o stream ou se a conexão de rede do cliente for interrompida.

  • on_disconnected -- É chamado quando o aplicativo se desconecta da sessão do OpenTok (veja abaixo).

  • on_error -- É chamada quando ocorre um erro ao se conectar à sessão. Essa função inclui parâmetros para uma string de erro e um código de erro que é definido pelo otc_session_error_code enum.

Todas as chamadas de retorno não serão executadas na thread do aplicativo ou na thread principal, mas em uma thread interna. O aplicativo deve retornar a chamada de retorno o mais rápido possível para evitar o bloqueio da thread interna.

Veja otc_session_callbacks Consulte a documentação de referência do SDK do OpenTok para macOS para obter detalhes sobre cada uma das funções de retorno de chamada.

Após inicializar o otc_session_callbacks estrutura, chame o otc_session_new() função, passando a string da sua chave da API do OpenTok, a string do ID da sessão do OpenTok, e um ponteiro para o otc_session_callbacks estrutura:

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

O otc_session_new() A função retorna um otc_session estrutura, que representa uma sessão do OpenTok.

Para usar configurações avançadas de sessão, chame a função otc_session_new_with_settings(), em vez do otc_session_new() função. Essa função recebe um settings parâmetro que é um ponteiro para um otc_session_settings struct que define as configurações avançadas. Por exemplo, o código a seguir utiliza o otc_session_settings_new () função para instanciar um otc_session_settings estruturas e chamadas otc_session_settings_set_connection_events_suppressed(OTC_TRUE) para fazer com que o SDK suprime eventos de conexão, a fim de dar suporte a grandes sessões de vídeo interativas. Em seguida, ele passa o otc_session_settings struct na otc_session_new_with_settings() função:

// 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);

Além de otc_session_settings_set_connection_events_suppressed(), as seguintes funções permitem definir configurações avançadas para uma sessão:

Conectando-se a uma sessão

Após criar as instâncias da sessão e do editor, chame o otc_session_connect() função:

  otc_session_connect(session, TOKEN);

Esta função conecta o cliente à sessão do OpenTok. Ela recebe dois argumentos:

  • O otc_session instância da estrutura.

  • A sequência do token do OpenTok.

Após estabelecer a conexão com sucesso, o on_connected função de retorno de chamada do otc_session_callbacks A estrutura é chamada. Em caso de erro, a on_error função de retorno de chamada do otc_session_callbacks a estrutura é chamada.

Desconectando-se de uma sessão

Para se desconectar de uma sessão, ligue para o otc_session_disconnect() função:

otc_session_disconnect(session);

Caso você não pretenda se reconectar à sessão, deve ligar para o otc_session_delete() e otc_destroy() funções:

otc_session_delete(session);
session = NULL;

otc_destroy();

Detectar quando a conexão foi interrompida

Quando o cliente se desconecta da sessão do OpenTok, o on_disconnected função de retorno de chamada do otc_session_callbacks a estrutura é chamada.

Reconexão automática

Os clientes tentarão se reconectar automaticamente a uma sessão da qual tenham se desconectado inesperadamente (por exemplo, devido a uma queda na conectividade de rede). Você não precisa adicionar nenhum código para que os clientes se reconectem automaticamente, a menos que queira responder a eventos que ocorram quando o cliente se desconectar e se reconectar.

Quando a conexão é interrompida e o cliente tenta se reconectar, o on_reconnection_started função de retorno de chamada do otc_session_callbacks a estrutura é chamada. Quando a conexão é restabelecida, a on_reconnected função de retorno de chamada do otc_session_callbacks A função `struct` é chamada. Se o cliente não conseguir restabelecer a conexão, ele se desconecta da sessão do OpenTok, e o on_disconnected função de retorno de chamada do otc_session_callbacks a estrutura é chamada.

Em resposta a esses eventos, seu aplicativo pode (opcionalmente) exibir notificações na interface do usuário indicando os estados de desconexão temporária, reconexão e desconexão.

Quando outro cliente se desconecta temporariamente de uma sessão, o on_disconnected função de retorno de chamada do otc_subscriber_callbacks é chamada a estrutura para um assinante de um fluxo publicado por esse cliente. A on_reconnected função de retorno de chamada do otc_subscriber_callbacks A estrutura para o assinante é chamada quando (e se) o cliente se reconectar e o fluxo for retomado automaticamente. Para obter mais informações, consulte o Reconexão automática seção do guia do desenvolvedor intitulada “Inscrição em streams”.

Por padrão, quaisquer sinais que você enviar enquanto seu cliente estiver temporariamente desconectado de uma sessão são colocados em fila e enviados quando (e se) você se reconectar com sucesso. Para evitar que os sinais sejam colocados em fila enquanto você estiver desconectado, você pode usar o otc_session_send_signal_with_options() função ou o otc_session_send_signal_to_connection_with_options () função e definir o retryAfterReconnect membro de false no otc_signal_options que você passa para a função. Para obter mais informações, consulte Impedir que sinais sejam enviados durante a reconexão automática.

Detectar quando outros clientes se conectaram e se desconectaram

Depois de se conectar a uma sessão, o on_connection_created função de retorno de chamada do otc_session_callbacks A função `struct` é chamada quando um novo cliente (que não seja o seu) se conecta à sessão. A connection O parâmetro dessa função é um ponteiro para uma instância de um otc_connection estrutura correspondente ao cliente que está se conectando à sessão.

O on_connection_dropped função de retorno de chamada do otc_session_callbacks struct é chamada quando um cliente (que não seja o seu) se desconecta da sessão. A connection O parâmetro dessa função é um ponteiro para o otc_connection struct correspondente ao desligamento do cliente da sessão.