Event.protection


Description:

[ CCode ( has_construct_function = false ) ]
[ Version ( since = "1.6" ) ]
public Event.protection (string system_id, Buffer data, string origin)

Creates a new event containing information specific to a particular protection system (uniquely identified by system_id), by which that protection system can acquire key(s) to decrypt a protected stream.

In order for a decryption element to decrypt media protected using a specific system, it first needs all the protection system specific information necessary to acquire the decryption key(s) for that stream. The functions defined here enable this information to be passed in events from elements that extract it (e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter elements that use it.

Events containing protection system specific information are created using Event.protection, and they can be parsed by downstream elements using parse_protection.

In Common Encryption, protection system specific information may be located within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) boxes; it may also be contained in ContentProtection elements within MPEG DASH MPDs. The events created by Event.protection contain data identifying from which of these locations the encapsulated protection system specific information originated. This origin information is required as some protection systems use different encodings depending upon where the information originates.

The events returned by Event.protection are implemented in such a way as to ensure that the most recently-pushed protection info event of a particular origin and system_id will be stuck to the output pad of the sending element.

Parameters:

system_id

a string holding a UUID that uniquely identifies a protection system.

data

a Buffer holding protection system specific information. The reference count of the buffer will be incremented by one.

origin

a string indicating where the protection information carried in the event was extracted from. The allowed values of this string will depend upon the protection scheme.

Returns:

a PROTECTION event, if successful; null if unsuccessful.