Wasabi ExpressPlay SDK for Embedded Systems  1.23.0
Data Structures | Macros | Typedefs | Functions
EMB_Storage Class

Performs various operations on the store. More...

Data Structures

struct  XPCA_Package
 The following structure defines the characteristics of a package. More...
 
struct  XPCA_Content
 An XPCA_Content type describes the status of a protected content with regard to the license associated with it. More...
 
struct  XPCA_PackageContentArray
 This is a variable-size array of XPCA_Content data. More...
 
struct  XPCA_UintArray
 This is a variable-size array of uint32_t data which are package ids returned by relevant EPD storage queries. More...
 

Macros

#define INVALID_EPD_STORAGE   (void *)NULL
 Invalid value for the EPD_Storage opaque type. More...
 
#define MIN_XPCA_PACKAGE_TYPE   1
 
#define MAX_XPCA_PACKAGE_TYPE   15
 
#define ANY_XPCA_PACKAGE_TYPE   0
 
#define MIN_XPCA_PACKAGE_ACCESS   1
 
#define MAX_XPCA_PACKAGE_ACCESS   15
 
#define ANY_XPCA_PACKAGE_ACCESS   0
 
#define XPCA_CONTENT_STATUS_IS_IN_EPD(status)   (((status) & 0x01) == 0x01)
 XPCA_Content status is a bitmask field, more than one bit can be set. More...
 
#define XPCA_CONTENT_STATUS_IS_IN_EPL(status)   (((status) & 0x02) == 0x02)
 
#define XPCA_CONTENT_STATUS_CHECK_ERROR(status)   (((status) & 0x80) == 0x80)
 
#define EPD_INFINITE_TIME   ((time_t)(-1))
 The value of an infinite duration for a package. More...
 

Typedefs

typedef struct EMB_Storage EMB_Storage
 An EMB_Storage object represents information about EMB object storage. More...
 
typedef void * EPD_Storage
 Entitlement Package Description (EPD) specific operations. More...
 
typedef int XPCA_package_type_t
 Type of package. More...
 
typedef int XPCA_package_access_t
 Accessibility of a package. More...
 

Functions

EMB_EXPORT EMB_Result EMB_Storage_Open (EMB_Storage **storage)
 Opens the EMBB storage and creates a new EMB_Storage object to refer to it. More...
 
EMB_EXPORT EMB_Result EMB_Storage_FindItemsByIds (EMB_Storage *storage, EMB_ItemType item_type, EMB_UInt32 id_count, EMB_ByteArray **ids, EMB_Bool hash_content_ids, SHI_Data **items)
 Finds in the EMBB Storage the items that contain the specified id(s). More...
 
EMB_EXPORT EMB_Result EMB_Storage_FindItemsTargetAtGroup (EMB_Storage *storage, EMB_ItemType item_type, EMB_ByteArray group_id, SHI_Data **items)
 
EMB_EXPORT EMB_Result EMB_Storage_GetItemByItemId (EMB_Storage *storage, EMB_ItemType item_type, EMB_UInt32 item_id, SHI_Data **item)
 Finds the item in the EMBB Storage that contain the specified item_id. More...
 
EMB_EXPORT EMB_Result EMB_Storage_RemoveItemsByIds (EMB_Storage *storage, EMB_ItemType item_type, EMB_UInt32 id_count, EMB_ByteArray **ids)
 Removes the list of the items specified in the EMB_ByteArray from the EMBB Storage. More...
 
EMB_EXPORT EMB_Result EMB_Storage_RemoveItem (EMB_Storage *storage, EMB_ItemType item_type, EMB_UInt32 item_id)
 Removes from the EMBB Storage the item with a specified item ID. More...
 
EMB_EXPORT EMB_Result EMB_Storage_ExpungeExpiredItems (EMB_Storage *storage, EMB_ItemType item_type)
 Expunges all expired items of item type from the EMBB storage. More...
 
EMB_EXPORT EMB_Result EMB_Storage_Close (EMB_Storage *storage)
 Closes the EMBB storage and releases the specified EMB_Storage object referring to it. More...
 
EMB_EXPORT EMB_Result EMB_Storage_Wipe ()
 Wipes the EMBB and license storage by deleting the underlying database. More...
 
EMB_EXPORT EMB_Result EMB_Storage_GetEntitlementStorage (EMB_Storage *storage, EPD_Storage *epds)
 Factory function to create an handle to access the EPD_Storage database. More...
 
EMB_EXPORT EMB_Result EMB_Storage_ReleaseEntitlementStorage (EMB_Storage *storage, EPD_Storage epds)
 Release the handle to the EPD_storage database. More...
 
EMB_EXPORT EMB_Result EMB_Storage_CleanupEntitlementStorage (EMB_Storage *storage, time_t expirationDate)
 Remove from the EMBB storage EPD entries that have expired. More...
 
EMB_EXPORT EMB_Result EPD_Storage_GetPackageById (EPD_Storage epds, uint32_t id, XPCA_Package **package)
 This API searches the EPD_Storage for a single package definition corresponding to the given package id. More...
 
EMB_EXPORT EMB_Result EPD_Storage_GetPackagesForContent (EPD_Storage epds, uint32_t lcid, XPCA_package_type_t type, XPCA_package_access_t access, XPCA_UintArray **array)
 This API searches the EPD_Storage for packages including the entitlement item (logical content id) lcid and whose access and type match the input criteria access and type. More...
 
EMB_EXPORT EMB_Result EPD_Storage_GetPackages (EPD_Storage epds, XPCA_package_type_t type, XPCA_package_access_t access, XPCA_UintArray **array)
 This API searches the EPD_Storage for packages whose access and type match the input criteria access and type. More...
 
EMB_EXPORT EMB_Result EPD_Storage_GetContentForPackage (EPD_Storage epds, uint32_t id, XPCA_PackageContentArray **array)
 This API searches the EPD_Storage and the EMB_Storage for the content access definition XPCA_ContentAccess of all the content ids associated with the package corresponding to a given package id. More...
 
EMB_EXPORT EMB_Result EPD_Storage_ReleasePackage (EPD_Storage epds, XPCA_Package *package)
 Release a XPCA_Package result set returned by a successful call to EPD_Storage_GetPackageById. More...
 
EMB_EXPORT EMB_Result EPD_Storage_ReleaseUintArray (EPD_Storage epds, XPCA_UintArray *array)
 Release a XPCA_UintArray result set returned by a successful call to EPD_Storage_GetPackages or EPD_Storage_GetPackagesForContent. More...
 
EMB_EXPORT EMB_Result EPD_Storage_ReleasePackageContentArray (EPD_Storage epds, XPCA_PackageContentArray *array)
 Release a XPCA_PackageContentArray result set returned by a successful call to EPD_Storage_GetContentForPackage. More...
 

Detailed Description

Performs various operations on the store.

Macro Definition Documentation

◆ ANY_XPCA_PACKAGE_ACCESS

#define ANY_XPCA_PACKAGE_ACCESS   0

◆ ANY_XPCA_PACKAGE_TYPE

#define ANY_XPCA_PACKAGE_TYPE   0

◆ EPD_INFINITE_TIME

#define EPD_INFINITE_TIME   ((time_t)(-1))

The value of an infinite duration for a package.

◆ INVALID_EPD_STORAGE

#define INVALID_EPD_STORAGE   (void *)NULL

Invalid value for the EPD_Storage opaque type.

◆ MAX_XPCA_PACKAGE_ACCESS

#define MAX_XPCA_PACKAGE_ACCESS   15

◆ MAX_XPCA_PACKAGE_TYPE

#define MAX_XPCA_PACKAGE_TYPE   15

◆ MIN_XPCA_PACKAGE_ACCESS

#define MIN_XPCA_PACKAGE_ACCESS   1

◆ MIN_XPCA_PACKAGE_TYPE

#define MIN_XPCA_PACKAGE_TYPE   1

◆ XPCA_CONTENT_STATUS_CHECK_ERROR

#define XPCA_CONTENT_STATUS_CHECK_ERROR (   status)    (((status) & 0x80) == 0x80)

◆ XPCA_CONTENT_STATUS_IS_IN_EPD

#define XPCA_CONTENT_STATUS_IS_IN_EPD (   status)    (((status) & 0x01) == 0x01)

XPCA_Content status is a bitmask field, more than one bit can be set.

The following macros evaluate the bitmask to a boolean. The meaning of the bitmask is the following:

  • XPCA_CONTENT_STATUS_IS_IN_EPD true means that the content id hash is located in the EPD
  • XPCA_CONTENT_STATUS_IS_IN_EPL true means that there is an EPL for that content id hash
  • XPCA_CONTENT_STATUS_CHECK_ERROR true means that group ids between package and license are inconsistent

◆ XPCA_CONTENT_STATUS_IS_IN_EPL

#define XPCA_CONTENT_STATUS_IS_IN_EPL (   status)    (((status) & 0x02) == 0x02)

Typedef Documentation

◆ EMB_Storage

typedef struct EMB_Storage EMB_Storage

An EMB_Storage object represents information about EMB object storage.

◆ EPD_Storage

typedef void* EPD_Storage

Entitlement Package Description (EPD) specific operations.

An opaque type representing the EPD_Storage object

◆ XPCA_package_access_t

typedef int XPCA_package_access_t

Accessibility of a package.

This is an opaque data type that is associated with a package by the operator and is meaningful only to some specific applications.Valid range is [1 - 15], 0 reserved of ANY_ACCESS in the queries

◆ XPCA_package_type_t

typedef int XPCA_package_type_t

Type of package.

This is an opaque data type that is associated with a package by the operator and is meaningful only to some specific applications.Valid range is [1 - 15], 0 rerserved for ANY_TYPE in the queries

Function Documentation

◆ EMB_Storage_CleanupEntitlementStorage()

EMB_EXPORT EMB_Result EMB_Storage_CleanupEntitlementStorage ( EMB_Storage storage,
time_t  expirationDate 
)

Remove from the EMBB storage EPD entries that have expired.

This function returns:

  • EMB_ERROR_INVALID_PARAMETERS if storage argument is NULL or \ expirationDate is invalid
  • EMB_SUCCESS in case of success
Parameters
storageAn EMBB storage.
expirationDateAn UTC time indicating the expiration date

◆ EMB_Storage_Close()

EMB_EXPORT EMB_Result EMB_Storage_Close ( EMB_Storage storage)

Closes the EMBB storage and releases the specified EMB_Storage object referring to it.

Parameters
storageAn EMBB storage.

◆ EMB_Storage_ExpungeExpiredItems()

EMB_EXPORT EMB_Result EMB_Storage_ExpungeExpiredItems ( EMB_Storage storage,
EMB_ItemType  item_type 
)

Expunges all expired items of item type from the EMBB storage.

If the item type is EMB_IT_UNKNOWN, the expunge operation is performed on all EPL and GKO items.

Parameters
storageAn EMBB storage
item_typeThe item type to check for expiration. Supported item types are EMB_IT_EPL, EMB_IT_GKO and EMB_IT_UNKNOWN.

◆ EMB_Storage_FindItemsByIds()

EMB_EXPORT EMB_Result EMB_Storage_FindItemsByIds ( EMB_Storage storage,
EMB_ItemType  item_type,
EMB_UInt32  id_count,
EMB_ByteArray **  ids,
EMB_Bool  hash_content_ids,
SHI_Data **  items 
)

Finds in the EMBB Storage the items that contain the specified id(s).

If the item type is EMB_IT_UNKNOWN, the lookup operation is performed on all EPL, (referenced) GKO items. Lookup for specific item type is also supported by passing in appropriate item type.

The querying logic when searching for a valid license with a content id using EMB_IT_UNKNOWN item type is done as followed:

look for EPL item first by content id
   - if found EPL, check for EPL expiration date
   - if still valid (not expired or no expiration date), check if EPL
     references a group id
   - if EPL does not reference a group key object id, return success with
     EPL
   - if EPL references a group id, look for GKO by group key object id
   - if found group key object id, check for GKO expiration date
   - if still valid (not expired or no expiration date), return success
     with both EPL and GKO

If a request is made with a zero id count, all items in the EMBB Storage will be returned.

This method returns EMB_ERROR_STORAGE_NO_ITEM if no match was found, or EMB_ERROR_STORAGE_LOOKUP if an error occurred during lookup.

Parameters
storageAn EMBB Storage
item_typeThe item type to check for expiration. Supported item types are EMB_IT_EPL, EMB_IT_GKO and EMB_IT_UNKNOWN.
id_countNumber of ids specified in the next argument.
idsThe ids used to perform lookup. For EPL,
  1. it expects the caller to pass in clear content id when hash_content_ids is FALSE
  2. value of hashed content id in hexadecimal(40 characters) when hash_content_ids is TRUE For GKO, it expects the caller to pass in group id.
hash_content_idsTRUE indicates that the ids are hashed content ids, otherwise they are clear. Note that the hash_content_ids should be TRUE only for an EPL item_type and in case the content ID is known by its hash value (it is an invalid parameter if hash_content_ids is true and the item_type argument is not EMB_IT_EPL).
itemsAddress of a SHI_Data pointer that will, upon successful return, be set to point to a SHI_Data object representing an array of one or more items. This SHI_Data object will have a value of type SHI_DATA_TYPE_ARRAY, where each element in the array will be of type SHI_DATA_TYPE_POINTER, so its value is a SHI_TypedPointer. Each SHI_TypedPointer structure in the array will have its type_id field set to EMB_TYPE_ID_EMBB_OBJ and its pointer field pointing to an EMB_Item. The caller is responsible for calling SHI_Data_Release to release the SHI_Data object containing the array when it is no longer needed. The EMB_Object pointed to by the array are no longer valid and should not be accessed after the caller has called SHI_Data_Release.

◆ EMB_Storage_FindItemsTargetAtGroup()

EMB_EXPORT EMB_Result EMB_Storage_FindItemsTargetAtGroup ( EMB_Storage storage,
EMB_ItemType  item_type,
EMB_ByteArray  group_id,
SHI_Data **  items 
)

◆ EMB_Storage_GetEntitlementStorage()

EMB_EXPORT EMB_Result EMB_Storage_GetEntitlementStorage ( EMB_Storage storage,
EPD_Storage epds 
)

Factory function to create an handle to access the EPD_Storage database.

This function returns:

  • EMB_ERROR_INVALID_PARAMETERS if the arguments are NULL
  • EMB_ERROR_OUT_OF_MEMORY
  • EMB_SUCCESS in case of success
Parameters
storageAn EMBB storage.
epdsA mandatory address of an handle to the EPD storage that is returned in case of success

◆ EMB_Storage_GetItemByItemId()

EMB_EXPORT EMB_Result EMB_Storage_GetItemByItemId ( EMB_Storage storage,
EMB_ItemType  item_type,
EMB_UInt32  item_id,
SHI_Data **  item 
)

Finds the item in the EMBB Storage that contain the specified item_id.

Lookup for specific item type is also supported by passing in appropriate item type.

The querying logic when searching for an item id using EMB_IT_UNKNOWN item type is done as followed:

a) look for EPL item first by id
   - if found then return it

c) look for GKO item by id
   - return it if found

This method returns EMB_ERROR_STORAGE_NO_ITEM if no match was found, or EMB_ERROR_STORAGE_LOOKUP if an error occurred during lookup.

Parameters
storageAn EMBB Storage
item_typeSupported item types are EMB_IT_EPL, EMB_IT_GKO and EMB_IT_UNKNOWN.
item_idThe item id to search for.
itemAddress of a SHI_Data pointer that will, upon successful return, be set to point to a SHI_Data object representing an item. This SHI_Data object will have a value of type SHI_DATA_TYPE_POINTER, so its value is a SHI_TypedPointer. The SHI_TypedPointer structure will have its type_id field set to EMB_TYPE_ID_EMBB_OBJ and its pointer field pointing to a EMB_Item object. The caller is responsible for calling SHI_Data_Release to release the SHI_Data object containing the array when it is no longer needed. The EMB_Object pointed to by the array are no longer valid and should not be accessed after the caller has called SHI_Data_Release.

◆ EMB_Storage_Open()

EMB_EXPORT EMB_Result EMB_Storage_Open ( EMB_Storage **  storage)

Opens the EMBB storage and creates a new EMB_Storage object to refer to it.

If the storage does not exist, this method creates it. The storage must be closed when it is no longer needed. If an error occurs while attempting to open the storage, this method returns EMB_ERROR_STORAGE_OPEN.

Parameters
storageAddress of a pointer that will be set to refer to the storage created.

◆ EMB_Storage_ReleaseEntitlementStorage()

EMB_EXPORT EMB_Result EMB_Storage_ReleaseEntitlementStorage ( EMB_Storage storage,
EPD_Storage  epds 
)

Release the handle to the EPD_storage database.

This function returns:

  • EMB_ERROR_INVALID_PARAMETERS if storage argument is NULL
  • EMB_SUCCESS in case of success
Parameters
storageAn EMBB storage.
epdsAn handle to access Entitlement Package Description storage.

◆ EMB_Storage_RemoveItem()

EMB_EXPORT EMB_Result EMB_Storage_RemoveItem ( EMB_Storage storage,
EMB_ItemType  item_type,
EMB_UInt32  item_id 
)

Removes from the EMBB Storage the item with a specified item ID.

This method returns EMB_ERROR_STORAGE_REMOVE_ITEM if it encounters an error.

Parameters
storageAn EMBB storage.
item_typeThe type of an item.
item_idThe item id for the item to be removed.

◆ EMB_Storage_RemoveItemsByIds()

EMB_EXPORT EMB_Result EMB_Storage_RemoveItemsByIds ( EMB_Storage storage,
EMB_ItemType  item_type,
EMB_UInt32  id_count,
EMB_ByteArray **  ids 
)

Removes the list of the items specified in the EMB_ByteArray from the EMBB Storage.

This method returns EMB_ERROR_STORAGE_NO_ITEM if no item found to remove, or EMB_ERROR_STORAGE_LOOKUP if an error occurred during removal.

It removes the items fetched by EMB_Storage_FindItemsByIds from the EMBB storage.

◆ EMB_Storage_Wipe()

EMB_EXPORT EMB_Result EMB_Storage_Wipe ( )

Wipes the EMBB and license storage by deleting the underlying database.

All items will be lost so only use this method when the storage is corrupted and not recoverable. Call this method only when the EMBB storage is not opened.

◆ EPD_Storage_GetContentForPackage()

EMB_EXPORT EMB_Result EPD_Storage_GetContentForPackage ( EPD_Storage  epds,
uint32_t  id,
XPCA_PackageContentArray **  array 
)

This API searches the EPD_Storage and the EMB_Storage for the content access definition XPCA_ContentAccess of all the content ids associated with the package corresponding to a given package id.

The content may be associated with the package either directly (listed in the Entitlement Package Definition) or indirectly by having the same group as the one for the package. It returns the array of XPCA_Content data in the array parameter if the package exists in the database or NULL otherwise. The array might have 0 size if no content is found for the package; this may happen if a package is associated only with a group and no license have been received yet or if the package is not found in the EPD_Storage.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if a parameter is invalid
  • EMB_ERROR_OUT_OF_MEMORY if a memory allocation failed
  • EMB_ERROR_SQLITE if a SQLite error occurred, enabling log level SEVERE will help troubleshouting the issue
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
idThe id of the package being queried
arrayThe address of a XPCA_PackageContentArray pointer returning the result set of a successful query. It may be NULL. This content array must be freed by calling EPD_Storage_ReleasePackageContentArray.

◆ EPD_Storage_GetPackageById()

EMB_EXPORT EMB_Result EPD_Storage_GetPackageById ( EPD_Storage  epds,
uint32_t  id,
XPCA_Package **  package 
)

This API searches the EPD_Storage for a single package definition corresponding to the given package id.

It returns the package definition in the package parameter or NULL in case the package id is not found.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if a parameter is invalid
  • EMB_ERROR_OUT_OF_MEMORY if a memory allocation failed
  • EMB_ERROR_SQLITE if a SQLite error occurred, enabling log level SEVERE will help troubleshouting the issue
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
idThe id of the package being queried
packageThe address of a XPCA_Package pointer returning the result set of a successful query. Must not be NULL. This package definition must be freed by calling EPD_Storage_ReleasePackage.

◆ EPD_Storage_GetPackages()

EMB_EXPORT EMB_Result EPD_Storage_GetPackages ( EPD_Storage  epds,
XPCA_package_type_t  type,
XPCA_package_access_t  access,
XPCA_UintArray **  array 
)

This API searches the EPD_Storage for packages whose access and type match the input criteria access and type.

It returns the array of their package ids in the array parameter. The array might have 0 size if no matches are found.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if a parameter is invalid
  • EMB_ERROR_OUT_OF_MEMORY if a memory allocation failed
  • EMB_ERROR_SQLITE if a SQLite error occurred, enabling log level SEVERE will help troubleshouting the issue
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
typeThe package type to match or ANY_XPCA_PACKAGE_TYPE if the package type doesn't matter
accessThe package access to match or ANY_XPCA_PACKAGE_ACCESS if the package access doesn't matter
arrayThe address of a XPCA_UintArray pointer returning the result set of a successful query. Must not be NULL. This package id array must be freed by calling EPD_Storage_ReleaseUintArray.

◆ EPD_Storage_GetPackagesForContent()

EMB_EXPORT EMB_Result EPD_Storage_GetPackagesForContent ( EPD_Storage  epds,
uint32_t  lcid,
XPCA_package_type_t  type,
XPCA_package_access_t  access,
XPCA_UintArray **  array 
)

This API searches the EPD_Storage for packages including the entitlement item (logical content id) lcid and whose access and type match the input criteria access and type.

It returns the array of their package ids in the array parameter. The array might have 0 size if no matches are found.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if a parameter is invalid
  • EMB_ERROR_OUT_OF_MEMORY if a memory allocation failed
  • EMB_ERROR_SQLITE if a SQLite error occurred, enabling log level SEVERE will help troubleshouting the issue
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
lcidThe logical content id being queried
typeThe package type to match or ANY_XPCA_PACKAGE_TYPE if the package type doesn't matter
accessThe package access to match or ANY_XPCA_PACKAGE_ACCESS if the package access doesn't matter
arrayThe address of a XPCA_UintArray pointer returning the result set of a successful query. Must not be NULL. This package id array must be freed by calling EPD_Storage_ReleaseUintArray.

◆ EPD_Storage_ReleasePackage()

EMB_EXPORT EMB_Result EPD_Storage_ReleasePackage ( EPD_Storage  epds,
XPCA_Package package 
)

Release a XPCA_Package result set returned by a successful call to EPD_Storage_GetPackageById.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if epds parameter is invalid
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
packageThe result set to be released. It can be NULL.

◆ EPD_Storage_ReleasePackageContentArray()

EMB_EXPORT EMB_Result EPD_Storage_ReleasePackageContentArray ( EPD_Storage  epds,
XPCA_PackageContentArray array 
)

Release a XPCA_PackageContentArray result set returned by a successful call to EPD_Storage_GetContentForPackage.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if epds argument is invalid
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
arrayThe result set to be released. It can be NULL

◆ EPD_Storage_ReleaseUintArray()

EMB_EXPORT EMB_Result EPD_Storage_ReleaseUintArray ( EPD_Storage  epds,
XPCA_UintArray array 
)

Release a XPCA_UintArray result set returned by a successful call to EPD_Storage_GetPackages or EPD_Storage_GetPackagesForContent.

This function returns:

  • EMB_SUCCESS in case of success
  • EMB_ERROR_INVALID_PARAMETERS if epds argument is invalid
Parameters
epdsThe handle to an EPD_Storage object. Must be different from INVALID_EPD_STORAGE
arrayThe result set to be released. It can be NULL