net.rim.device.api.util
Class TLEUtilities

java.lang.Object
  net.rim.device.api.util.TLEUtilities

public final class TLEUtilities
extends Object

Utility methods for manipulating type-length encoded (TLE) fields.

Method Summary
static boolean	findType(DataBuffer buffer, int type) Determines if a specific type is contained in the encoding from the current position to the end of the buffer.
static int	getFieldSize(int dataSize) Determines the number of bytes required to write a byte field.
static int	getIntegerFieldSize(int i) Determines the number of bytes required to write an integer type field.
static String	getStringFromBuffer(DataBuffer buf, int length) Retrieves string from provided buffer.
static void	parseBuffer(DataBuffer db, TLEFieldController con) Parses a DataBuffer using the given TLE field controller.
static void	parseField(DataBuffer db, TLEFieldController con, int length) Parses a field within a data buffer using the given TLE field controller.
static byte[]	readDataField(DataBuffer buf) Reads a field containing a sequence of bytes into a byte array.
static byte[]	readDataField(DataBuffer buf, int type) Reads a field containing a sequence of bytes into a byte array.
static int	readIntegerField(DataBuffer buf) Reads an integer field from the data buffer.
static int	readIntegerField(DataBuffer buf, int type) Reads an integer field from the data buffer.
static int	readIntegerFieldWithLength(DataBuffer buf, int length) Reads an integer field from the data buffer.
static String	readStringField(DataBuffer buf, boolean stripNull) Reads a field containing a sequence of bytes into a string.
static String	readStringField(DataBuffer buf, int type) Reads a field containing a sequence of bytes into a string.
static String	readStringField(DataBuffer buf, int type, boolean stripNull) Reads a field containing a sequence of bytes into a string.
static void	skipField(DataBuffer buffer) Skips over the next field in the DataBuffer.
static void	writeDataField(DataBuffer buf, int type, byte[] data) Writes a byte array field to the data buffer with the specified type.
static void	writeDataField(DataBuffer buf, int type, byte[] data, int offset, int length) Writes section of byte array field to the data buffer with the specified type.
static void	writeDataField(DataBuffer buf, int type, String value, int start, int len, boolean addNull) Writes section of String field to the data buffer with the specified type.
static void	writeField(DataBuffer db, int type, TLEFieldController con) Writes a TLE field into the DataBuffer.
static void	writeIntegerField(DataBuffer buf, int type, int value, boolean fixed) Writes an integer field to the data buffer with the specified type.
static void	writeStringField(DataBuffer buf, int type, String value) Writes a string field to the data buffer with the specified type.
static void	writeStringField(DataBuffer buf, int type, String value, boolean addNull) Writes a string field (with optional terminating null) to the data buffer with the specified type.
static void	writeStringField(DataBuffer buf, int type, String value, int offset, int length) Writes section of string field to the data buffer with the specified type.
static void	writeStringField(DataBuffer buf, int type, String value, int offset, int len, boolean addNull) Writes section of string field (with optional terminating null) to the data buffer with the specified type.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

parseBuffer

public static void parseBuffer(DataBuffer db,
                               TLEFieldController con)
                        throws IllegalArgumentException,
                               EOFException

Parses a DataBuffer using the given TLE field controller.

Parameters:

db - Data buffer to parse.

con - Controller to use during parsing.

Throws:

IllegalArgumentException

EOFException

parseField

public static void parseField(DataBuffer db,
                              TLEFieldController con,
                              int length)
                       throws IllegalArgumentException,
                              EOFException

Parses a field within a data buffer using the given TLE field controller.

Before parsing begins the data buffer's size is set to be the size of the field. The original size is then restored once parsing is finished. This routine is used to parse nested fields.

Parameters:

db - Data buffer to parse.

con - Controller to use during parsing.

length - Length of the field.

Throws:

IllegalArgumentException

EOFException

readIntegerField

public static int readIntegerField(DataBuffer buf,
                                   int type)
                            throws IllegalArgumentException,
                                   EOFException

Reads an integer field from the data buffer.

The type in the data buffer must match the specified type. An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Parameters:

buf - Data buffer containing the integer field.

type - Expected type.

Returns:

Integer read from field.

Throws:

IllegalArgumentException - if the types do not match, or if a suitable compressedInt value is not read from buf.

EOFException

readIntegerField

public static int readIntegerField(DataBuffer buf)
                            throws EOFException,
                                   IllegalArgumentException

Reads an integer field from the data buffer.

An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Parameters:

buf - Data buffer containing the integer field.

Returns:

Integer read from field.

Throws:

IllegalArgumentException - if buf parameter does not read a proper compressed integer value.

EOFException

Since:

BlackBerry API 4.0.0

readIntegerFieldWithLength

public static int readIntegerFieldWithLength(DataBuffer buf,
                                             int length)
                                      throws EOFException,
                                             IllegalArgumentException

Reads an integer field from the data buffer.

An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Primarily intended for use by TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer) methods.

Parameters:

buf - Data buffer containing the integer field.

length - the size of the contained integer. Should be one of: 1, 2 or 4.

Returns:

Integer read from field.

Throws:

IllegalArgumentException - if buf parameter does not read a proper compressed integer value.

EOFException

Since:

BlackBerry API 4.0.0

readDataField

public static byte[] readDataField(DataBuffer buf,
                                   int type)
                            throws IllegalArgumentException,
                                   EOFException

Reads a field containing a sequence of bytes into a byte array.

A new byte array is created to hold the data. The type in the data buffer must match the specified type.

Parameters:

buf - Databuffer containing the data bytes.

type - Expected type.

Returns:

Byte array containing data.

Throws:

IllegalArgumentException - if the types do not match.

EOFException

readDataField

public static byte[] readDataField(DataBuffer buf)
                            throws EOFException

Reads a field containing a sequence of bytes into a byte array.

A new byte array is created to hold the data. The type in the data buffer must match the specified type.

Parameters:

buf - Databuffer containing the data bytes.

Returns:

Byte array containing data.

Throws:

EOFException

Since:

BlackBerry API 4.0.0

readStringField

public static String readStringField(DataBuffer buf,
                                     int type)
                              throws IllegalArgumentException,
                                     EOFException

Reads a field containing a sequence of bytes into a string.

The bytes may or may not be null-terminated. The null-terminator will be stripped from the data stream before the string is made.

Parameters:

buf - Data buffer containing the data bytes.

type - Expected type.

Returns:

String containing data.

Throws:

IllegalArgumentException - if the types do not match.

EOFException

readStringField

public static String readStringField(DataBuffer buf,
                                     int type,
                                     boolean stripNull)
                              throws IllegalArgumentException,
                                     EOFException

Reads a field containing a sequence of bytes into a string.

Parameters:

buf - Data buffer containing the data bytes.

type - Expected type.

stripNull - Indicates if the null-terminator, if it exists, is to be stripped from the data stream before the string is made.

Returns:

String containing data.

Throws:

IllegalArgumentException - if the types do not match.

EOFException

Since:

BlackBerry API 3.6.0

readStringField

public static String readStringField(DataBuffer buf,
                                     boolean stripNull)
                              throws EOFException

Reads a field containing a sequence of bytes into a string.

Parameters:

buf - Data buffer containing the data bytes.

stripNull - Indicates if the null-terminator, if it exists, is to be stripped from the data stream before the string is made.

Returns:

String containing data.

Throws:

EOFException

Since:

BlackBerry API 4.0.0

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  byte[] data)

Writes a byte array field to the data buffer with the specified type.

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

data - Byte array containing bytes to write.

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  byte[] data,
                                  int offset,
                                  int length)

Writes section of byte array field to the data buffer with the specified type.

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

data - Byte array containing bytes to write.

start - First byte to write.

len - Number of bytes to write.

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  String value,
                                  int start,
                                  int len,
                                  boolean addNull)

Writes section of String field to the data buffer with the specified type.

The string is written as a sequence of ASCII bytes so this routine will not handle characters with values > 255. This differs from writeStringField which handles values > 255. Use this when a byte string *must* be written (eg. protocol headers, ...)

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

offset - First character of string value to write in the buffer.

len - Number of characters from string to write in the buffer.

addNull - If true, the field will be null terminated; if false, the field will not be null terminated.

Since:

BlackBerry API 3.7.0

writeField

public static void writeField(DataBuffer db,
                              int type,
                              TLEFieldController con)

Writes a TLE field into the DataBuffer.

Use this method when you don't know how big the field will be beforehand as it will automatically calculate the size once it is finished.

Parameters:

db - Data buffer to contain the written field.

type - Type of the field.

con - Controller to use to write the data.

writeIntegerField

public static void writeIntegerField(DataBuffer buf,
                                     int type,
                                     int value,
                                     boolean fixed)

Writes an integer field to the data buffer with the specified type.

A fixed integer field will always be 4 bytes, otherwise it can be either 1, 2 or 4 bytes in size(the smallest size field will be used to contain the given value).

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

fixed - If true, the field should have a fixed size of 4 bytes.

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value)

Writes a string field to the data buffer with the specified type.

The string written is not null terminated.

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

Since:

BlackBerry API 3.6.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    boolean addNull)

Writes a string field (with optional terminating null) to the data buffer with the specified type.

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

addNull - If true, the field will be null terminated; if false, the field will not be null terminated.

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    int offset,
                                    int length)

Writes section of string field to the data buffer with the specified type.

The string is not null terminated.

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

Since:

BlackBerry API 3.6.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    int offset,
                                    int len,
                                    boolean addNull)

Writes section of string field (with optional terminating null) to the data buffer with the specified type.

If all the characters are less than 255, then the substring is written in Latin-1. Otherwise, the bytes 0xFE 0xFF are written and the string is written in UCS-2(big endian). The encoded version may optionally be null-terminated (null termination in UCS-2 is 2 NUL bytes).

Parameters:

buf - Data buffer to contain the written field.

type - Type of the field.

value - Value to write.

offset - First character of string value to write in the buffer.

len - Number of characters from string to write in the buffer.

addNull - If true, the field will be null terminated; if false, the field will not be null terminated.

findType

public static boolean findType(DataBuffer buffer,
                               int type)

Determines if a specific type is contained in the encoding from the current position to the end of the buffer. If the type is found then the position of the buffer is updated to have that type as the next type.

Parameters:

buffer - the DataBuffer to examine.

type - the type to search for.

Returns:

a boolean indicating whether or not the type was found.

Since:

BlackBerry API 4.0.0

skipField

public static void skipField(DataBuffer buffer)
                      throws EOFException

Skips over the next field in the DataBuffer. This method asumes that the type is currently lined up as the next part to be read in the encoding.

Parameters:

buffer - the DataBuffer to skip the next field in.

Throws:

EOFException - if there is not enough data left in the buffer to skip.

Since:

BlackBerry API 4.0.0

getIntegerFieldSize

public static int getIntegerFieldSize(int i)

Determines the number of bytes required to write an integer type field.

Parameters:

i - Integer you want to write.

Returns:

Required field size for provided integer.

getFieldSize

public static final int getFieldSize(int dataSize)

Determines the number of bytes required to write a byte field.

Parameters:

dataSize - Number of bytes you want to write.

Returns:

Required field size to write your data bytes.

getStringFromBuffer

public static String getStringFromBuffer(DataBuffer buf,
                                         int length)

Retrieves string from provided buffer.

Used by TLEFieldControllers for getting Strings from data buffers (primarily with their TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer) methods).

Parameters:

buf - Data buffer containing the string that you want to extract

length - Length of the string to be extracted, as passed into TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer).

Returns:

String extracted from buffer.

Since:

BlackBerry API 4.0.0