# Smart Card Shell

- - Home
- - GPError
  - GPSystem
  - ByteString
  - ByteBuffer
  - TLV
  - TLVList
  - Card
  - Atr
  - Key
  - Crypto
  - Application
  - GPApplication
  - GPSecDomain
- - ASN1
  - CardFile
  - IsoSecureChannel
  - ApplFactory
  - GPXML
  - JsScript
  - CardSim
- - X509
  - CRL
  - KeyStore
  - Signed CMS
  - Enveloped CMS
  - CMS Generator
  - XMLSignature
  - SSS
  - OCSPQuery
  - LDAP
  - SOAP
  - URLConnection
- - PKCS11Provider
  - PKCS11Session
  - PKCS11Object
- - OutlineNode
  - Dialog
  - Task
- - Tools
  - Modules
- - OpenSCDP

# ByteBuffer - Reference Documentation

Implementation of a mutuable byte buffer.

## Index of Methods

- ByteBuffer() constructor
- toString()
- append()
- byteAt()
- clear()
- copy()
- find()
- insert()
- toByteString()

## Properties

Type | Name | Description
--- | --- | ---
Number | length | Number of bytes in the ByteBuffer

## Constructor

### Prototype

ByteBuffer()

ByteBuffer(String stringValue, Number encoding)

ByteBuffer(ByteString byteString)

### Description

Create a empty ByteBuffer object or a ByteBuffer object containing the data from stringValue decoded according to format defined in argument encoding or a ByteBuffer object containing the ByteString object passed as argument

The following encoding formats can be used for the stringValue argument:

HEX - A string containing hexadecimal characters and arbitrary delimiters.

ASCII - A string containing ASCII characters and characters from Latin-1.

UTF8 - A string containing Unicode characters.

BASE64 - A string containing BASE-64 encoded data.

OID - A string containing an object identifier in dotted notation or separated by blanks (This is a proprietary extension to Global Platform Scripting).

### Arguments

Type | Name | Description
--- | --- | ---
`String` | stringValue | String containing the encoded binary data
`Number` | encoding | Encoding format. Must be one of HEX, ASCII, UTF8, BASE64 or OID
`ByteString` | byteString | ByteString object with data

### Exceptions

Name | Value | Description
--- | --- | ---
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 contains an unknown encoding format
GPError | GPError.INVALID_DATA | The argument stringValue contains characters not compatible with the encoding format
GPError | GPError.INVALID_ARGUMENTS | Too many arguments given

### Example

    x = new ByteBuffer();

    assert(x != null);
    assert(x instanceof ByteBuffer);

    x = new ByteBuffer("1234", HEX);

    assert(x.length == 2);
    assert(x.toString() == "12 34");

    x = new ByteBuffer("0x1234 56.78.90+AB#cd'EF", HEX);

    assert(x.length == 8);
    assert(x.toString() == "12 34 56 78 90 AB CD EF");

    x = new ByteBuffer("1234ABCDÄÖÜß", ASCII);

    assert(x.length == 12);
    assert(x.toString() == "31 32 33 34 41 42 43 44 C4 D6 DC DF");

    x = new ByteBuffer("1234ABCDÄÖÜß", UTF8);

    assert(x.length == 16);
    assert(x.toString() == "31 32 33 34 41 42 43 44 C3 84 C3 96 C3 9C C3 9F");

    x = new ByteBuffer("SGVsbG8gV29ybGQ=", BASE64);

    assert(x.length == 11);
    assert(x.toString(ASCII) == "Hello World");

    x = new ByteBuffer(new ByteString("1234", HEX));

    assert(x.length == 2);
    assert(x.toString() == "12 34");

    x = new ByteBuffer("1.2.840.113549.1.1.2", OID);

    assert(x.length == 9);
    assert(x.toString(OID) == "1.2.840.113549.1.1.2");
    assert(x.toString(HEX) == "2A864886F70D010102");

    x = new ByteBuffer("1 2 840 113549 1 1 2", OID);

    assert(x.toString(HEX) == "2A864886F70D010102");

## toString()

### Prototype

String toString(Number encoding)

### Description

Return string containing binary data in given encoding

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | encoding | Encoding to present the binary data in. Must be one of ASCII, HEX, UTF8, BASE64 or CN.

### Return

`String` | String representing data from ByteBuffer

### 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

### Example

    x = new ByteBuffer("41 42 43", HEX);
    assert(x.toString(HEX) == "414243");

    x = new ByteBuffer("41 42 43 C4 D6 DC DF", HEX);
    assert(x.toString(ASCII) == "ABCÄÖÜß");

    x = new ByteBuffer("C3 84 C3 96 C3 9C C3 9F", HEX);
    assert(x.toString(UTF8) == "ÄÖÜß");

    x = new ByteBuffer("Hello World", ASCII);
    assert(x.toString(BASE64) == "SGVsbG8gV29ybGQ=");

## append()

### Prototype

ByteBuffer append(ByteBuffer byteBuffer)

ByteBuffer append(ByteString byteString)

ByteBuffer append(Number byteValue)

ByteBuffer append(String stringValue)

### Description

Append to the ByteBuffer at the end the content of the ByteBuffer or ByteString object, the ASCII encoded string or the byte given as argument.

### Arguments

Type | Name | Description
--- | --- | ---
`ByteBuffer` | byteBuffer | ByteBuffer object to be appended to ByteBuffer
`ByteString` | byteString | ByteString object to be appended to ByteBuffer
`String` | stringValue | String containing ASCII characters to be appended to ByteBuffer
`Number` | byteValue | Single byte value

### Return

`ByteBuffer` | Returns the ByteBuffer object this method is applied to

### 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

### Example

    x = new ByteBuffer();

    x.append(new ByteBuffer("ABC", ASCII));
    assert(x.toString() == "41 42 43");

    x.append("123");
    assert(x.toString() == "41 42 43 31 32 33");

    x.append(new ByteString("ABC", ASCII));
    assert(x.toString() == "41 42 43 31 32 33 41 42 43");

    str = 0x20;
    x.append(str);
    assert(x.toString() == "41 42 43 31 32 33 41 42 43 20");

## byteAt()

### Prototype

Number byteAt(Number offset)

### Description

Return the byte at the zero based offset in the ByteBuffer

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | offset | Zero based offset

### Return

`Number` | Value of byte as unsigned integer

### 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_INDEX | Argument offset is out of range

### Example

    x = new ByteBuffer("123ABCÄÖÜ", ASCII);
    assert(typeof(x.byteAt(0) == "number"));
    assert(x.byteAt(0) == 0x31);
    assert(x.byteAt(3) == 0x41);
    assert(x.byteAt(6) == 0xC4);

## clear()

### Prototype

ByteBuffer clear()

ByteBuffer clear(Number offset)

ByteBuffer clear(Number offset, Number length)

### Description

Clears the area specified by offset and length in the ByteBuffer. Bytes behind the cleared area are moved to offset. If length is missing, then the remaining length from offset to the end of the ByteBuffer is cleared. If offset and length are missing from the argument list, then the whole ByteBuffer is cleared.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | offset | The zero based offset in the ByteBuffer where the clear operation is started. Zero is assumed if offset is missing.
`Number` | length | The length of the area to be cleared. If length is missing, then the maximum number of bytes up to the end of the ByteBuffer is assumed.

### Return

`ByteBuffer` | The ByteBuffer object the method is applied to

### 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_INDEX | Argument offset is out of range
GPError | GPError.INVALID_LENGTH | Argument length is out of range

### Example

    x = new ByteBuffer("123456", ASCII);

    x.clear(2, 2);
    assert(x.toString(ASCII) == "1256");

    x.clear(2);
    assert(x.toString(ASCII) == "12");

    x.clear();
    assert(x.length == 0);

## copy()

### Prototype

ByteBuffer copy(Number offset, ByteBuffer byteBuffer)

ByteBuffer copy(Number offset, ByteString byteString)

ByteBuffer copy(Number offset, Number byteValue)

ByteBuffer copy(Number offset, String stringValue)

### Description

Copy the bytes from the argument into the ByteBuffer at offset and replace the bytes contained. The length of the ByteBuffer is not changed.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | offset | Zero based offset at which the bytes from the argument are copied to
`ByteBuffer` | byteBuffer |
`ByteString` | byteString |
`Number` | byteValue | Value of a single unsigned byte
`Number` | stringValue | ASCII encoded string

### Return

`ByteBuffer` | The ByteBuffer object this method is applied to

### 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_INDEX | The argument offset is out of range
GPError | GPError.INVALID_LENGTH | The offset plus the length of the argument exceeds the end of the ByteBuffer

### Example

    x = new ByteBuffer("123456", ASCII);

    x.copy(0, "AB");
    assert(x.toString(ASCII) == "AB3456");

    y = new ByteBuffer("CD", ASCII);
    x.copy(2, y);
    assert(x.toString(ASCII) == "ABCD56");

    y = new ByteString("EF", ASCII);
    x.copy(4, y);
    assert(x.toString(ASCII) == "ABCDEF");

## find()

### Prototype

Number find(ByteString value)

Number find(ByteString value, Number offset)

### Description

Find the first occurence of the value starting at offset.

### Arguments

Type | Name | Description
--- | --- | ---
`ByteString` | value | ByteString to locate in ByteBuffer
`Number` | offset | Zero based offset to start search at. Zero is assumed if argument is missing.

### Return

`Number` | Zero based offset at which the ByteString is found or -1 if the ByteString is not found.

### 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_INDEX | Argument offset is out of range
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call

### Example

    x = new ByteBuffer("ABCDABCD", ASCII);
    y = new ByteString("BC", ASCII);

    assert(x.find(y) == 1);
    assert(x.find(y, 2) == 5);
    assert(x.find(y, -2) == 1);

    y = new ByteString("CD", ASCII);
    assert(x.find(y, 4) == 6);

    y = new ByteString("CD", ASCII);
    assert(x.find(y, 6) == 6);

    y = new ByteString("CB", ASCII);
    assert(x.find(y) == -1);

    y = new ByteString("BCDE", ASCII);
    assert(x.find(y) == -1);

    y = new ByteString("", ASCII);
    assert(x.find(y) == 0);

    x = new ByteBuffer("", ASCII);
    y = new ByteString("", ASCII);
    assert(x.find(y) == 0);
    assert(x.find(y, 0) == 0);

## insert()

### Prototype

ByteBuffer insert(Number offset, ByteBuffer byteBuffer)

ByteBuffer insert(Number offset, ByteString byteString)

ByteBuffer insert(Number offset, Number byteValue)

ByteBuffer insert(Number offset, String stringValue)

### Description

Insert the bytes from the argument at offset.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | offset | Zero based offset at which the bytes are inserted
`ByteBuffer` | byteBuffer | ByteBuffer object to be appended to ByteBuffer
`ByteString` | byteString | ByteString object to be appended to ByteBuffer
`String` | stringValue | String containing ASCII characters to be appended to ByteBuffer
`Number` | byteValue | Single byte value

### Return

`ByteBuffer` | Returns the ByteBuffer object this method is applied to

### 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_INDEX | The argument offset is out of range

### Example

    x = new ByteBuffer("123456", ASCII);

    x.insert(0, "AB");
    assert(x.toString(ASCII) == "AB123456");

    y = new ByteBuffer("CD", ASCII);
    x.insert(2, y);
    assert(x.toString(ASCII) == "ABCD123456");

    y = new ByteString("EF", ASCII);
    x.insert(10, y);
    assert(x.toString(ASCII) == "ABCD123456EF");

    x.insert(1, 0x31);
    assert(x.toString(ASCII) == "A1BCD123456EF");

## toByteString()

### Prototype

ByteString toByteString()

ByteString toByteString(Number offset)

ByteString toByteString(Number offset, Number count)

### Description

Return all or a fraction of the ByteBuffer as ByteString.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | offset | Zero based offset in ByteBuffer. Default is 0.
`Number` | count | Number of bytes to return. Default is all.

### Return

`ByteString` | Bytes as ByteString object

### 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_INDEX | The argument offset is out of range
GPError | GPError.INVALID_LENGTH | The argument count is out of range

### Example

    x = new ByteBuffer("123456", ASCII);

    y = x.toByteString();
    assert(y.toString(ASCII) == "123456");

    y = x.toByteString(3);
    assert(y.toString(ASCII) == "456");

    y = x.toByteString(2, 2);
    assert(y.toString(ASCII) == "34");

    y = x.toByteString(6, 0);
    assert(y.toString(ASCII) == "");

© Copyright 2003 - 2024 CardContact Systems GmbH , Minden, Germany