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:

Interface Methods:

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

Parameters

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:

• pData must be a one-dimensional byte array variant

• lDataSize must be <= size of pData variant

• Set the Flags to their appropriate values. If you pass a complete KLV buffer, pass DataFlag_BeginSample | DataFlag_EndSample for Flags. It is not necessary to pass the DataFlag_IsKLV flag. That is for informational purposes. The ILMKlvParser interface pays attention only to the DataFlag_BeginSample and DataFlag_EndSample flags.

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

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:

• UAV Datalink Local Metadata Set (EG 0601 12 Jan 2006)

• Predator UAV Basic Universal Metadata Set (MISB EG 0104.4 25 August 2005)

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:

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

Parameters

Description

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

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:

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

Parameters

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:

• ‘0’..’9’ or

• ‘a’..’f’ or

• ‘A’..’F’

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: