ILMKlvParser Interface

The ILMKlvParser interface is provided by the LEAD MPEG-2 Transport Demultiplexer to simplify the task of parsing KLV data. It can be obtained from the demultiplexer by calling ILMMpgDmx::GetKlvParser.

Data types:

typedef enum SearchKeyConstants
{
   SearchKey_Exact = 1, /* Find the exact key only. The key version number must match. */
   SearchKey_AnyVersion = 2, /* Ignore the version number when doing the search. */
   SearchKey_DesignatorOnly = 3, /* Find the key by the designator only. Ignore the key representation and version number */
} SearchKeyConstants;

 

typedef enum ErrorConstants
{
   KLV_KEY_NOT_FOUND = 0x80050010, /* The KLV key was not found */
   KLV_BAD_KEY = 0x80050011, /* The KLV key is bad */
} ErrorConstants;

 

Interface Properties:

 

Type

Property name

Description

long

Count

The number of complete top-level KLV keys contained in the internal interface buffer. An incomplete KLV key will not be included in the count.

Interface Methods:

HRESULT AddData(VARIANT *pData, long lDataSize, long Flags);

Parameters

pData

Pointer to a variant containing the private data.

lDataSize

The size of data contained in pData.

Flags

The flags value describing the position of this data packet within the private data sample. See the DataFlagConstants enumeration for a list of possible flags.

Description

This method can be used to begin parsing private data containing KLV packets. After calling this function, you can parse the data by calling GetKey, FindKey and FindKeyStr.

This method is designed to be called in response to a call to ILMMpgDmxCallback::DataAvailable. You can call AddData with the corresponding parameters from ILMMpgDmxCallback::DataAvailable (pData, lData, Flags).

You should call this function ONLY if ILMMpgDmxCallback::DataAvailable is called and Flags has DataFlag_IsKLV set. Although you can call this function if the flag in question is not set, that will be pointless because the parsing function will most likely fail.

If you do not pass the data received from ILMMpgDmxCallback::DataAvailable and you want to pass as pData a variant that you create, follow the following rules:

If Flag_BeginSample is set in Flags, AddData will clear the previous data from the buffer. If Flag_BeginSample is not set, the new data is appended to the data set by the previous AddData call.

Example:

AddData(var1, 2048, DataFlag_BeginSample); /* Now we have 2048 bytes worth of data */

AddData(var2, 2048, DataFlag_EndSample); /* Now we have 4096 bytes worth of data, made up of data contained in var1 and var2 */

AddData(var3, 2048, DataFlag_BeginSample); /* Now we have 2048 bytes worth of data, made up of data contained in var3. The previous 4096 bytes have been discarded because DataFlag_BeginSample was passed to AddData */

Returns

S_OK if successful, < 0 if an error occurred.

            Common error codes:

E_POINTER                  [0x80004003] pData is NULL

E_INVALIDARG             [0x80070057] pData is not a byte array variant

 

HRESULT GetKey(long keyIndex, VARIANT *pKey, VARIANT *pKeyData, long *pDataSize);

Parameters

keyIndex

The index of the key to retrieve. The index is 0-based, so allowed values are 0..Count – 1

pKey

Pointer to a VARIANT that will be updated with a key describing the data. The key will be a 16-byte array describing the variant data. This key tells you how to interpret the key data contained in pKeyData.

pKeyData

Pointer to a VARIANT that will be updated key data. The key data will be a byte array variant regardless of the real format of the key data.

pDataSize

Pointer to a long variable that will be updated with the number of bytes stored in pKeyData. This is the same as the size of the pKeyData variant.

Description

Use this method to enumerate all the keys contained in a private data sample. This method will enumerate all the data passed to AddData since the last call that had the DataFlag_BeginSample flag set.

The method allocates data for the pKey and pKeyData variants. You should make sure you free the memory allocated in these variants if your programming language does not do so automatically. For example, VB automatically frees this memory, but C/C++ does not. In C++, you free the variant memory by calling VariantClear. Please consult the documentation for your programming language for more information on how to free the variant data.

You should examine pKey to find out how you are supposed to interpret the key data. The ILMKlvParser will not interpret the key data for you. There is not a single document describing all the KLV keys that you might find in a stream. You will find various documents describing certain lists of currently defined keys. But each company that generates MPEG-2 transport streams or files might write their own internal keys in a private data stream. At the time of writing this documentation, the following documents contained information on KLV keys and how to interpret their content:

Based on information on this and other documents that you might find, you should interpret the key data accordingly. For example:

Key: 06 0E 2B 34 01 01 01 04 07 02 01 01 01 05 00 00

Is a “User Defined Time Stamp (microseconds since 1970)” in msb bit order and that the key should be 8 bytes long. In this case, you should verify that *pDataSize is 8. If *pDataSize is 8, you should convert the 8-byte array into a 64-bit unsigned integer (or a double floating point if your programming language does not support 64-bit integers). You would then convert the 64-bit value into a date and time by counting the microseconds since 1970.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid (< 0).

E_POINTER

[0x80004003] pKey, pKeyData or pDataSize is NULL.

KLV_KEY_NOT_FOUND

[0x80050010] The key was not found (keyIndex >= Count).

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the pKey or pKeyData variants.

 

HRESULT FindKey(VARIANT *pKeyToFind, long searchFlags, VARIANT *pKey, VARIANT *pKeyData, long *pDataSize);

Parameters

pKeyToFind

Pointer to a variant describing which key to look for.

searchFlags

One of the flags in the SearchKeyConstants enumeration. These flags tell the parser how whether the match should be exact or not.

pKey

Pointer to a VARIANT that will be updated with a key describing the data. The key will be a 16-byte array describing the variant data. This key tells you how to interpret the key data contained in pKeyData.

pKeyData

Pointer to a VARIANT that will be updated key data. The key data will be a byte array variant regardless of the real format of the key data.

pDataSize

Pointer to a long variable that will be updated with the number of bytes stored in pKeyData. This is the same as the size of the pKeyData variant.

Description

Use searchFlags to whether you require an exact match or not for the key you are looking for. Possible values for searchFlags are:

SearchKey_Exact

An exact match is required. All 16 bytes of the key must match.

SearchKey_AnyVersion

For a match to be acceptable, all key bytes must match, with the exception of the version key (the 7th byte).

SearchKey_DesignatorOnly

For a match to be acceptable, the key designator component must match. The key designator is stored in the last 8 bytes of the key.

This function will go through the top keys in the buffer and compare them with the key passed in pKeyToFind. If the key from the buffer matches exactly or partially (if permitted by searchFlags), then the key found is stored in pKey, the key data is stored in pKeyData and the key length is stored in pDataSize.

To understand searchFlags better, read more information on KLV keys in the KLV Key information topic.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

E_POINTER

[0x80004003] pKey, pKeyData or pDataSize is NULL.

KLV_KEY_NOT_FOUND

[0x80050010] There is no key matching pKeyToFind and searchFlags.

E_OUTOFMEMORY

 [0x8007000E] Could not allocate memory for the pKey or pKeyData variants.

 

HRESULT FindKeyStr(BSTR pKeyToFind, long searchFlags, VARIANT *pKey, VARIANT *pKeyData, long *pDataSize);

Parameters

pKeyToFind

Pointer to a string describing which key to look for.

searchFlags

One of the flags in the SearchKeyConstants enumeration. These flags tell the parser whether the match should be exact or not.

pKey

Pointer to a VARIANT that will be updated with a key describing the data. The key will be a 16-byte array describing the variant data. This key tells you how to interpret the key data contained in pKeyData.

pKeyData

Pointer to a VARIANT that will be updated key data. The key data will be a byte array variant regardless of the real format of the key data.

pDataSize

Pointer to a long variable that will be updated with the number of bytes stored in pKeyData. This is the same as the size of the pKeyData variant.

Description

This method works exactly like FindKey, except that the key to search for is passed as a string, rather than a VARIANT.

pKeyToFind is a string containing a hexadecimal representation of the bytes in the key. Each byte should be represented by two hexadecimal digits. Each digit can be:

Space characters are ignored. For example, “06 0E 2B 34 01 01 01 04 07 02 01 01 01 05 00 00” is equivalent to “060E2B34010101040702010101050000”.

For more information on each parameter, see the description for FindKey.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

E_POINTER

[0x80004003] pKey, pKeyData or pDataSize is NULL.

KLV_KEY_NOT_FOUND

[0x80050010] There is no key matching pKeyToFind and searchFlags.

E_OUTOFMEMORY

 [0x8007000E] Could not allocate memory for the pKey or pKeyData variants.

KLV_BAD_KEY

[0x80050011] The key string is invalid: the key string should contain a hexadecimal representation of a 16-byte value, with 2 digits per byte (32 digits total).