TLVList - Reference Documentation
Implementation of a mutable TLV object list.
Index of Methods
Properties
| Type |
Name |
Description |
| Number |
encodingMode |
Encoding mode used for TLV object. One of TLV.EMV, TLV.DGI or TLV.L16 |
| Number |
length |
The number of TLV objects in the list |
Constructor
Prototype
TLVList(ByteString tlvStream, Number encoding)
Description
Create a TLV list object initialized with the tlv objects encoded within the given ByteString object.
For EMV encoding the tag field has a variable length of up to 4 bytes.
The length field has a variable length of up to 4 byte. Both fields are
encoded as specified as per ASN.1 Basic Encoding Rule (ISO 8825).
For DGI encoding the tag field has a fixed length of two bytes.
The length field contains one byte for values between 0 and 254. The length
is encoded in three bytes for values between 255 and 65535, with the first byte
set to 'FF'.
For L16 encoding the tag field has a fixed length of two bytes.
The length field is always two byte long and is encoded in big endian /
little endian format.
Arguments
| Type |
Name |
Description |
ByteString
|
tlvStream |
ByteString containing the encoded tlv objects |
Number
|
encoding |
Encoding for tag and length field of the tlv objects in the ByteString. Must be one of TLV.EMV, TLV.DGI or TLV.L16. |
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_ENCODING |
The argument encoding is invalid |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
Example
// EMV
data = new ByteString("61050102030405620100630A00010203040506070809", HEX);
// Create a TLV list
list = new TLVList(data, TLV.EMV);
assert(list.length == 3);
// Create a TLV list with "illegal" ASN.1 DER encoding
list = new TLVList(new ByteString("9f030100", HEX), TLV.EMV);
assert(list.length == 1);
// DGI
data = new ByteString("7F1F05010203040500630A00010203040506070809", HEX);
list = new TLVList(data, TLV.DGI);
assert(list.length == 2);
// L16
data = new ByteString("7F1F000501020304050063000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
index()
Prototype
TLV index(Number index)
Description
Returns a TLV object which represents the TLV stored within the TLVList at the given index. The index is zero based.
Arguments
| Type |
Name |
Description |
Number
|
index |
Index of the TLV object |
Return
TLV
|
TLV object at the specified index |
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
Example
// EMV
data = new ByteString("610501020304056201008E0A00010203040506070809", HEX);
// Create a TLV list
list = new TLVList(data, TLV.EMV);
assert(list.length == 3);
tag_61 = list.index(0);
assert(tag_61 != null);
assert(tag_61.getTag() == 0x61);
tag_62 = list.index(1);
assert(tag_62 != null);
assert(tag_62.getTag() == 0x62);
tag_8e = list.index(2);
assert(tag_8e != null);
assert(tag_8e.getTag() == 0x8E);
// Invalid index
try {
tag = list.index(10);
} catch (e) {
assert(e instanceof GPError);
}
// Check various EMV length encodings
data = new ByteString("6181050102030405", HEX);
list = new TLVList(data, TLV.EMV);
tlv = list.index(0);
assert(tlv.getTag() == 0x61);
assert(tlv.getValue().length == 5);
assert(tlv.getValue().toString(HEX) == "0102030405");
data = new ByteString("618200050102030405", HEX);
list = new TLVList(data, TLV.EMV);
tlv = list.index(0);
assert(tlv.getTag() == 0x61);
assert(tlv.getValue().length == 5);
assert(tlv.getValue().toString(HEX) == "0102030405");
append()
Prototype
append(ByteString tlvStream)
append(Number tag, ByteString value)
append(TLV tlv)
Description
Appends the specified TLV data to the end of the existing list of TLV objects.
Arguments
| Type |
Name |
Description |
ByteString
|
tlvStream |
TLV as a single stream of bytes in a ByteString. |
Number
|
tag |
Tag to be used to be added to the list. |
ByteString
|
value |
Value to be used to be added to the List. |
TLV
|
tlv |
TLV as a TLV object. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
| GPError |
GPError.TAG_ALREADY_EXISTS |
The tag of the specified TLV object already exists within the TLV list |
Example
// L16 encoded data
data = new ByteString("7F1F00050102030405", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 1);
// append(Number, Value)
list.append(0x63, new ByteString("00010203040506070809", HEX));
assert(list.length == 2);
// append(ByteString)
list.append(new ByteString("0061000A00010203040506070809", HEX));
assert(list.length == 3);
// append(TLV)
t = new TLV(0x3221, new ByteString("123456", HEX), TLV.L16);
list.append(t);
assert(list.length == 4);
// try to append an invalid type
try {
list.append("HALLO");
} catch (e) {
assert(e instanceof GPError);
}
// try to append a tag with an already existing tag number
try {
t = new TLV(0x3221, new ByteString("123456", HEX), TLV.L16);
list.append(t);
} catch (e) {
assert(e instanceof GPError);
}
appendValue()
Prototype
appendValue(Number tag, ByteString value)
Description
Appends the data to the existing data for the specified tag.
Arguments
| Type |
Name |
Description |
Number
|
tag |
Tag to be used to be added to the list. |
ByteString
|
value |
Value to be used to be added to the List. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
Example
// L16 encoded data
data = new ByteString("7F1F00050102030405", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 1);
// appendValue(Number, Value)
list.appendValue(0x7F1F, new ByteString("06070809", HEX));
tlv = list.index(0);
assert(tlv.getValue().toString(HEX) == "010203040506070809");
appendValueIndex()
Prototype
appendValueIndex(Number index, ByteString value)
Description
Appends the data to the existing data for the specified zero-based index into the TLVStream.
Arguments
| Type |
Name |
Description |
Number
|
index |
Tag to be used to be added to the list. |
ByteString
|
value |
Value to be used to be added to the List. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
Example
// L16 encoded data
data = new ByteString("7F1F00050102030405", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 1);
// appendValueIndex(Number, Value)
list.appendValueIndex(0, new ByteString("06070809", HEX));
tlv = list.index(0);
assert(tlv.getValue().toString(HEX) == "010203040506070809");
deleteByIndex()
Prototype
deleteByIndex(Number index)
Description
Delete the specified TLV from the list using a zero based index.
Arguments
| Type |
Name |
Description |
Number
|
index |
Zero based index number that represents the Tag that will be deleted from the list. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
Example
// L16 encoded data
data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
// deleteByIndex(Number)
list.deleteByIndex(0);
assert(list.length == 1);
tlv = list.index(0);
assert(tlv.getTLV().toString(HEX) == "0061000A00010203040506070809");
deleteByTag()
Prototype
deleteByTag(Number tag)
Description
Delete the specified TLV from the list by tag value.
Arguments
| Type |
Name |
Description |
Number
|
tag |
Number of Tag that will be deleted from the list. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
| GPError |
GPError.TAG_NOT_FOUND |
The specified tag could not be found |
Example
// L16 encoded data
data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
// deleteByTag(Number)
list.deleteByTag(0x7F1F);
assert(list.length == 1);
tlv = list.index(0);
assert(tlv.getTLV().toString(HEX) == "0061000A00010203040506070809");
findIndex()
Prototype
Number findIndex(Number tag)
Description
Searches the list for a specified tag, and returns a zero based index for that TLV.
Arguments
| Type |
Name |
Description |
Number
|
tag |
The Tag that will be searched for within the list. |
Return
Number
|
Index that indicates the location of the TLV within TLV list or -1 if not found. |
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
Example
// L16 encoded data
data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
index_tag_61 = list.findIndex(0x61);
assert(typeof(index_tag_61) == "number");
assert(index_tag_61 == 1);
index_tag_63 = list.findIndex(0x63);
assert(index_tag_63 == -1);
find()
Prototype
TLV find(Number tag)
Description
Searches the list for a specified tag, and returns a TLV object.
Arguments
| Type |
Name |
Description |
Number
|
tag |
The Tag that will be searched for within the list. |
Return
TLV
|
A TLV object which contains the data stored for that Tag or null if the Tag was not found. |
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
Example
// L16 encoded data
data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
tag_61 = list.find(0x61);
assert(tag_61 != null);
tag_63 = list.find(0x63);
assert(tag_63 == null);
updateValue()
Prototype
updateValue(Number tag, ByteString value)
Description
Updates the data for the specified tag.
Arguments
| Type |
Name |
Description |
Number
|
tag |
Tag to be used to be added to the list. |
ByteString
|
value |
Data to replace existing value of TLV specified by tag with. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
Example
// L16 encoded data
data = new ByteString("7F1F00050102030405", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 1);
// appendValue(Number, Value)
list.updateValue(0x7F1F, new ByteString("06070809", HEX));
tlv = list.index(0);
assert(tlv.getValue().toString(HEX) == "06070809");
updateValueIndex()
Prototype
updateValueIndex(Number index, ByteString value)
Description
Updates the data for the specified zero-based index into the TLVStream.
Arguments
| Type |
Name |
Description |
Number
|
index |
Tag to be used to be added to the list. |
ByteString
|
value |
Value to be used to be added to the List. |
Return
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
| GPError |
GPError.INVALID_TYPE |
Type of argument is invalid for call |
| GPError |
GPError.INVALID_TAG |
The tag value is invalid for the selected encoding format |
| GPError |
GPError.INVALID_INDEX |
The specified index is not valid |
| GPError |
GPError.DATA_TOO_LARGE |
The data supplied for the value fields exceeds the maximum length |
Example
// L16 encoded data
data = new ByteString("7F1F00050102030405", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 1);
// appendValueIndex(Number, Value)
list.updateValueIndex(0, new ByteString("06070809", HEX));
tlv = list.index(0);
assert(tlv.getValue().toString(HEX) == "06070809");
toByteString()
Prototype
ByteString toByteString()
Description
Returns the contents of the entire list, including T, L and V values in a TLV format as a ByteString object.
Return
ByteString
|
The concatenated T, L and V values in a TLV format. |
Exceptions
| Name |
Value |
Description |
| GPError |
GPError.INVALID_ARGUMENTS |
Too many arguments in call |
| GPError |
GPError.ARGUMENTS_MISSING |
Too few arguments in call |
Example
// L16 encoded data
data = new ByteString("7F1F000501020304050061000A00010203040506070809", HEX);
list = new TLVList(data, TLV.L16);
assert(list.length == 2);
t = list.toByteString();
assert(t != null);
assert(t.toString() == data.toString());
© Copyright 2003 - 2020 CardContact Systems GmbH
, Minden, Germany
