Rejoindre une session — macOS

En utilisant un ID de la session et jeton, vous pouvez vous connecter à la session OpenTok à l'aide du SDK OpenTok pour macOS.

Cette rubrique comprend les sections suivantes :

Instanciation d'une instance otc_session et rappels liés à la session

Créer une structure de type otc_session_callbacks, ainsi que des pointeurs de fonction vers des membres de fonction de rappel. Par exemple :


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;

Utiliser le user_data membre de la otc_session_callbacks structure permettant de définir les données auxquelles vous souhaiterez peut-être faire référence dans les fonctions de rappel. Dans cet exemple, nous l'avons définie comme un pointeur vers un objet chaîne de caractères. Mais il pourrait s'agir d'un pointeur vers une instance d'un autre type contenant des informations pertinentes.

Les autres membres de la otc_session_callbacks Cette structure est constituée de fonctions de rappel qui sont appelées lorsque des événements liés à la session OpenTok se produisent. L'exemple précédent comprend des fonctions de rappel pour les éléments suivants :

  • on_connected -- Appelé lorsque le otc_session_connect() La fonction (voir ci-dessous) permet de connecter correctement l'instance à une session OpenTok.

  • on_stream_received -- Appelé lorsqu'un nouveau flux apparaît dans la session OpenTok (lorsqu'un autre client publie un flux dans la session).

  • on_stream_dropped -- Appelé lorsqu'un flux provenant d'un autre client est supprimé de la session OpenTok. Cela peut se produire lorsque le client cesse de diffuser le flux ou en cas de coupure de sa connexion réseau.

  • on_disconnected -- Appelée lorsque l'application se déconnecte de la session OpenTok (voir ci-dessous).

  • on_error -- Appelée lorsqu'une erreur survient lors de la connexion à la session. Cette fonction comporte des paramètres pour une chaîne d'erreur et un code d'erreur défini par la otc_session_error_code enum.

Aucun rappel ne sera effectué sur le thread de l'application ou le thread principal, mais sur un thread interne. L'application doit renvoyer la réponse au rappel aussi rapidement que possible afin d'éviter de bloquer le thread interne.

Voir otc_session_callbacks Consultez la documentation de référence du SDK OpenTok pour macOS pour plus de détails sur chacune des fonctions de rappel.

Après avoir initialisé le otc_session_callbacks appeler la structure otc_session_new() fonction, en lui transmettant votre chaîne de caractères correspondant à la clé API OpenTok, la chaîne de caractères correspondant à l'identifiant de session OpenTok, ainsi qu'un pointeur vers le otc_session_callbacks structure :

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

Les otc_session_new() La fonction renvoie un otc_session structure, qui représente une session OpenTok.

Pour utiliser les paramètres avancés de la session, appelez le otc_session_new_with_settings(), au lieu de la otc_session_new() fonction. Cette fonction prend un settings qui est un pointeur sur un otc_session_settings struct qui définit les paramètres avancés. Par exemple, le code suivant utilise la otc_session_settings_new () fonction permettant d'instancier un otc_session_settings struct et appels otc_session_settings_set_connection_events_suppressed(OTC_TRUE) pour que le SDK ignore les événements de connexion, afin de prendre en charge les sessions vidéo interactives de grande envergure. Il transmet ensuite le otc_session_settings struct dans le otc_session_new_with_settings() fonction :

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

En plus de otc_session_settings_set_connection_events_suppressed(), les fonctions suivantes vous permettent de définir des paramètres avancés pour une session :

Connexion à une session

Après avoir créé les instances de session et d'éditeur, appelez la méthode otc_session_connect() fonction :

  otc_session_connect(session, TOKEN);

Cette fonction connecte le client à la session OpenTok. Elle prend deux arguments :

  • Les otc_session exemple de structure.

  • La chaîne de caractères du jeton OpenTok.

Une fois la connexion réussie, le on_connected fonction de rappel de la otc_session_callbacks est appelée. En cas d'erreur, la on_error fonction de rappel de la otc_session_callbacks struct est appelé.

Déconnexion d'une session

Pour se déconnecter d'une session, appelez le otc_session_disconnect() fonction :

otc_session_disconnect(session);

Si vous ne comptez pas vous reconnecter à la session, vous devez appeler le otc_session_delete() et otc_destroy() fonctions :

otc_session_delete(session);
session = NULL;

otc_destroy();

Détection de la déconnexion

Lorsque le client se déconnecte de la session OpenTok, la fonction on_disconnected fonction de rappel de la otc_session_callbacks struct est appelé.

Reconnexion automatique

Les clients tenteront de se reconnecter automatiquement à une session dont ils se sont déconnectés de manière inattendue (par exemple, en raison d'une interruption de la connexion réseau). Vous n'avez pas besoin d'ajouter de code pour que les clients se reconnectent automatiquement, sauf si vous souhaitez réagir aux événements qui se produisent lorsque votre client se déconnecte puis se reconnecte.

Lorsque la connexion est interrompue et que le client tente de se reconnecter, la fonction on_reconnection_started fonction de rappel de la otc_session_callbacks La structure est appelée. Lorsque la connexion est rétablie, la on_reconnected de la fonction de rappel du otc_session_callbacks La fonction `struct` est appelée. Si le client ne parvient pas à rétablir la connexion, il se déconnecte de la session OpenTok, et le on_disconnected de la fonction de rappel du otc_session_callbacks struct est appelé.

En réponse à ces événements, votre application peut (si vous le souhaitez) afficher des notifications dans l'interface utilisateur indiquant les états de déconnexion temporaire, de reconnexion et de déconnexion.

Lorsqu'un autre client se déconnecte temporairement d'une session, le on_disconnected fonction de rappel de la otc_subscriber_callbacks struct permettant à un abonné d'accéder à un flux publié par ce client est appelée. La on_reconnected fonction de rappel de la otc_subscriber_callbacks La structure de l'abonné est appelée lorsque (et si) le client se reconnecte et que le flux reprend automatiquement. Pour plus d'informations, consultez la Reconnexion automatique section du guide du développeur intitulée « S'abonner à des flux ».

Par défaut, tous les signaux que vous envoyez lorsque votre client est temporairement déconnecté d'une session sont mis en file d'attente et envoyés lorsque (et si) vous vous reconnectez avec succès. Pour éviter que les signaux ne soient mis en file d'attente pendant que vous êtes déconnecté, vous pouvez utiliser la otc_session_send_signal_with_options() fonction ou le otc_session_send_signal_to_connection_with_options () fonction et définir le retryAfterReconnect au membre false dans le otc_signal_options que vous transmettez à la fonction. Pour plus d'informations, consultez Empêcher l'envoi de signaux lors d'une reconnexion automatique.

Détection de la connexion et de la déconnexion d'autres clients

Une fois que vous vous êtes connecté à une session, la fenêtre on_connection_created fonction de rappel de la otc_session_callbacks La fonction `struct` est appelée lorsqu'un nouveau client (autre que le vôtre) se connecte à la session. La connection Le paramètre de cette fonction est un pointeur vers une instance d'un otc_connection struct correspondant au client qui se connecte à la session.

Les on_connection_dropped de la fonction de rappel du otc_session_callbacks La fonction `struct` est appelée lorsqu'un client (autre que le vôtre) se déconnecte de la session. La connection de cette fonction est un pointeur sur le fichier otc_connection struct correspondant à la déconnexion du client de la session.