subscriber.h File Reference

OpenTok Subscriber. More...

#include "config.h"
#include "stream.h"
#include "error.h"
#include "video_frame.h"
#include "audio_data.h"

Go to the source code of this file.

Data Structures
struct	otc_subscriber_audio_stats
struct	otc_subscriber_video_stats
struct	otc_subscriber_rtc_stats_report_cb
struct	otc_subscriber_callbacks

Typedefs
typedef struct otc_subscriber	otc_subscriber

Enumerations
enum	otc_subscriber_error_code {   OTC_SUBSCRIBER_INTERNAL_ERROR = 2000, OTC_SUBSCRIBER_SESSION_DISCONNECTED = 1010, OTC_SUBSCRIBER_SERVER_CANNOT_FIND_STREAM = 1604, OTC_SUBSCRIBER_STREAM_LIMIT_EXCEEDED = 1605,   OTC_SUBSCRIBER_TIMED_OUT, OTC_SUBSCRIBER_WEBRTC_ERROR = 1600, OTC_SUBSCRIBER_PEER_CONNECTION_NOT_CONNECTED, OTC_SUBSCRIBER_DECRYPTION_INTERNAL_ERROR,   OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH }

Functions
otc_subscriber *	otc_subscriber_new (const otc_stream *stream, const struct otc_subscriber_callbacks *callbacks)
otc_status	otc_subscriber_delete (otc_subscriber *subscriber)
otc_stream *	otc_subscriber_get_stream (const otc_subscriber *subscriber)
otc_status	otc_subscriber_set_subscribe_to_video (otc_subscriber *subscriber, otc_bool subscribe_to_video)
otc_status	otc_subscriber_set_subscribe_to_audio (otc_subscriber *subscriber, otc_bool subscribe_to_audio)
otc_status	otc_subscriber_set_subscribe_to_captions (otc_subscriber *subscriber, otc_bool subscribe_to_captions)
otc_bool	otc_subscriber_get_subscribe_to_video (const otc_subscriber *subscriber)
otc_bool	otc_subscriber_get_subscribe_to_audio (const otc_subscriber *subscriber)
otc_bool	otc_subscriber_get_subscribe_to_captions (const otc_subscriber *subscriber)
otc_session *	otc_subscriber_get_session (const otc_subscriber *subscriber)
otc_status	otc_subscriber_set_preferred_resolution (otc_subscriber *subscriber, uint32_t preferred_width, uint32_t preferred_height)
otc_status	otc_subscriber_get_preferred_resolution (const otc_subscriber *subscriber, uint32_t *preferred_width, uint32_t *preferred_height)
otc_status	otc_subscriber_set_audio_volume (otc_subscriber *subscriber, double volume)
otc_status	otc_subscriber_get_audio_volume (const otc_subscriber *subscriber, double *volume)
otc_status	otc_subscriber_set_preferred_framerate (otc_subscriber *subscriber, float preferred_framerate)
otc_status	otc_subscriber_get_preferred_framerate (const otc_subscriber *subscriber, float *preferred_framerate)
const char *	otc_subscriber_get_subscriber_id (const otc_subscriber *subscriber)
void *	otc_subscriber_get_user_data (const otc_subscriber *subscriber)
otc_status	otc_subscriber_get_rtc_stats_report (const otc_subscriber *subscriber)
otc_status	otc_subscriber_set_rtc_stats_report_cb (otc_subscriber *subscriber, struct otc_subscriber_rtc_stats_report_cb cb)

Detailed Description

OpenTok Subscriber.

This file includes the type definition for an OpenTok subscriber along with several function declarations.

Typedef Documentation

otc_subscriber

typedef struct otc_subscriber otc_subscriber

OpenTok subscriber type definition.

A type representing the consumer of audio and video from a stream in the OpenTok session.

Enumeration Type Documentation

otc_subscriber_error_code

enum otc_subscriber_error_code

Error code enumeration for OpenTok subscribers.

This enumeration represents several error codes associated with a subscriber.

Enumerator
OTC_SUBSCRIBER_INTERNAL_ERROR	Internal error when subscribing.
OTC_SUBSCRIBER_SESSION_DISCONNECTED	Attempting to subscribe to a stream in a session that you have disconnected from.
OTC_SUBSCRIBER_SERVER_CANNOT_FIND_STREAM	The subscriber failed because the stream is missing. This can happen if the subscriber is created at the same time the stream is removed from the session.
OTC_SUBSCRIBER_STREAM_LIMIT_EXCEEDED	The client tried to subscribe to a stream in a session that has exceeded the limit for simultaneous streams.
OTC_SUBSCRIBER_TIMED_OUT	Timeout while attempting to subscribe.
OTC_SUBSCRIBER_WEBRTC_ERROR	Subscriber WebRTC failure.
OTC_SUBSCRIBER_PEER_CONNECTION_NOT_CONNECTED	The peer connection is not yet created or connected.
OTC_SUBSCRIBER_DECRYPTION_INTERNAL_ERROR	Internal error while decrypting a packet
OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH	Secret mismatch while decrypting a packet

Function Documentation

otc_subscriber_delete()

otc_status otc_subscriber_delete

(

otc_subscriber *

subscriber

)

Releases a subscriber instance, including all hardware and UI resources bound to it.

Parameters

subscriber

The subcriber to be deleted.

Returns

Return value indicating either error or success.

otc_subscriber_get_audio_volume()

otc_status otc_subscriber_get_audio_volume	(	const otc_subscriber *	subscriber,
		double *	volume
	)

Returns the audio volume, between 0 and 100, of the subscriber.

The default value is 100.

Parameters

subscriber	The subscriber instance.
volume	The volume of the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_get_preferred_framerate()

otc_status otc_subscriber_get_preferred_framerate	(	const otc_subscriber *	subscriber,
		float *	preferred_framerate
	)

Returns the preferred frame rate for the subscriber's stream.

Parameters

subscriber	The subscriber instance.
preferred_framerate	The preferred framerate associated with the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_get_preferred_resolution()

otc_status otc_subscriber_get_preferred_resolution	(	const otc_subscriber *	subscriber,
		uint32_t *	preferred_width,
		uint32_t *	preferred_height
	)

Returns the preferred resolution for the subscriber's stream.

Parameters

subscriber	The subscriber instance.
preferred_width	The preferred width of the subscriber.
preferred_height	The preferred height of the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_get_rtc_stats_report()

otc_status otc_subscriber_get_rtc_stats_report

(

const otc_subscriber *

subscriber

)

Gets the RTC stats report for the subscriber. This is an asynchronous operation. create an otc_subscriber_rtc_stats_report_cb struct and pass it into the otc_subscriber_set_rtc_stats_report_cb function prior to calling this function. When the stats are available, the otc_subscriber_set_rtc_stats_report_cb callback function is called.

Also see otc_subscriber_callbacks.on_audio_stats, otc_subscriber_callbacks.on_video_stats, and otc_publisher_get_rtc_stats_report.

Parameters

subscriber

The subscriber.

otc_subscriber_get_session()

otc_session* otc_subscriber_get_session

(

const otc_subscriber *

subscriber

)

Returns the otc_session associated this instance.

Parameters

subscriber

The subscriber instance.

Returns

The otc_session associated this instance. This can be null if there is an error.

otc_subscriber_get_stream()

otc_stream* otc_subscriber_get_stream

(

const otc_subscriber *

subscriber

)

Returns the stream associated with the subscriber.

Parameters

subscriber

The subscriber instance to get the stream from.

Returns

The stream associated with the subscriber. This can be null if there is an error.

otc_subscriber_get_subscribe_to_audio()

otc_bool otc_subscriber_get_subscribe_to_audio

(

const otc_subscriber *

subscriber

)

Returns whether the subscriber is subscribed to the stream's audio or not.

Parameters

subscriber

The subscriber instance.

Returns

Whether the subscriber is subscribed to the stream's audio or not.

otc_subscriber_get_subscribe_to_captions()

otc_bool otc_subscriber_get_subscribe_to_captions

(

const otc_subscriber *

subscriber

)

Returns whether the subscriber is subscribed to the stream's captions or not.

Parameters

subscriber

The subscriber instance.

Returns

Whether the subscriber is subscribed to the stream's captions or not. The default value is the captions value of the stream's publisher otc_publisher_get_publish_captions

otc_subscriber_get_subscribe_to_video()

otc_bool otc_subscriber_get_subscribe_to_video

(

const otc_subscriber *

subscriber

)

Returns whether the subscriber is subscribed to the stream's video or not.

Parameters

subscriber

The subscriber instance.

Returns

Whether the subscriber is subscribed to the stream's video or not.

otc_subscriber_get_subscriber_id()

const char* otc_subscriber_get_subscriber_id

(

const otc_subscriber *

subscriber

)

Gets a unique identifier for a given subscriber.

Parameters

subscriber

The subscriber instance.

Returns

A unique identifier for the subscriber. This can be null if there is an error.

otc_subscriber_get_user_data()

void* otc_subscriber_get_user_data

(

const otc_subscriber *

subscriber

)

Gets user data for a given subscriber.

Parameters

subscriber

The subscriber instance.

Returns

A pointer to the user data in memory.

otc_subscriber_new()

otc_subscriber* otc_subscriber_new	(	const otc_stream *	stream,
		const struct otc_subscriber_callbacks *	callbacks
	)

Creates a new Subscriber for a given Stream.

Parameters

stream	The Stream object corresponding to the stream you will subscribe to.
callbacks	Struct with function pointers of the subscriber's callbacks.

Returns

The new Subscriber instance. This can be null if there is an error.

otc_subscriber_set_audio_volume()

otc_status otc_subscriber_set_audio_volume	(	otc_subscriber *	subscriber,
		double	volume
	)

Sets the audio volume, between 0 and 100, of the subscriber. If the value is not in this range, it will be clamped to it.

Parameters

subscriber	The subscriber instance.
volume	The volume of the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_set_preferred_framerate()

otc_status otc_subscriber_set_preferred_framerate	(	otc_subscriber *	subscriber,
		float	preferred_framerate
	)

Sets the preferred frame rate for the subscriber's stream.

The default value is 100.

Parameters

subscriber	The subscriber instance which will be affected.
preferred_framerate	The preferred framerate of the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_set_preferred_resolution()

otc_status otc_subscriber_set_preferred_resolution	(	otc_subscriber *	subscriber,
		uint32_t	preferred_width,
		uint32_t	preferred_height
	)

Sets the preferred resolution for the subscriber's stream.

Parameters

subscriber	The subscriber instance which will be affected.
preferred_width	The preferred width of the subscriber.
preferred_height	The preferred height of the subscriber.

Returns

Return value indicating either error or success.

See also

otc_error_code

otc_subscriber_set_rtc_stats_report_cb()

otc_status otc_subscriber_set_rtc_stats_report_cb	(	otc_subscriber *	subscriber,
		struct otc_subscriber_rtc_stats_report_cb	cb
	)

Sets the RTC stats report callback the subscriber. See otc_subscriber_get_rtc_stats_report.

Parameters

subscriber	The subscriber instance.
cb	The otc_subscriber_rtc_stats_report_cb struct that includes the callback function for the RTC stats report.

otc_subscriber_set_subscribe_to_audio()

otc_status otc_subscriber_set_subscribe_to_audio	(	otc_subscriber *	subscriber,
		otc_bool	subscribe_to_audio
	)

Subscribes to the stream's audio.

Parameters

subscriber	The subscriber instance which will be affected.
subscribe_to_audio	Whether to subscribe to audio or not.

Returns

Return value indicating either error or success.

otc_subscriber_set_subscribe_to_captions()

otc_status otc_subscriber_set_subscribe_to_captions	(	otc_subscriber *	subscriber,
		otc_bool	subscribe_to_captions
	)

Subscribes to captions for the stream.

Parameters

subscriber	The subscriber instance which will be affected.
subscribe_to_captions	Whether to subscribe to captions or not.

Returns

Return value indicating either error or success.

otc_subscriber_set_subscribe_to_video()

otc_status otc_subscriber_set_subscribe_to_video	(	otc_subscriber *	subscriber,
		otc_bool	subscribe_to_video
	)

Subscribes to the stream's video.

Parameters

subscriber	The subscriber instance which will be affected.
subscribe_to_video	Whether to subscribe to video or not.

Returns

Return value indicating either error or success.