CI Content Control. More...

#include <string.h>
#include "techtype.h"
#include "dbgfuncs.h"
#include "stbhwos.h"
#include "stbhwci.h"
#include "stbci.h"
#include "stberc.h"
#include "stbhwav.h"
#include "stbheap.h"
#include "stbdpc.h"
#include "stbcicc.h"
#include "stbci_int.h"

Classes
struct	ci_protection

struct	s_slot_state

Macros
#define	MAX_CICAM_BRANDS 126

#define	DBG_CC(x, ...)

#define	DBG_REC(x, ...)

Typedefs
typedef struct ci_protection	S_CI_PROTECTION

typedef struct s_slot_state	S_SLOT_STATE

Enumerations
enum	E_CI_AUTH_STATUS { CI_AUTH_NONE = 0, CI_AUTH_IN_PROGRESS, CI_AUTH_SUCCESS, CI_AUTH_FAIL }

Functions
void	STB_CiCcInitialise (void)
	CI content control support initialise.

void	STB_CiCcNotifyModuleInsert (U8BIT slot_id)
	Notify module insertion. More...

void	STB_CINotifyModuleReady (U8BIT slot_id, BOOLEAN ci_plus, U32BIT mask)
	Notify module insertion. More...

void	STB_CiCcNotifyModuleRemove (U8BIT slot_id)
	Notify module removal. More...

void	STB_CiCcRemove (U8BIT slot_id)
	Handle CAM removal from slot. More...

BOOLEAN	STB_CiCcIsSlotReady (U8BIT slot_id)
	Return whether CI slot is ready. More...

BOOLEAN	STB_CiCcIsServiceAllowed (U8BIT slot_id, U8BIT *ci_prot_desc)
	Tell whether the service is allowed. This function checks whether the CI Protection Descriptor allows the service to be routed through the CI module. More...

BOOLEAN	STB_CiCcAuthenticated (U8BIT slot_id)
	Tell whether the CI slot has been authenticated. More...

U8BIT	STB_CiCcFindSlotForCicamId (U8BIT cicam_id[CIP_CICAM_ID_LEN])
	Checks CAMs in all slots to find the one with the given CAM id. More...

void	STB_CiCcSetSDTAcquisitionStatus (BOOLEAN complete)
	To implement the first part of the diagram in Figure 10.2: Shunning Operation of ci-plus_specification_v1.3.2.pdf, this function passes the status of the SDT acquisition to the ci+ glue. More...

void	STB_CiCcGetUsageRulesInfo (U8BIT slot_id, U16BIT service_id, U8BIT raw_uri[CIP_URI_LEN])
	Return the current URI for the given service. More...

void	STB_CiCcGetDefaultUsageRulesInfo (U8BIT raw_uri[CIP_URI_LEN])
	Sets the default URI values into the given array. The URI requires HDCP. More...

U32BIT	STB_CiCcGetRetentionLimit (U8BIT raw_uri[CIP_URI_LEN])
	Return the retention limit given a packed URI. More...

void	STB_CiCcApplyUsageRulesInfo (U8BIT raw_uri[CIP_URI_LEN])
	Apply the given Usage Rules Information. More...

void	STB_CiCcApplyUsageRulesInfoForPlayback (U8BIT *raw_uri)
	Apply the given Usage Rules Information for playback. More...

BOOLEAN	STB_CiCcIsHDCPRequired (U16BIT service_id)
	Tell whether the given service requires HDCP. More...

void	STB_CINotifyProgress (U8BIT slot_id, E_STB_CI_CC_STATE state, U16BIT cicam_brand_id)
	Notify content control progress. More...

void	STB_CINotifyURI (U8BIT slot_id, U16BIT program_number, S_STB_CI_URI *uri)
	Handle URI (usage rules information) More...

U8BIT	STB_CINotifySRM (U8BIT slot_id, E_STB_SRM_DATA_TYPE srm_type, U8BIT *data, U16BIT len)
	This function is called by the CI+ stack to send an SRM (System Renewability Message) to the host. SRM data files perform the function of blacklist for HDCP. More...

void	STB_CINotifyPinCaps (U8BIT slot_id, E_STB_CI_PIN_CAPS capability, S_STB_CI_DATE pin_date, S_STB_CI_TIME pin_time, U8BIT rating)

BOOLEAN	STB_CiCcSendPin (U8BIT slot_id, U8BIT *pin_data)
	Called by the host to check whether a CAM pin is valid. An STB_EVENT_CI_PIN_STATUS event will be sent to notify the host of the validity, or otherwise, of the pin. More...

void	STB_CINotifyPinReply (U8BIT slot_id, E_STB_CI_PIN_STATUS status)

void	STB_CINotifyPinEvent (U8BIT slot_id, U16BIT program_number, E_STB_CI_PIN_STATUS status, U8BIT rating, S_STB_CI_DATE event_date, S_STB_CI_TIME event_time, U8BIT private_data[CIP_PIN_PRIVATE_DATA_SIZE])

BOOLEAN	STB_CiCcGetRecordingPinInfo (U8BIT slot_id, U8BIT status, U8BIT age_rating, U8BIT *private_data, U16BIT date_code, U8BIT hour, U8BIT min, U8BIT *sec)
	Returns the information to be stored with a pin event when recording. More...

BOOLEAN	STB_CiCcSendPinPlayback (U8BIT slot_id, U8BIT age_rating, U8BIT *private_data)
	Sends a pin event to the CAM during playback. More...

void	STB_CiCcSetRecordOperatingMode (U8BIT slot_id, U32BIT mode, U16BIT service_id)
	Sets the record operating mode for the given slot id. More...

BOOLEAN	STB_CiCcSendRecordStart (U8BIT slot_id, U16BIT program_number, U8BIT *pin_string)
	Called by the app when a recording is to be started on a CA protected service. More...

void	STB_CINotifyRecordStartStatus (U8BIT slot_id, U8BIT status)

void	STB_CINotifyRecordingLicense (U8BIT slot_id, U16BIT program_number, U8BIT licence_status, S_STB_CI_URI uri, U8BIT licence, U16BIT licence_len)

U8BIT *	STB_CiCcGetRecordingLicence (U8BIT slot_id, U8BIT licence_status, U16BIT licence_len, U8BIT raw_uri[CIP_URI_LEN])
	Returns the last licence received from the CAM when recording. More...

BOOLEAN	STB_CiCcSendPlaybackLicence (U8BIT slot_id, U16BIT program_number, U8BIT *licence, U16BIT licence_len)
	Sends a CICAM licence to a module during playback, which will result in a modified licence being notified through STB_CINotifyCicamLicence. More...

void	STB_CINotifyPlaybackLicense (U8BIT slot_id, U16BIT program_number, U8BIT licence_status, S_STB_CI_URI uri, U8BIT licence, U16BIT licence_len)

U8BIT *	STB_CiCcGetPlaybackLicence (U8BIT slot_id, U8BIT licence_status, U16BIT licence_len, U8BIT raw_uri[CIP_URI_LEN])
	Returns the last licence received from the CAM during playback. More...

void	STB_CINotifyLicenseStatus (U8BIT slot_id, U8BIT licence_status, U8BIT play_count)

void	STB_CINotifyModeChangeStatus (U8BIT slot_id, U8BIT status)

BOOLEAN	STB_CiCcSendRecordStop (U8BIT slot_id)
	Called by the app when a recording is stopped or completes. More...

void	STB_CINotifyRecordStopStatus (U8BIT slot_id, U8BIT status)

Detailed Description

CI Content Control.

Date: 28 November 2016

Author: Adam Sturtridge

Function Documentation

void STB_CiCcApplyUsageRulesInfo ( U8BIT raw_uri[CIP_URI_LEN] )

Apply the given Usage Rules Information.

Parameters

uri	- Usage Rules Information

void STB_CiCcApplyUsageRulesInfoForPlayback ( U8BIT * raw_uri )

Apply the given Usage Rules Information for playback.

Parameters

uri	- Usage Rules Information

BOOLEAN STB_CiCcAuthenticated ( U8BIT slot_id )

Tell whether the CI slot has been authenticated.

Tell whether authenticated CI+ module is in the slot.

Parameters

slot_id slot ID (0, 1, ...)

Returns: BOOLEAN - TRUE if authenticated

U8BIT STB_CiCcFindSlotForCicamId ( U8BIT cicam_id[CIP_CICAM_ID_LEN] )

Checks CAMs in all slots to find the one with the given CAM id.

Parameters

cicam_id - CAM id to look for

Returns: slot id if found, INVALID_RES_ID if not found

void STB_CiCcGetDefaultUsageRulesInfo ( U8BIT raw_uri[CIP_URI_LEN] )

Sets the default URI values into the given array. The URI requires HDCP.

Parameters

raw_uri - returns with the default URI settings

U8BIT* STB_CiCcGetPlaybackLicence	(	U8BIT	slot_id,
		U8BIT *	licence_status,
		U16BIT *	licence_len,
		U8BIT	raw_uri[CIP_URI_LEN]
	)

Returns the last licence received from the CAM during playback.

Parameters

slot_id	- slot
licence_status	- status value associated with the licence
licence_len	- pointer to return the licence length in bytes
raw_uri	- returns with the packed URI data associated with the licence

Returns: pointer to the licence data, mustn't be freed. NULL if no licence

U8BIT* STB_CiCcGetRecordingLicence	(	U8BIT	slot_id,
		U8BIT *	licence_status,
		U16BIT *	licence_len,
		U8BIT	raw_uri[CIP_URI_LEN]
	)

Returns the last licence received from the CAM when recording.

Parameters

slot_id	- slot
licence_status	- status value associated with the licence
licence_len	- pointer to return the licence length in bytes
raw_uri	- returns with the packed URI data associated with the licence

Returns: pointer to the licence data, mustn't be freed. NULL if no licence

BOOLEAN STB_CiCcGetRecordingPinInfo	(	U8BIT	slot_id,
		U8BIT *	status,
		U8BIT *	age_rating,
		U8BIT **	private_data,
		U16BIT *	date_code,
		U8BIT *	hour,
		U8BIT *	min,
		U8BIT *	sec
	)

Returns the information to be stored with a pin event when recording.

Parameters

slot_id	- slot being used for the recording
status	- pin status code
age_rating	- returns the age rating supplied with the pin event
private_data	- returns a pointer to the private data to be saved - don't free
date_code	- MJD UTC date code when the pin is to be applied
hour	- UTC hour when the pin is to be applied
min	- UTC minute when the pin is to be applied
sec	- UTC second when the pin is to be applied

Returns: TRUE if the info is returned, FALSE otherwise

U32BIT STB_CiCcGetRetentionLimit ( U8BIT raw_uri[CIP_URI_LEN] )

Return the retention limit given a packed URI.

Parameters

uri	- Usage Rules Information

Returns: Retention limit in minutes (0 = no limit)

void STB_CiCcGetUsageRulesInfo	(	U8BIT	slot_id,
		U16BIT	service_id,
		U8BIT	raw_uri[CIP_URI_LEN]
	)

Return the current URI for the given service.

Parameters

slot_id	- slot ID
service_id	- service ID
uri	- the URI for the service

Returns: URI for the service if available or "empty" URI otherwise

BOOLEAN STB_CiCcIsHDCPRequired ( U16BIT service_id )

Tell whether the given service requires HDCP.

Parameters

service_id - Service ID

BOOLEAN STB_CiCcIsServiceAllowed	(	U8BIT	slot_id,
		U8BIT *	ci_prot_desc
	)

Tell whether the service is allowed. This function checks whether the CI Protection Descriptor allows the service to be routed through the CI module.

Parameters

slot_id	slot ID (0, 1, ...)
ci_prot_desc	CI Protection Descriptor for the service

Returns: BOOLEAN - TRUE if allowed

BOOLEAN STB_CiCcIsSlotReady ( U8BIT slot_id )

Return whether CI slot is ready.

Parameters

slot_id - slot ID (0, 1, ...)

Returns: BOOLEAN - TRUE if ready

void STB_CiCcNotifyModuleInsert ( U8BIT slot_id )

Notify module insertion.

Parameters

slot_id - slot ID for module

void STB_CiCcNotifyModuleRemove ( U8BIT slot_id )

Notify module removal.

Parameters

slot_id - slot ID for module

void STB_CiCcRemove ( U8BIT slot_id )

Handle CAM removal from slot.

Parameters

slot_id zero-based CI slot identifier (0, 1, ...)

BOOLEAN STB_CiCcSendPin	(	U8BIT	slot_id,
		U8BIT *	pin_data
	)

Called by the host to check whether a CAM pin is valid. An STB_EVENT_CI_PIN_STATUS event will be sent to notify the host of the validity, or otherwise, of the pin.

Parameters

slot_id	- slot
pin_data	- ASCII encoded pin data, null terminated

Returns: TRUE if the pin was sent successfully, FALSE otherwise

BOOLEAN STB_CiCcSendPinPlayback	(	U8BIT	slot_id,
		U8BIT	age_rating,
		U8BIT *	private_data
	)

Sends a pin event to the CAM during playback.

Parameters

slot_id	- slot
age_rating	- rating as provided by the pin event during recording
private_data	- pin private data as provided by the pin event during recording

Returns: TRUE on success, FALSE otherwise

BOOLEAN STB_CiCcSendPlaybackLicence	(	U8BIT	slot_id,
		U16BIT	program_number,
		U8BIT *	licence,
		U16BIT	licence_len
	)

Sends a CICAM licence to a module during playback, which will result in a modified licence being notified through STB_CINotifyCicamLicence.

Parameters

slot_id	- slot
program_number	- program number being played back
licence	- CICAM licence
licence_len	- licence length in bytes

Returns: TRUE if operation succeeded, FALSE otherwise

BOOLEAN STB_CiCcSendRecordStart	(	U8BIT	slot_id,
		U16BIT	program_number,
		U8BIT *	pin_string
	)

Called by the app when a recording is to be started on a CA protected service.

Parameters

slot_id	- slot being used for the recording
program_number	- service ID
pin_string	- pin as a null terminated ascii string

Returns: TRUE on success, but this doesn't mean the recording can start, FALSE otherwise

BOOLEAN STB_CiCcSendRecordStop ( U8BIT slot_id )

Called by the app when a recording is stopped or completes.

Parameters

slot_id - slot being used for the recording

Returns: TRUE on success, FALSE otherwise

void STB_CiCcSetRecordOperatingMode	(	U8BIT	slot_id,
		U32BIT	mode,
		U16BIT	service_id
	)

Sets the record operating mode for the given slot id.

Parameters

slot_id	- slot to be used for the recording
mode	- mode in which the host is in
service_id	-

void STB_CiCcSetSDTAcquisitionStatus ( BOOLEAN complete )

To implement the first part of the diagram in Figure 10.2: Shunning Operation of ci-plus_specification_v1.3.2.pdf, this function passes the status of the SDT acquisition to the ci+ glue.

To implement the first part of the diagram in "Figure 10.2: Shunning Operation" of ci-plus_specification_v1.3.2.pdf, this function passes the status of the SDT acquisition to the ci+ glue.

Parameters

sdt_acquisition_status TRUE if the SDT acquisition is completed (either successfully if the table has been received, or unsuccessfully if the SDT timeout has expired), FALSE if the DVB engine is waiting for an SDT.

void STB_CINotifyLicenseStatus	(	U8BIT	slot_id,
		U8BIT	licence_status,
		U8BIT	play_count
	)

Function Name: STB_CINotifyLicenseStatus

Description: This function is called by the CI+ stack to send the licence status and the remaining number of plays that the user is entitled to.

The function should be called in response to a call to CIP_RequestLicenceCheck.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) licence_status - the licence status play_count - number of plays remaining

Returns: Nothing

void STB_CINotifyModeChangeStatus	(	U8BIT	slot_id,
		U8BIT	status
	)

Function Name: STB_CINotifyModeChangeStatus

Description: This function is called by the CI+ stack to send the mode change status to the host. This function should be called in response to CIP_ChangeOperatingMode.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) status - mode change status

Returns: Nothing

void STB_CINotifyModuleReady	(	U8BIT	slot_id,
		BOOLEAN	ci_plus,
		U32BIT	mask
	)

Notify module insertion.

Parameters

slot_id	- slot ID for module
ci_plus	- TRUE if the module claims to be a CI+ module
mask	- a bit mask indicating which features are supported

void STB_CINotifyPlaybackLicense	(	U8BIT	slot_id,
		U16BIT	program_number,
		U8BIT	licence_status,
		S_STB_CI_URI *	uri,
		U8BIT *	licence,
		U16BIT	licence_len
	)

Function Name: STB_CINotifyPlaybackLicense

Description: This function is called by the CI+ stack to send the licence status, the URI and the optional licence data to the host.

The function is called in response to a playback start message from the host (sent using STB_CISendPlaybackLicence).

The licence and URI replace the ones that were stored with the recording. If the licence was updated, the new licence will have the same size as the original licence.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) program_number - the program number licence_status - licence status uri - usage rules structure for the recording licence - the CICAM licence (or NULL if not required) licence_len - licence length in bytes

Returns: Nothing

void STB_CINotifyProgress	(	U8BIT	slot_id,
		E_STB_CI_CC_STATE	state,
		U16BIT	cicam_brand_id
	)

Notify content control progress.

Parameters

module	- module ID
state	- content control state
cicam_brand_id	- CICAM brand identifier

void STB_CINotifyRecordingLicense	(	U8BIT	slot_id,
		U16BIT	program_number,
		U8BIT	licence_status,
		S_STB_CI_URI *	uri,
		U8BIT *	licence,
		U16BIT	licence_len
	)

Function Name: STB_CINotifyRecordingLicence

Description: This function is called by the CI+ stack to send the licence status, the URI and the optional licence data to the host.

This function may be called during a recording (after a call to STB_CISendRecordStart and before a call to STB_CISendRecordStop).

The licence must be stored on the host and sent during playback to the module using CIP_SendCicamLicence.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) program_number - the program number licence_status - licence status uri - usage rules structure for the recording licence - the CICAM licence (or NULL if not required) licence_len - licence length in bytes

Returns: Nothing

void STB_CINotifyRecordStartStatus	(	U8BIT	slot_id,
		U8BIT	status
	)

Function Name: STB_CINotifyRecordStartStatus

Description: This function is called by the CI+ stack to send the record start status to the host. This function should be called in response to STB_CISendRecordStart.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) status - record start status

Returns: Nothing

void STB_CINotifyRecordStopStatus	(	U8BIT	slot_id,
		U8BIT	status
	)

Function Name: STB_CINotifyRecordStopStatus

Description: This function is called by the CI+ stack to send the record stop status to the host. This function should be called in response to STB_CISendRecordStop.

Parameters: slot_id - zero-based CI slot identifier (0, 1, ...) status - record stop status

Returns: Nothing

U8BIT STB_CINotifySRM	(	U8BIT	slot_id,
		E_STB_SRM_DATA_TYPE	srm_type,
		U8BIT *	data,
		U16BIT	len
	)

This function is called by the CI+ stack to send an SRM (System Renewability Message) to the host. SRM data files perform the function of blacklist for HDCP.

Parameters

slot_id	zero-based CI slot identifier (0, 1, ...)
srm_type	the type of data in data field, for example DHCP or DTCP
data	SRM data
len	size of SRM data in bytes

Returns: STB_CI_SRM_OK STB_CI_SRM_NO_CC_SUPPORT STB_CI_SRM_HOST_BUSY STB_CI_SRM_NOT_REQUIRED

void STB_CINotifyURI	(	U8BIT	slot_id,
		U16BIT	program_number,
		S_STB_CI_URI *	uri
	)

Handle URI (usage rules information)

Parameters

slot_id	- slot ID
program_number	- program number
uri	- the URI

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation