otc_subscriber_callbacks

Funciones de devolución de llamada del suscriptor.

Esta estructura es un conjunto de punteros a funciones que pueden invocarse para eventos relacionados con un suscriptor de OpenTok.

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.

Propiedades

Nombre Tipo Descripción
user_data void * Este miembro de la estructura puede apuntar a datos relacionados con el suscriptor que el desarrollador pueda necesitar.
reserved void * Un puntero nulo a un área de memoria que contiene recursos reservados utilizados para la implementación interna.

Devoluciones de llamada

Nombre Descripción
on_connected(subscriber, user_data, stream) Se invoca cuando la instancia se ha conectado correctamente al flujo y comienza a reproducir el contenido multimedia.
on_disconnected(subscriber, user_data) Se invoca cuando se ha interrumpido la transmisión del suscriptor.
on_reconnected(subscriber, user_data) Se invoca cuando se ha reanudado la transmisión del suscriptor.
on_render_frame(subscriber, user_data, frame) Se invoca cuando un nuevo fotograma de vídeo para el suscriptor está listo para ser renderizado.
on_video_disabled(subscriber, user_data, reason) Se invoca cuando se desactiva el vídeo del suscriptor.
on_video_enabled(subscriber, user_data, reason) Se invoca cuando se activa el vídeo del suscriptor.
on_audio_disabled(subscriber, user_data) Se invoca cuando se desactiva el audio del suscriptor.
on_audio_enabled(subscriber, user_data) Se invoca cuando se activa el audio del suscriptor.
on_video_data_received(subscriber, user_data) Se invoca cuando un suscriptor recibe datos de vídeo por primera vez.
on_video_disable_warning(subscriber, user_data) Se invoca cuando el OpenTok Media Router detecta que la calidad de la transmisión se ha deteriorado y que el vídeo se desactivará si la calidad sigue empeorando.
on_caption_text(subscriber, user_data, text, is_final) Se invoca cuando está disponible el texto de los subtítulos de la transmisión del suscriptor.
on_video_disable_warning_lifted(subscriber, user_data) Se invoca cuando el OpenTok Media Router determina que la calidad de la transmisión ha mejorado hasta el punto de que la desactivación del vídeo no supone un riesgo inmediato.
on_audio_stats(subscriber, user_data, audio_stats) Se ejecuta periódicamente para enviar un informe con las estadísticas de audio del abonado.
on_video_stats(subscriber, user_data, video_stats) Se ejecuta periódicamente para generar un informe con las estadísticas de vídeo del suscriptor.
on_audio_level_updated(subscriber, user_data, audio_level) Se invoca periódicamente para informar del nivel de audio del abonado.
on_error(subscriber, user_data, error_string, error) Se activa cuando el abonado falla.
on_audio_data(subscriber, user_data, audio_data) Se invoca periódicamente para enviar los datos de audio del abonado.
on_network_condition_changed(subscriber, user_data, media_link_stats, reason) Esta función de devolución de llamada se activa cuando se detecta un evento relacionado con la calidad en el lado del suscriptor.
on_media_link_stats(subscriber, user_data, media_link_stats) Se ejecuta periódicamente para generar informes sobre las estadísticas de enlaces multimedia del suscriptor.

on_connected(suscriptor, datos_de_usuario, flujo)

Se invoca cuando la instancia se ha conectado correctamente al flujo y comienza a reproducir el contenido multimedia.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
stream const otc_stream * El flujo del suscriptor. La instancia no perdura más allá de la ejecución de la función de devolución de llamada. Asegúrate de hacer una copia si vas a utilizar esta instancia más adelante.

on_disconnected(suscriptor, datos_de_usuario)

Se invoca cuando se ha interrumpido la transmisión del suscriptor. Esta función de devolución de llamada solo se invoca si la función de reconexión está activada, y a continuación se invoca «on_reconnected» si la reconexión se realiza con éxito. Las interrupciones habituales, cuando la reconexión no está activada, se notifican a través de la función de devolución de llamada «on_error».

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_reconnected(suscriptor, datos_de_usuario)

Se invoca cuando se ha reanudado la transmisión del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_render_frame(suscriptor, datos_de_usuario, fotograma)

Se invoca cuando un nuevo fotograma de vídeo para el suscriptor está listo para ser renderizado. No llamar a cualquier función de la API de OpenTok (excepto las que se encuentran en video_frame.h) en el mismo hilo que invoca esta función de devolución de llamada. Si necesitas llamar a una función de la API de OpenTok (por ejemplo, funciones en publisher.h o subscriber.h), reprogramar su ejecución en un hilo diferente.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
frame const otc_video_frame * El fotograma del vídeo.

on_video_disabled(suscriptor, datos_del_usuario, motivo)

Se invoca cuando se desactiva el vídeo del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
reason enumeración otc_video_reason Ofrece más detalles sobre por qué se ha desactivado el vídeo.

on_video_enabled(suscriptor, datos_de_usuario, motivo)

Se invoca cuando se activa el vídeo del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
reason enumeración otc_video_reason Ofrece más detalles sobre por qué se ha activado el vídeo.

on_audio_disabled(suscriptor, datos_de_usuario)

Se invoca cuando se desactiva el audio del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_audio_enabled(suscriptor, datos_de_usuario)

Se invoca cuando se activa el audio del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_video_data_received(suscriptor, datos_de_usuario)

Se invoca cuando un suscriptor recibe datos de vídeo por primera vez.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_video_disable_warning(suscriptor, datos_de_usuario)

Se invoca cuando el OpenTok Media Router detecta que la calidad de la transmisión se ha deteriorado y que el vídeo se desactivará si la calidad sigue empeorando.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_caption_text(suscriptor, datos_de_usuario, texto, es_final)

Se invoca cuando está disponible el texto de los subtítulos de la transmisión del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia del suscriptor.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
text const char * Referencia al texto de la leyenda.
is_final otc_bool Indica si un subtítulo está terminado.

on_video_disable_warning_lifted(suscriptor, datos_de_usuario)

Se invoca cuando el OpenTok Media Router determina que la calidad de la transmisión ha mejorado hasta el punto de que la desactivación del vídeo no supone un riesgo inmediato.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.

on_audio_stats(suscriptor, datos_de_usuario, estadísticas_de_audio)

Se ejecuta periódicamente para enviar un informe con las estadísticas de audio del abonado.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
audio_stats struct otc_subscriber_audio_stats Un puntero a la estructura de estadísticas de audio.

on_video_stats(suscriptor, datos_de_usuario, estadísticas_de_vídeo)

Se ejecuta periódicamente para generar un informe con las estadísticas de vídeo del suscriptor.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
video_stats struct otc_subscriber_video_stats Un puntero a la estructura de estadísticas del vídeo.

on_audio_level_updated(suscriptor, datos_de_usuario, nivel_de_audio)

Se invoca periódicamente para informar del nivel de audio del abonado.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
audio_level flotante El valor del nivel de audio, de 0 a 1,0.

on_error(suscriptor, datos_de_usuario, cadena_de_error, error)

Se activa cuando el abonado falla.

La mayoría de los errores son graves: el suscriptor se desconecta automáticamente y ya no se puede seguir utilizando. Algunos errores no impiden continuar y permiten seguir utilizando el suscriptor; cuando un error no es grave, así se indica en la descripción del error.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
error_string const char * Una cadena que contiene el mensaje de error.
error enumeración otc_subscriber_error_code Valor de la enumeración del código de error.

on_audio_data(suscriptor, datos_de_usuario, datos_de_audio)

Se invoca periódicamente para notificar los datos de audio del abonado. Las propiedades de audio recibidas pueden cambiar dinámicamente. Las causas de estos cambios son la negociación del códec de audio, las condiciones de la red, etc. Los consumidores de los datos de audio son responsables de gestionar estos cambios de acuerdo con el caso de uso implementado (por ejemplo, el remuestreo de audio).

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
audio_data const struct otc_audio_data * Los datos de audio.

on_network_condition_changed(suscriptor, datos_de_usuario, estadísticas_de_enlace_multimedia, motivo)

Esta función de devolución de llamada se activa cuando se detecta un evento relacionado con la calidad en el lado del suscriptor.

La implementación actual solo lo activa en caso de interrupción del vídeo (pausa), cambio de códec o cambio de resolución. Los bloqueos se registran internamente y se muestran a través de las estadísticas, pero no se activa ninguna llamada de retorno para cada bloqueo debido a su corta duración y a su elevada frecuencia potencial. Solo se activa una llamada de retorno cuando se detecta una pausa (por ejemplo, cuando no se reproduce ningún fotograma durante más de 5 segundos), ya que esto representa una interrupción más significativa en la reproducción multimedia.

El reason Este parámetro indica la causa del evento y se tiene en cuenta siguiendo el siguiente orden de prioridad: OTC_VIDEO_REASON_VIDEO_INTERRUPT, OTC_VIDEO_REASON_CODEC_CHANGE, OTC_VIDEO_REASON_RESOLUTION_CHANGE.

Este evento se diferencia de on_video_disabled y on_video_enabled funciones de devolución de llamada, ya que notifica los cambios relevantes en la calidad del vídeo. on_video_disabled y «on_video_enabled» solo indican que la pista de vídeo del suscriptor se ha activado o desactivado (por ejemplo, debido a una actualización de las propiedades de la transmisión o a un cambio a audio de reserva). Por el contrario, este evento proporciona información de diagnóstico sobre las causas de la degradación de la calidad, como los bloqueos, el número de pausas y las estadísticas actualizadas.

Esta función de devolución de llamada tiene en cuenta todo tipo de interrupciones de vídeo que duren 5 segundos o más. Esto significa que, en el caso concreto de la alternativa de audio o de los cambios en las propiedades de la transmisión (como la desactivación del vídeo), además de activar la on_video_disabled y on_video_enabled En el caso de las llamadas de retorno, la interrupción también se registra como una pausa en las estadísticas de vídeo, y se aplica la correspondiente calificación de calidad de la interrupción del vídeo.

Las aplicaciones pueden utilizar esta función de devolución de llamada para responder a problemas de calidad, como actualizar la interfaz de usuario, registrar datos de telemetría o notificar al usuario.

/** Esta función de devolución de llamada se activa cuando se detecta un cambio en las condiciones de red del suscriptor o del editor remoto.

La implementación actual activa esta llamada de retorno únicamente cuando las condiciones de red han cambiado en cualquiera de las dos partes.

El reason El parámetro indica la causa del evento y, actualmente, siempre es OTC_NETWORK_REASON_NETWORK_CONDITION_CHANGE.

Este evento se diferencia de on_video_disabled y on_video_enabled se diferencia de las demás funciones de devolución de llamada en que informa de cambios en el estado de la red, en lugar de cambios en el estado de la pista de vídeo del suscriptor. Las aplicaciones pueden utilizar esta función de devolución de llamada para responder a problemas de red, como actualizar la interfaz de usuario, registrar datos de telemetría o activar un comportamiento adaptativo.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia de suscriptor que ha desencadenado el evento.
user_data void * Puntero opcional a datos de usuario que se pasa al registrar la llamada de retorno.
media_link_stats const struct otc_subscriber_media_link_stats * Estadísticas de enlaces a medios de comunicación.
reason enumeración otc_network_reason El motivo del cambio en el estado de la red.

on_media_link_stats(suscriptor, datos_de_usuario, estadísticas_de_enlace_multimedia)

Se ejecuta periódicamente para generar informes sobre las estadísticas de enlaces multimedia del suscriptor.

Las estadísticas de enlaces de medios ofrecen una visión global del estado de la red a nivel de transporte.

Parámetros:
Nombre Tipo Descripción
subscriber otc_subscriber * La instancia que realiza esta llamada.
user_data void * Puntero a los datos personalizados del usuario vinculados a esta estructura.
media_link_stats const struct otc_subscriber_media_link_stats * Un puntero a la estructura de estadísticas de enlaces multimedia.