ILMKlvBuilder Interface

 

The ILMKlvBuilder interface is provided by the LEAD MPEG-2 Transport Multiplexer to simplify the task of parsing KLV data. It can be obtained from the multiplexer by reading the ILMMpg2MxT::KlvBuilder property.

 

Use the KlvBuilder to build and create private data conforming to SMPTE 336M-2001. There are two standards supported by this interface : Universal Metadata Set and Local Metadata Set.

 

Universal Metadata Set UMS

In this standard, keys are formatted and identified as GIUD value indicated by a 16-bit hexadecimal string.

One example of an application of this standard is the one used for vehicles of type Predator UAV (Unmanned Aerial Vehicle): Basic Universal Metadata Set MISB EG 0104.4

 

Local Metadata Set LDS

In this standard, keys are formatted and identified as a short value indicated by an ULONG type.

One example of an application of this standard is the one used for systems of type UAS (Unmanned Air System): Datalink Local Metadata Set MISB STD 0601.4

 

Data types:

 

typedefenum Mpg2MxT_SearchKey
{
   Mpg2MxT_SearchKey_Exact = 1,           /* Find only the exact key. The key version number must match. */
   Mpg2MxT_SearchKey_AnyVersion = 2,      /* Ignore the version number when doing the search. */
   Mpg2MxT_SearchKey_DesignatorOnly = 3,  /* Find the key by the designator only. Ignore the key representation and version number */
} Mpg2MxT_SearchKey;

 

typedefenum Mpg2MxT_Errors
{
   Mpg2MxT_E_KEY_NOT_FOUND = 0x80050010,    /* The KLV data was not found */
   Mpg2MxT_E_BAD_KEY = 0x80050011,          /* The KLV key is bad */
} Mpg2MxT_Errors;

 

Interface Properties:

 

Type

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.

BYTE[]

GroupKey

Group key defined by the user that is an independent KLV builder; it can be added to the main KLV Builder.

 

Interface Methods:

 

HRESULT AddData(VARIANT Data, long lDataLengh);

Parameters

Data

Variant containing the private data.

DataLength

The size of data contained in Data.

Description

Use this method to begin building private data containing KLV packets. It is particularly useful from ILMMpgDmxCallback::DataAvailable when processing a source file containing KLV data. Build up the KLV data using this method and then edit the individual keys afterwards. This method appends the supplied data to the internal buffer. You should call the Clear method to restart the process. The Data parameter must contain a pointer to a byte array. The AddData method uses the smaller of the DataLength parameter and the actual array size.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

E_POINTER                  [0x80004003] Data is NULL

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

 

HRESULT CreateSubBuilder(VARIANT GroupKey, ILMKlvBuilder1** pVal);

Parameters

GroupKey

Pointer to a VARIANT that holds the key for SubBuilder. The key will be a 16-byte array.

pVal

A pointer to a location to store a new builder interface pointer.

Description

Creates an independent builder for constructing subkeys.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

E_POINTER

[0x80004003] ppBuilder is NULL

 

HRESULT DeleteKey(long keyIndex);

Parameters

keyIndex

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

Description

Deletes an existing key.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

 

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

Parameters

KeyToFind

Variant describing which key to look for.

searchFlags

One of the flags in the Mpg2MxT_SearchKey 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 specify whether you require an exact match for the key for which you are looking. Possible values for searchFlags are:

Mpg2MxT_SearchKey_Exact

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

Mpg2MxT_SearchKey_AnyVersion

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

Mpg2MxT_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 goes through the top keys in the buffer and compares them with the key passed in KeyToFind. 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.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

E_POINTER

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

Mpg2MxT_E_KEY_NOT_FOUND

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

E_OUTOFMEMORY

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

 

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

Parameters

KeyToFind

String describing which key to look for.

searchFlags

One of the flags in the Mpg2MxT_SearchKey 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.

KeyToFind 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 0101 04 07 02 01 0101 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.

Mpg2MxT_E_KEY_NOT_FOUND

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

E_OUTOFMEMORY

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

Mpg2MxT_E__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).

 

HRESULT GetData(VARIANT* pData);

Parameters

Data

Pointer to a variant that is filled with a byte array copy of the current data.

Description

Creates a copy of the current data.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

E_POINTER                  [0x80004003] Data is NULL

E_OUTOFMEMORY      [0x80070057] The array for the copy could not be allocated.

  

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 enumerates all the data passed to AddData.

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 to interpret the key data. The IKlvBuilder 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 0101 04 07 02 01 0101 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.

Mpg2MxT_E_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 InsertKey(long keyIndex, VARIANT Key, VARIANT KeyData, long DataSize);

 Parameters

keyIndex

The index of the keys insertion point. The index is 0-based, so allowed values are 0..Count - 1. However, a special value of -1 will append the key to the end of the current data.

Key

VARIANT 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 KeyData.

KeyData

VARIANT containing key data. The key data will be a byte array variant regardless of the real format of the key data.

DataSize

Long variable describing the number of bytes stored in KeyData. This is the same as the size of the KeyData variant.

 Description

Inserts a new key.

 Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

  

HRESULT SetKey(long keyIndex, VARIANT Key, VARIANT KeyData, long DataSize);

Parameters

keyIndex

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

Key

VARIANT 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 KeyData.

KeyData

VARIANT containing key data. The key data will be a byte array variant regardless of the real format of the key data.

DataSize

Long variable describing the number of bytes stored in KeyData. This is the same as the size of the KeyData variant.

Description

Replaces an existing key.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

 HRESULT CreateGroup(BSTR GroupKey,  ILMKlvBuilder **pVal);

Parameters

GroupKey

A hexadecimal string that defines the Key of the group.

pVal

A pointer to a location to store a new builder interface pointer.

Description

Creates an independent builder for constructing subkeys. This builder is referred to as a group and identifed by the GroupKey.

Returns

S_OK if successful, < 0 if an error occurred.
 

Common error codes:

Value

Meaning

E_POINTER

[0x80004003] pVal is NULL

 

HRESULT InsertGroup( long keyIndex, BSTR key, ILMKlvBuilder *pGroup);

Parameters

keyIndex

The index of the Groupkey's insertion position. The index is 0-based, However, a special value of -1 appends the group at the end of the set.

key

A hexadecimal string representing the groups key. This value can be NULL or an empty string to indicate the GroupKey is defined within the group.

pGroup

The pointer to the group's interface to be added.

Description

Inserts the group into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

E_POINTER

[0x80004003] pGroup is NULL

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

 

 

HRESULT InsertString(long keyIndex, BSTR key, BSTR val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (string) to be inserted.

Description

Inserts a string value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertUInt8(long keyIndex, BSTR key, BYTE val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (BYTE) to be inserted.

Description

Inserts an 8-bit unsigned integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

 

HRESULT InsertUInt16(long keyIndex, BSTR key, USHORT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (USHORT) to be inserted.

Description

Inserts a 16-bit unsigned integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

 

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

 

HRESULT InsertUInt32(long keyIndex, BSTR key, ULONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (ULONG) to be inserted.

Description

Inserts a 32-bit unsigned integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertUInt64(long keyIndex, BSTR key, ULONGLONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (ULONGLONG) to be inserted.

Description

Inserts a 64-bit unsigned integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertInt8(long keyIndex, BSTR key, CHAR val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (CHAR) to be inserted.

Description

Inserts an 8-bit signed integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertInt16(long keyIndex, BSTR key, SHORT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (SHORT) to be inserted.

Description

Inserts a 16-bit signed integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertInt32(long keyIndex, BSTR key, LONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (LONG) to be inserted.

Description

Inserts a 32-bit signed integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertInt64(long keyIndex, BSTR key, LONGLONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (LONGLONG) to be inserted.

Description

Inserts a 64-bit signed integer value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertFloat(long keyIndex, BSTR key, FLOAT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (FLOAT) to be inserted.

Description

Inserts a float value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertDouble(long keyIndex, BSTR key, DOUBLE val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

The simple value (DOUBLE) to be inserted.

Description

Inserts a double value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertArray(long keyIndex, BSTR key, VARIANT val, long valSize);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A hexadecimal string that represents the key.

val

VARIANT containing key value, that will be a byte array.

valSize

forces the actual size of the data. Specify -1 to use all of the array data.

Description

Inserts an array value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT AppendChecksum(BSTR key, BSTR outerKey);

Parameters

key

A hexadecimal string that represents the key.

outerKey

Use this parameter to specify a different group key to use for  checksum calculations. Use NULL or an empry string to default to the predefined GroupKey.

Description

Appends a 16 bit checksum to the end of the builder data.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalGroup(long keyIndex, ULONG key, ILMKlvBuilder* pGroup);

Parameters

keyIndex

The index of the Groupkey's insertion position. The index is 0-based, However, a special value of -1 will append the group at the end of the set.

key

A local dataset ULONG key.

pGroup

The group interface pointer to be added.

Description

Inserts the group into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

E_POINTER

[0x80004003]pGroup is NULL

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalString(long keyIndex, ULONG key, BSTR val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (string) to be inserted.

Description

Inserts a string value into the builder.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalUInt8(long keyIndex, ULONG key, BYTE val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (BYTE) to be inserted.

Description

Inserts an 8-bit unsigned integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalUInt16(long keyIndex, ULONG key, USHORT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (USHORT) to be inserted.

Description

Inserts a 16-bit unsigned integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalUInt32(long keyIndex, ULONG key, ULONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (ULONG) to be inserted.

Description

Inserts a 32-bit unsigned integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalUInt64(long keyIndex, ULONG key, ULONGLONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (ULONGLONG) to be inserted.

Description

Inserts a 64-bit unsigned integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalInt8(long keyIndex, ULONG key, CHAR val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (CHAR) to be inserted.

Description

Inserts an 8-bit signed integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalInt16(long keyIndex, ULONG key, SHORT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (SHORT) to be inserted.

Description

Inserts a 16-bit signed integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalInt32(long keyIndex, ULONG key, LONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (LONG) to be inserted.

Description

Inserts a 32-bit signed integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalInt64(long keyIndex, ULONG key, LONGLONG val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (LONGLONG) to be inserted.

Description

Inserts a 64-bit signed integer value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalFloat(long keyIndex, ULONG key, FLOAT val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (FLOAT) to be inserted.

Description

Inserts a float value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalDouble(long keyIndex, ULONG key, DOUBLE val);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

The simple value (DOUBLE) to be inserted.

Description

Inserts a double value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT InsertLocalArray(long keyIndex, ULONG key, VARIANT val, long valSize);

Parameters

keyIndex

The index of the key's insertion point. The index is 0-based, hence the allowed values are 0...Count - 1. However, a special value of -1 will append the key at the end of the current data.

key

A local dataset ULONG key.

val

VARIANT containing key value, that will be a byte array.

valSize

Actual data size. Specify -1 to use all of the array data.

Description

Inserts an array value into the builder using the local dataset short key.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

DISP_E_BADINDEX

[0x8002000B] keyIndex is invalid.

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.

 

HRESULT AppendLocalChecksum(BSTR ULONG , BSTR outerKey);

Parameters

key

A local dataset short key.

outerKey

Use this parameter to specify a different group key to use for the checksum calculation. Use NULL or an empry string to default to the predefined GroupKey.

Description

Appends a 16-bit checksum to the end of the builder data using the local dataset short key.

The checksum value is used for error detection and it is highly recommended that a 16-bit checksum is included in every Local Data Set packet.
This value is running a 16-bit sum through the entire LDS packet. The sum is composed of the local data set key and the length field that indicates the data size.

Returns

S_OK if successful, < 0 if an error occurred.

 

Common error codes:

Value

Meaning

E_OUTOFMEMORY

[0x8007000E] Could not allocate memory for the new data.