Top-level module for the Conviva Client Library. More...

Data Structures
struct	ccl_settings_t
	Conviva Client Library settings. More...

Macros
#define	CCL_SUCCESS 0

#define	CCL_ERROR -1

#define	CCL_MAX_URL_LENGTH 256

Typedefs
typedef struct ccl_session	ccl_session_t
	Conviva monitoring session. More...

Enumerations
enum	ccl_log_level_t { CCL_LOG_LEVEL_NONE = 0, CCL_LOG_LEVEL_ERROR = 1, CCL_LOG_LEVEL_WARN = 2, CCL_LOG_LEVEL_INFO = 3, CCL_LOG_LEVEL_DEBUG = 4 }
	Log level. More...

Functions
void	ccl_settings_create (ccl_settings_t *settings)
	Create a new ccl_settings_t. More...

void	ccl_settings_destroy (ccl_settings_t *settings)
	Destroy an existing ccl_settings_t. More...

int	ccl_init (const char customer_key, const ccl_platform_t platform_interface, const ccl_settings_t *settings)
	Initializes the library. More...

void	ccl_cleanup (void)
	Releases the library and all tied up memory/resources. More...

ccl_session_t *	ccl_session_create (ccl_content_info_t *content_info)
	Create a new monitoring session. More...

ccl_session_t *	ccl_ad_session_create (ccl_session_t content_session, ccl_content_info_t ad_content_info)
	Create a new AD monitoring session. More...

int	ccl_session_destroy (ccl_session_t *session)
	Destroy an existing monitoring session. More...

int	ccl_session_player_attach (ccl_session_t session, const ccl_player_t player, void *player_data)
	Link a video player to a monitoring session. More...

int	ccl_session_player_detach (ccl_session_t *session)
	Unlink current video player from a monitoring session. More...

int	ccl_session_ad_start (ccl_session_t *session)
	Notify Conviva that preroll advertisement has started. More...

int	ccl_session_ad_end (ccl_session_t *session)
	Notify Conviva that a preroll ad has ended. More...

int	ccl_session_report_error (ccl_session_t session, const char error_message, int is_fatal)
	Notify Conviva that an error has occurred. More...

int	ccl_send_event (const char name, ccl_dictionary_t attributes)
	Report a custom event to Conviva. More...

int	ccl_session_send_event (ccl_session_t session, const char name, ccl_dictionary_t *attributes)
	Report a custom event to Conviva. More...

void	ccl_session_update_content_info (ccl_session_t session, const ccl_content_info_t content_info)
	Update metadata content for the session. More...

void	ccl_notify_network_connection_type (const char *type)
	Notify a change of network connection type. More...

void	ccl_notify_network_signal_strength (double value)
	Notify a change of network wireless signal strength. More...

void	ccl_notify_network_wifi_link_encryption (const char *name)
	Notify a change of WiFi SSID. More...

int	ccl_session_set_video_size (ccl_session_t *session, int width, int height)
	Notify Conviva of a video resolution change. More...

unsigned int	ccl_session_get_session_id (ccl_session_t *session)
	Gets the Conviva session ID for a session. More...

char *	ccl_get_client_id (void)
	Gets the Conviva Client ID. More...

Detailed Description

Top-level module for the Conviva Client Library.

The application should call ccl_init() to initialize the library before making any other calls.
To monitor each viewing experience, a Conviva monitoring session should be created via ccl_session_create() upon playback request by the viewer.
Each monitoring session can be dynamically tied to a video player via ccl_session_player_attach(). Used with ccl_player_t and ccl_notifier_t, video playback data can then be reporting for that monitoring session.
When a video player is no longer relevant for the monitoring session, the link can be severed using ccl_session_player_detach().
When playback for that piece of content ends/fails/is cancelled, the session should be destroyed using ccl_session_destroy().
The application should call ccl_cleanup() to release the library when it is no longer needed.

Macro Definition Documentation

◆ CCL_ERROR

#define CCL_ERROR -1

◆ CCL_MAX_URL_LENGTH

#define CCL_MAX_URL_LENGTH 256

◆ CCL_SUCCESS

#define CCL_SUCCESS 0

Typedef Documentation

◆ ccl_session_t

typedef struct ccl_session ccl_session_t

Conviva monitoring session.

Enumeration Type Documentation

◆ ccl_log_level_t

enum ccl_log_level_t

Log level.

Enumerator
CCL_LOG_LEVEL_NONE	No logging.
CCL_LOG_LEVEL_ERROR	Display only error logs.
CCL_LOG_LEVEL_WARN	Display only error and warning logs.
CCL_LOG_LEVEL_INFO	Display all logs except debug logs.
CCL_LOG_LEVEL_DEBUG	Display all logs.

Function Documentation

◆ ccl_ad_session_create()

ccl_session_t* ccl_ad_session_create	(	ccl_session_t *	content_session,
		ccl_content_info_t *	ad_content_info
	)

Create a new AD monitoring session.

A new monitoring session should be created for each piece of Ad content.

Parameters

content_session	instance of video content
ad_content_info	Metadata associated with the ad content to be monitored.

Returns

A pointer of ccl_session_t on success.
NULL otherwise.

◆ ccl_cleanup()

void ccl_cleanup ( void )

Releases the library and all tied up memory/resources.

Note: This will terminate all active monitoring sessions as well.

◆ ccl_get_client_id()

char* ccl_get_client_id ( void )

Gets the Conviva Client ID.

Returns

Returns pointer to a string which represents client Id

Note: This API shall be called after ccl_init only

◆ ccl_init()

int ccl_init	(	const char *	customer_key,
		const ccl_platform_t *	platform_interface,
		const ccl_settings_t *	settings
	)

Initializes the library.

One-time synchronous call required to initialize the library.

Parameters

customer_key	The Conviva customer key associated with your Conviva account.
platform_interface	Your implementation of ccl_platform_t for your device.
settings	Optional. Custom settings for the library.

Returns

CCL_SUCCESS
CCL_ERROR

Warning: All other API calls will fail until the library is properly initialized with a call to ccl_init.

Note: Calling ccl_init() when the library is already initialized will have no effect.

◆ ccl_notify_network_connection_type()

void ccl_notify_network_connection_type ( const char * type )

Notify a change of network connection type.

The type of network connection can be "3G", "4G", "WiFi", "LTE", and etc. When the type is unknown, set "Other".

Parameters

type	network connection type

◆ ccl_notify_network_signal_strength()

void ccl_notify_network_signal_strength ( double value )

Notify a change of network wireless signal strength.

Parameters

value Signal strength.

◆ ccl_notify_network_wifi_link_encryption()

void ccl_notify_network_wifi_link_encryption ( const char * name )

Notify a change of WiFi SSID.

Parameters

ssid	WiFi SSID. Notify a change of WiFi Link Encryption.

Example values are "WEP", "WEP2", "WPA", "WPA2".

Parameters

name	Link encryption.

◆ ccl_send_event()

int ccl_send_event	(	const char *	name,
		ccl_dictionary_t *	attributes
	)

Report a custom event to Conviva.

Part of the Conviva Player Insight feature.
Each event has a name and a list of key-value pair attributes.

Parameters

name	Name of the event.
attributes	Optional. Attributes associated with the event.

Returns

CCL_SUCCESS
CCL_ERROR

Note: This method can be used without an active monitoring session.

◆ ccl_session_ad_end()

int ccl_session_ad_end ( ccl_session_t * session )

Notify Conviva that a preroll ad has ended.

Use right after playing preroll advertisement.

Parameters

session Pointer to a ccl_session_t.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_ad_start()

int ccl_session_ad_start ( ccl_session_t * session )

Notify Conviva that preroll advertisement has started.

Use right before playing preroll advertisement.

Parameters

session Pointer to a ccl_session_t.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_create()

ccl_session_t* ccl_session_create ( ccl_content_info_t * content_info )

Create a new monitoring session.

A new monitoring session should be created for each piece of video content, at the time playback is requested by the viewer.

Parameters

content_info Metadata associated with the content to be monitored.

Returns

A pointer of ccl_session_t on success.
NULL otherwise.

◆ ccl_session_destroy()

int ccl_session_destroy ( ccl_session_t * session )

Destroy an existing monitoring session.

An existing monitoring session should be destroyed when video playback for the content ends, fails or is cancelled by the viewer.

Parameters

session Pointer to the ccl_session_t to destroy.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_get_session_id()

unsigned int ccl_session_get_session_id ( ccl_session_t * session )

Gets the Conviva session ID for a session.

Parameters

session Pointer to a ccl_session_t.

Returns

Session Id of CCL session

Note: This API shall be called after session create and before session destroy

◆ ccl_session_player_attach()

int ccl_session_player_attach	(	ccl_session_t *	session,
		const ccl_player_t *	player,
		void *	player_data
	)

Link a video player to a monitoring session.

Attach a video player to a monitoring session.
Generally used right after ccl_session_create.
To properly handle midroll advertisement, it is sometimes necessary to use this method after a midroll ad.
If you are using multiple video players over the course of a single monitoring session, you may have to call this multiple times as well.

Parameters

session	Pointer to a ccl_session_t.
player	Interface to the video player.
player_data	Context data for the video player.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_player_detach()

int ccl_session_player_detach ( ccl_session_t * session )

Unlink current video player from a monitoring session.

Detaches the current video player from a monitoring session.
Generally used right before calling ccl_session_destroy.
To properly handle midroll advertisement, it is sometimes necessary to use this method before a midroll ad.
If you are using multiple video players over the course of a single monitoring session, you may have to call this multiple times as well.

Parameters

session Pointer to a ccl_session_t.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_report_error()

int ccl_session_report_error	(	ccl_session_t *	session,
		const char *	error_message,
		int	is_fatal
	)

Notify Conviva that an error has occurred.

To report errors from the video player, use set_error instead.

Parameters

session	Pointer to a ccl_session_t.
error_message	A message describing the error.
is_fatal	Whether the error can prevent playback altogether. When in doubt, set to true.

Returns

CCL_SUCCESS
CCL_ERROR

Warning: We strongly recommend sticking to static error messages like error codes.
Including dynamic variables like user ID or memory addresses makes spotting error patterns much harder.

◆ ccl_session_send_event()

int ccl_session_send_event	(	ccl_session_t *	session,
		const char *	name,
		ccl_dictionary_t *	attributes
	)

Report a custom event to Conviva.

Part of the Conviva Player Insight feature.
Each event has a name and a list of key-value pair attributes.

Parameters

name	Name of the event.
attributes	Optional. Attributes associated with the event.

Returns

CCL_SUCCESS
CCL_ERROR

Note: This method can be used only with an active monitoring session.

◆ ccl_session_set_video_size()

int ccl_session_set_video_size	(	ccl_session_t *	session,
		int	width,
		int	height
	)

Notify Conviva of a video resolution change.

Parameters

session	Pointer to a ccl_session_t.
width	Width of video resolution.
height	Height of video resolution.

Returns

CCL_SUCCESS
CCL_ERROR

◆ ccl_session_update_content_info()

void ccl_session_update_content_info	(	ccl_session_t *	session,
		const ccl_content_info_t *	content_info
	)

Update metadata content for the session.

NOTE: Only those metadata values that were not previously set are updated.

Parameters

session	Pointer to a ccl_session_t.
content_info	Metadata associated with the content to be monitored.

◆ ccl_settings_create()

void ccl_settings_create ( ccl_settings_t * settings )

Create a new ccl_settings_t.

Note: All fields are set to their default values.; When setting the gateway_url, free the existing string and set a newly allocated string.

Parameters

settings instance to ccl_settings_t structure which will be set to default values

◆ ccl_settings_destroy()

void ccl_settings_destroy ( ccl_settings_t * settings )

Destroy an existing ccl_settings_t.

Parameters

setting instance to ccl_settings_t structure which needs to be destroyed

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CCL_ERROR

◆ CCL_MAX_URL_LENGTH

◆ CCL_SUCCESS

Typedef Documentation

◆ ccl_session_t

Enumeration Type Documentation

◆ ccl_log_level_t

Function Documentation

◆ ccl_ad_session_create()

◆ ccl_cleanup()

◆ ccl_get_client_id()

◆ ccl_init()

◆ ccl_notify_network_connection_type()

◆ ccl_notify_network_signal_strength()

◆ ccl_notify_network_wifi_link_encryption()

◆ ccl_send_event()

◆ ccl_session_ad_end()

◆ ccl_session_ad_start()

◆ ccl_session_create()

◆ ccl_session_destroy()

◆ ccl_session_get_session_id()

◆ ccl_session_player_attach()

◆ ccl_session_player_detach()

◆ ccl_session_report_error()

◆ ccl_session_send_event()

◆ ccl_session_set_video_size()

◆ ccl_session_update_content_info()

◆ ccl_settings_create()

◆ ccl_settings_destroy()