Source release 19.3.0

oemcrypto/include/OEMCryptoCENC.h

@@ -3,7 +3,7 @@
 // License Agreement.
 
 /**
- * @mainpage OEMCrypto API v19.2
+ * @mainpage OEMCrypto API v19.3
  *
  * OEMCrypto is the low level library implemented by the OEM to provide key and
  * content protection, usually in a separate secure memory or process space. The
@@ -746,6 +746,7 @@ typedef enum OEMCrypto_SignatureHashAlgorithm {
 #define OEMCrypto_UseSecondaryKey             _oecc152
 #define OEMCrypto_MarkOfflineSession          _oecc153
 #define OEMCrypto_WrapClearPrivateKey         _oecc154
+#define OEMCrypto_SetSessionUsage             _oecc155
 // clang-format on
 
 /// @addtogroup initcontrol
@@ -1939,6 +1940,33 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session,
                                          uint8_t* key_token,
                                          size_t* key_token_length);
 
+/**
+ * Sets the session's usage information and scrambling mode, allowing the
+ * descrambler to be set up to decode one or more streams encrypted by the
+ * Conditional Access System (CAS). This method is currently used exclusively by
+ * CAS.
+ *
+ * @param[in] session: session id.
+ * @param[in] intent: session usage information. A constant defined by MediaCaS.
+ * @param[in] mode: scrambling mode. A constant defined by MediaCaS.
+ *
+ * @retval OEMCrypto_SUCCESS on success
+ * @retval OEMCrypto_ERROR_INVALID_SESSION
+ * @retval OEMCrypto_ERROR_INVALID_CONTEXT
+ * @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
+ *
+ * @threading
+ *   This is a "Session Function" and may be called simultaneously with session
+ *   functions for other sessions but not simultaneously with other functions
+ *   for this session. It is as if the CDM holds a write lock for this session,
+ *   and a read lock on the OEMCrypto system.
+ *
+ * @version
+ *   This method is new in API version 19.
+ */
+OEMCryptoResult OEMCrypto_SetSessionUsage(OEMCrypto_SESSION session,
+                                          uint32_t intent, uint32_t mode);
+
 /// @}
 
 /// @addtogroup decryption
@@ -2236,10 +2264,20 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session,
  * usually be non-zero. This mode allows devices to decrypt FMP4 HLS content,
  * SAMPLE-AES HLS content, as well as content using the DASH 'cbcs' scheme.
  *
- * The skip field of OEMCrypto_CENCEncryptPatternDesc may also be zero. If
- * the skip field is zero, then patterns are not in use and all crypto blocks
- * in the protected part of the subsample are encrypted. It is not valid for
- * the encrypt field to be zero.
+ * The skip field of OEMCrypto_CENCEncryptPatternDesc may be zero. If the skip
+ * field is zero, then patterns are not in use and all crypto blocks in the
+ * protected part of the subsample are encrypted, except for any partial crypto
+ * blocks at the end. The most common pattern with a skip field of zero is
+ * (10,0), but all patterns with a skip field of zero are functionally the same.
+ *
+ * If the skip field of OEMCrypto_CENCEncryptPatternDesc is zero, the encrypt
+ * field may also be zero. This pattern sometimes appears in content,
+ * particularly in audio tracks. This (0,0) pattern should be treated as
+ * equivalent to the pattern (10,0). e.g. All complete crypto blocks should be
+ * decrypted.
+ *
+ * It is not valid for the encrypt field of OEMCrypto_CENCEncryptPatternDesc to
+ * be zero if the skip field is non-zero.
  *
  * The length of a crypto block in AES-128 is 16 bytes. In the 'cbcs' scheme,
  * if the protected part of a subsample has a length that is not a multiple