Wasabi ExpressPlay SDK for Desktop Systems  1.23.0
Functions
WSB_MediaFile Class

Media file information access. More...

Functions

WSB_EXPORT WSB_Result WSB_MediaFile_Open (const char *name, const char *mime_type, WSB_MediaFile **file)
 Opens the specified media file and creates a WSB_MediaFile object referencing it. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetProtectionType (WSB_MediaFile *file, WSB_MediaFileProtectionType *type)
 Gets the type of protection on the specified media file, which may be none (indicated as WSB_PROTECTION_TYPE_CLEAR_TEXT). More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetMetadata (WSB_MediaFile *file, SHI_Attribute **metadata)
 Returns an attribute list containing all the metadata for the specified media file. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetProgress (WSB_MediaFile *file, WSB_FileProgress *progress)
 Gets file progress information, indicating how many bytes of the file are available, and the total number of bytes in the file. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_SetLicense (WSB_MediaFile *file, const void *license_data, WSB_Size license_data_size)
 Attempts to write the given license into the specified file. More...
 
WSB_EXPORT const char * WSB_MediaFile_GetContentId (WSB_MediaFile *file)
 Returns the content ID for the content in the specified media file. More...
 
WSB_EXPORT const char * WSB_MediaFile_GetContentType (WSB_MediaFile *file)
 Gets the specified media file's content type as a MIME type. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetMediaInfo (WSB_MediaFile *file, WSB_MediaInfo *media_info)
 Gets basic information, such as media type, format, and so on, about the specified media file. More...
 
WSB_EXPORT WSB_Cardinal WSB_MediaFile_GetTrackCount (WSB_MediaFile *file)
 Returns the number of tracks in the specified media file. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetTrackInfo (WSB_MediaFile *file, WSB_Ordinal index, WSB_TrackInfo **track_info)
 Gets information about a specified track. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetLicense (WSB_MediaFile *file, SHI_Data **license)
 Gets the license from the metadata attached to the specified media file. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetRightsIssuerUrls (WSB_MediaFile *file, SHI_Attribute **ri_urls)
 Gets the right issuer URLs from the specified media file. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_GetSilentLicenseAcquisitionUrls (WSB_MediaFile *file, SHI_Attribute **slas)
 Gets the silent license acquisition URLs from the specified media file. More...
 
WSB_EXPORT const char * WSB_MediaFile_GetName (WSB_MediaFile *file)
 Gets the name of the media file, which was passed in during creation. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_WaitUntilReady (WSB_MediaFile *file, WSB_UInt32 file_ready_timeout_ms)
 Waits until the file is ready or the specified timeout has been reached. More...
 
WSB_EXPORT WSB_Result WSB_MediaFile_Close (WSB_MediaFile *file)
 Closes the media file and releases the WSB_MediaFile object referencing it. More...
 

Detailed Description

Media file information access.

Function Documentation

◆ WSB_MediaFile_Close()

WSB_EXPORT WSB_Result WSB_MediaFile_Close ( WSB_MediaFile file)

Closes the media file and releases the WSB_MediaFile object referencing it.

No WSB_TrackInfo methods may be called for tracks in this file after calling this method; release all WSB_TrackInfo objects referencing tracks in this file by calling WSB_TrackInfo_Release prior to calling this method.

Parameters
fileThe WSB_MediaFile to be released.

◆ WSB_MediaFile_GetContentId()

WSB_EXPORT const char* WSB_MediaFile_GetContentId ( WSB_MediaFile file)

Returns the content ID for the content in the specified media file.

This is only relevant for files like DCF files that have a single content ID, reported at the file level. For files that do not have a content ID at the file level (e.g., PDCF files, which report content IDs on a per-track basis), this method returns NULL.

Parameters
fileThe WSB_MediaFile whose content ID will be returned.
Returns
A string containing the content ID, or NULL, if the media file is not the type of file that keeps track of a single content ID at the file level.

◆ WSB_MediaFile_GetContentType()

WSB_EXPORT const char* WSB_MediaFile_GetContentType ( WSB_MediaFile file)

Gets the specified media file's content type as a MIME type.

The MIME type represents the media data BEFORE protection. WSB_CONTENT_TYPE_* constants are defined for this property.

NOTE: MIME types are case-insensitive.

Parameters
fileThe WSB_MediaFile whose content type will be returned.
Returns
A string containing the MIME content type.

◆ WSB_MediaFile_GetLicense()

WSB_EXPORT WSB_Result WSB_MediaFile_GetLicense ( WSB_MediaFile file,
SHI_Data **  license 
)

Gets the license from the metadata attached to the specified media file.

This method returns WSB_ERROR_NO_SUCH_ITEM if no license is found.

Parameters
fileThe WSB_MediaFile representing the media file.
licenseAddress of a SHI_Data pointer that will be set to refer to the SHI_Data object created if a license is found. (If not, the pointer will be set to NULL.) The SHI_Data object will contain a SHI_ByteArray containing the license bytes. The SHI_Data must be freed, by calling SHI_Data_Release, when it is no longer needed.

◆ WSB_MediaFile_GetMediaInfo()

WSB_EXPORT WSB_Result WSB_MediaFile_GetMediaInfo ( WSB_MediaFile file,
WSB_MediaInfo media_info 
)

Gets basic information, such as media type, format, and so on, about the specified media file.

Parameters
fileThe WSB_MediaFile for which basic information will be returned.
media_infoThe basic file information.

◆ WSB_MediaFile_GetMetadata()

WSB_EXPORT WSB_Result WSB_MediaFile_GetMetadata ( WSB_MediaFile file,
SHI_Attribute **  metadata 
)

Returns an attribute list containing all the metadata for the specified media file.

Parameters
fileThe WSB_MediaFile whose metadata will be returned.
metadataAddress of a SHI_Attribute pointer that will, upon successful return, be set to point to a SHI_Attribute object containing the metadata. The SHI_Attribute type is SHI_ATTRIBUTE_TYPE_LIST, and each child of the list is an attribute for a single metadata item. See the WSB_FILE_METADATA_ constant definitions for the metadata attribute names and the types for their values. The caller is responsible for calling SHI_Attribute_Release to release the SHI_Attribute object when it is no longer needed. If the metadata attributes cannot be found or an error occurs, no SHI_Attribute object is created, and the SHI_Attribute pointer is set to NULL.

◆ WSB_MediaFile_GetName()

WSB_EXPORT const char* WSB_MediaFile_GetName ( WSB_MediaFile file)

Gets the name of the media file, which was passed in during creation.

Parameters
fileThe WSB_MediaFile representing the media file whose name will be returned.
Returns
The name of the media file.

◆ WSB_MediaFile_GetProgress()

WSB_EXPORT WSB_Result WSB_MediaFile_GetProgress ( WSB_MediaFile file,
WSB_FileProgress progress 
)

Gets file progress information, indicating how many bytes of the file are available, and the total number of bytes in the file.

If the type of media doesn't enable gathering the total size information, such as in streaming, the total size reported will be zero, but no error will be returned.

Parameters
fileThe WSB_MediaFile whose progress will be returned.
[out]progressThe progress information.

◆ WSB_MediaFile_GetProtectionType()

WSB_EXPORT WSB_Result WSB_MediaFile_GetProtectionType ( WSB_MediaFile file,
WSB_MediaFileProtectionType type 
)

Gets the type of protection on the specified media file, which may be none (indicated as WSB_PROTECTION_TYPE_CLEAR_TEXT).

Parameters
fileThe WSB_MediaFile whose protection type will be returned.
[out]typeThe protection type.

◆ WSB_MediaFile_GetRightsIssuerUrls()

WSB_EXPORT WSB_Result WSB_MediaFile_GetRightsIssuerUrls ( WSB_MediaFile file,
SHI_Attribute **  ri_urls 
)

Gets the right issuer URLs from the specified media file.

This method returns WSB_ERROR_NO_SUCH_ITEM if no right issuer URLS found.

Parameters
fileThe WSB_MediaFile object referencing the media file whose rights issuer URLs will be returned.
ri_urlsAddress of a SHI_Attribute pointer that will be set to refer to the SHI_Attribute object created if rights issuer URLs are found. (If not, the pointer will be set to NULL.) The SHI_Attribute object will be of type SHI_ATTRIBUTE_TYPE_LIST. The names of the children in the list will be content IDs, and their values will each be of type SHI_ATTRIBUTE_TYPE_STRING and contain the rights issuer URL associated with the content ID. The caller is responsible for releasing the SHI_Attribute when no longer needed (the children will be automatically released) by calling SHI_Attribute_Release.

◆ WSB_MediaFile_GetSilentLicenseAcquisitionUrls()

WSB_EXPORT WSB_Result WSB_MediaFile_GetSilentLicenseAcquisitionUrls ( WSB_MediaFile file,
SHI_Attribute **  slas 
)

Gets the silent license acquisition URLs from the specified media file.

This method returns WSB_ERROR_NO_SUCH_ITEM if no silent license acquisition URLs are found.

Parameters
fileThe WSB_MediaFile object referencing the media file whose silent license acquisition URLs will be returned.
slasAddress of a SHI_Attribute pointer that will be set to refer to the SHI_Attribute object created if silent license acquisition URLs are found. (If not, the pointer will be set to NULL.) The SHI_Attribute object will be of type SHI_ATTRIBUTE_TYPE_LIST. The names of the children in the list will be content IDs, and their values will each be of type SHI_ATTRIBUTE_TYPE_STRING and contain the silent license acquisition URL associated with the content ID. The caller is responsible for releasing the SHI_Attribute when no longer needed (the children will be automatically released) by calling SHI_Attribute_Release.

◆ WSB_MediaFile_GetTrackCount()

WSB_EXPORT WSB_Cardinal WSB_MediaFile_GetTrackCount ( WSB_MediaFile file)

Returns the number of tracks in the specified media file.

Parameters
fileThe WSB_MediaFile whose number of tracks will be returned.
Returns
The number of tracks.

◆ WSB_MediaFile_GetTrackInfo()

WSB_EXPORT WSB_Result WSB_MediaFile_GetTrackInfo ( WSB_MediaFile file,
WSB_Ordinal  index,
WSB_TrackInfo **  track_info 
)

Gets information about a specified track.

Parameters
fileThe WSB_MediaFile for which information about a specific track will be returned.
indexThe track index.
track_infoAddress of a WSB_TrackInfo pointer that will be set to point to a WSB_TrackInfo object for the specified track. The caller is responsible for releasing the WSB_TrackInfo object by calling WSB_TrackInfo_Release when it is no longer needed. If the track information cannot be returned, no WSB_TrackInfo object is created, and the WSB_TrackInfo pointer is set to NULL.

◆ WSB_MediaFile_Open()

WSB_EXPORT WSB_Result WSB_MediaFile_Open ( const char *  name,
const char *  mime_type,
WSB_MediaFile **  file 
)

Opens the specified media file and creates a WSB_MediaFile object referencing it.

When access to the file is no longer needed, the WSB_MediaFile_Close method should be called to close the file and release the WSB_MediaFile object. Handles cleartext and Marlin protected media files in DCF and PDCF container formats, MPEG-2 transport streams in BBTS format, cleartext and Marlin protected DASH and HLS playlists, and MS3 URLs with c-URLs pointing to any of the above mentioned Marlin protected formats

Note: This function directly opens the media file (whether local or on network) and parses it to get the media information. This function does not evaluate any licenses. This function does not support MS3 URLs containing an Authenticator as these URLs require the MS3 license to be first evaluated in order to obtain the value of the Authenticator from the SAS

Parameters
nameA filename or an HTTP URL specifying the file location, e.g., file:///media/movie.mp4 or http://host.com:port/file.mp4.
mime_typeThe MIME type, if known, or NULL if unknown.
fileAddress of a WSB_MediaFile pointer that will be set to refer to the newly created WSB_MediaFile object.

◆ WSB_MediaFile_SetLicense()

WSB_EXPORT WSB_Result WSB_MediaFile_SetLicense ( WSB_MediaFile file,
const void *  license_data,
WSB_Size  license_data_size 
)

Attempts to write the given license into the specified file.

This will not work for streamed media.

Parameters
fileThe WSB_MediaFile referencing the file into which the license should be embedded.
license_dataThe license data.
license_data_sizeThe length, in bytes, of license_data.

◆ WSB_MediaFile_WaitUntilReady()

WSB_EXPORT WSB_Result WSB_MediaFile_WaitUntilReady ( WSB_MediaFile file,
WSB_UInt32  file_ready_timeout_ms 
)

Waits until the file is ready or the specified timeout has been reached.

Parameters
fileThe media file.
file_ready_timeout_msTimeout in milliseconds to wait until the file is ready.