SHOW Signed

net.rim.device.api.synchronization
Class ConverterUtilities

java.lang.Object
  |
  +--net.rim.device.api.synchronization.ConverterUtilities

public final class ConverterUtilities

extends Object

A set of static utility functions used when formatting or parsing data used during serial synchronization with the RIM desktop.

All data used by the RIM desktop is structured as a sequence of fields, each in the following format:

   Length<2> Type<1> Data<n>
 

where n is the length specified in the first short.

Data communication to or from the desktop must be in this format. Records that are not may either cause errors or may cause the data to be lost.

There are two ways that these utilities will typically be used. The first is to iterate over all fields in the buffer:

   buffer.rewind();
   try {
     for (;;) {
       int type;
       try {
         type = ConverterUtilities.getType( buffer );
       } catch (EOFException e) {
         // at end of buffer
         break;
       }
       switch (type) {
       case 1:
         // do something with ConverterUtilities.readString( buffer )
         break;
       case 2:
         // do something with ConverterUtilities.readString( buffer )
         break;
       }
     }
     // do something with the result.
   } catch (EOFException e) {
     // an error occurred
   }
 

The second is to search for specific fields in the buffer:

   try {
     buffer.rewind();
     while (ConverterUtilities.findType( buffer, 1 )) {
       // do something with ConverterUtilities.readString( buffer )
     }
     buffer.rewind();
     while (ConverterUtilities.findType( buffer, 2 )) {
       // do something with ConverterUtilities.readString( buffer )
     }
     // do something with the result.
   } catch (EOFException e) {
     // an error occurred
   }
 

Note that at any point where one might call ConverterUtilities.readString, you may also perform special processing to extract the next field, provided that the read/write pointer of the DataBuffer is advanced to the next field.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

See Also:

SyncConverter

Field Summary

static int

CONSUMED_FIELD A marker to indicate that the field has been consumed.

Method Summary

	static boolean	findType(DataBuffer buffer, int type) Finds the next field in the DataBuffer of the specified type.
	static int	getType(DataBuffer buffer) Extracts the type of the next field in the DataBuffer.
	static boolean	isType(DataBuffer buffer, int type) Determines whether the next field in the DataBuffer matches a specified type.
	static byte[]	readByteArray(DataBuffer buffer) Extracts a byte array from a DataBuffer.
	static byte[]	readByteArray(DataBuffer buffer, boolean markConsumed) Extracts a byte array from a DataBuffer.
	static int	readInt(DataBuffer buffer) Extracts an integer from a DataBuffer.
	static int	readInt(DataBuffer buffer, boolean markConsumed) Extracts an integer from a DataBuffer.
	static int[]	readIntArray(DataBuffer buffer) Extracts an integer array from a DataBuffer.
	static int[][]	readIntArrayArray(DataBuffer buffer, boolean allowNulls) Extracts an array of integer arrays from a DataBuffer.
	static long	readLong(DataBuffer buffer) Extracts a long integer from a DataBuffer.
	static long	readLong(DataBuffer buffer, boolean markConsumed) Extracts a long integer from a DataBuffer.
	static short[]	readShortArray(DataBuffer buffer) Extracts a short array from a DataBuffer.
	static String	readString(DataBuffer buffer) Calls readString( buffer, false ).
	static String	readString(DataBuffer buffer, boolean markConsumed) Extracts a string from a DataBuffer.
	static void	skipField(DataBuffer buffer) Skips over the next field in the DataBuffer.
	static void	writeByteArray(DataBuffer buffer, int type, byte[] s) Places a binary string with the specified type in the provided DataBuffer.
	static void	writeCharArrayArray(DataBuffer buffer, int type, char[][] array) Places an array of char arrays with the specified type in the provided DataBuffer.
	static void	writeEmptyField(DataBuffer buffer, int type) Places an empty field of the specified type in the provided DataBuffer.
	static void	writeInt(DataBuffer buffer, int type, int value) Places an integer scalar in the provided DataBuffer as 8 bytes.
	static void	writeIntArray(DataBuffer buffer, int type, int[] array) Places an array of integers with the specified type in the provided DataBuffer.
	static void	writeIntArrayArray(DataBuffer buffer, int type, int[][] array) Places an array of integer arrays with the specified type in the provided DataBuffer.
	static void	writeLong(DataBuffer buffer, int type, long value) Places a long scalar in the provided DataBuffer as 8 bytes.
	static void	writeShort(DataBuffer buffer, int type, short value) Places a long scalar in the provided DataBuffer as 8 bytes.
	static void	writeShortArray(DataBuffer buffer, int type, short[] array) Places an array of shorts with the specified type in the provided DataBuffer.
	static void	writeString(DataBuffer buffer, int type, String s) Writes an encoded string into the databuffer.

Methods inherited from class java.lang.Object

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

Field Detail

CONSUMED_FIELD

public static final int CONSUMED_FIELD

A marker to indicate that the field has been consumed.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

writeString

public static void writeString(DataBuffer buffer,
                               int type,
                               String s)

Writes an encoded string into the databuffer.

Newlines are kept as newlines. If the string contains non Latin-1 characters, the bytes 0xFE 0xFF are written followed by the 16 bit chars in big endian. For legacy reasons, if the string is encoded as bytes, and the string ends in 0x00, then an extra 0x00 may be appended to the end.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeByteArray

public static void writeByteArray(DataBuffer buffer,
                                  int type,
                                  byte[] s)

Places a binary string with the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the string.

type - The type to be used to tag the string.

s - The binary to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeCharArrayArray

public static void writeCharArrayArray(DataBuffer buffer,
                                       int type,
                                       char[][] array)

Places an array of char arrays with the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the array.

type - The type to be used to tag the array.

array - The array whose bytes are to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeInt

public static void writeInt(DataBuffer buffer,
                            int type,
                            int value)

Places an integer scalar in the provided DataBuffer as 8 bytes.

Parameters:

buffer - The DataBuffer to receive the data.

type - The type to be used to tag the data.

value - The integer to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeIntArray

public static void writeIntArray(DataBuffer buffer,
                                 int type,
                                 int[] array)

Places an array of integers with the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the array.

type - The type to be used to tag the array.

array - The array whose bytes are to be encoded

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeIntArrayArray

public static void writeIntArrayArray(DataBuffer buffer,
                                      int type,
                                      int[][] array)

Places an array of integer arrays with the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the array.

type - The type to be used to tag the array.

array - The array whose bytes are to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeShort

public static void writeShort(DataBuffer buffer,
                              int type,
                              short value)

Places a long scalar in the provided DataBuffer as 8 bytes.

Parameters:

buffer - The DataBuffer to receive the data.

type - The type to be used to tag the data.

value - The long to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeShortArray

public static void writeShortArray(DataBuffer buffer,
                                   int type,
                                   short[] array)

Places an array of shorts with the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the array.

type - The type to be used to tag the array.

array - The array whos bytes are to be encoded

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeLong

public static void writeLong(DataBuffer buffer,
                             int type,
                             long value)

Places a long scalar in the provided DataBuffer as 8 bytes.

Parameters:

buffer - The DataBuffer to receive the data.

type - The type to be used to tag the data.

value - The long to be encoded.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

writeEmptyField

public static void writeEmptyField(DataBuffer buffer,
                                   int type)

Places an empty field of the specified type in the provided DataBuffer.

Parameters:

buffer - The DataBuffer to receive the string.

type - The type to be used to tag the string.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getType

public static int getType(DataBuffer buffer)
                   throws EOFException

Extracts the type of the next field in the DataBuffer.

The read/write position of the DataBuffer is not affected by this function.

Parameters:

buffer - The buffer to examine.

Returns:

The type of the next field in the DataBuffer.

Throws:

EOFException - if there is insufficient data in the DataBuffer to extract a type field.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

skipField

public static void skipField(DataBuffer buffer)
                      throws EOFException

Skips over the next field in the DataBuffer.

Parameters:

buffer - The buffer to advance.

Throws:

EOFException - if there is insufficient data in the DataBuffer to advance past the field.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isType

public static boolean isType(DataBuffer buffer,
                             int type)

Determines whether the next field in the DataBuffer matches a specified type.

The read/write position of the DataBuffer is not affected by this function.

Parameters:

buffer - The DataBuffer to examine.

type - The type to be matched.

Returns:

true if the next field in the DataBuffer has the specified type; false if the next field does not have the specified type or if there is insufficient data in the DataBuffer to determine a field type.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readString

public static String readString(DataBuffer buffer)
                         throws EOFException

Calls readString( buffer, false ).

Parameters:

buffer - The DataBuffer from which to extract a null-terminated string.

Returns:

The String extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing a string.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readString

public static String readString(DataBuffer buffer,
                                boolean markConsumed)
                         throws EOFException

Extracts a string from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer. The maximum data size is 64kB.

The buffer is expected to be in the following format: If the first bytes are 0xFE 0xFF, then the buffer is encoded in big endian UTF-16. Otherwise, the buffer is encoded in ISO-8859-1.

In UTF-16 format: newlines are converted to 0x000A.

In ISO-8859-1 format: The buffer may have an extra byte 0x00 appended to the end (for a string with n 0x00 bytes at the end, n+1 are written so either 0 or 1 0x00 indicate this characters must not be included with the string). The control region (0x80- 0xA0) is enterpreted as on Windows and mapped into the Unicode character set. The character 0x000D is converted to 0x000A.

Parameters:

buffer - The DataBuffer from which to extract a null-terminated string.

markConsumed - Write a CONSUMED_FIELD marker to the field's type element. This can be used to see if the field has already been processed.

Returns:

The String extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing a string.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readByteArray

public static byte[] readByteArray(DataBuffer buffer)
                            throws EOFException

Extracts a byte array from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract a binary string

Returns:

The String extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing a string.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readByteArray

public static byte[] readByteArray(DataBuffer buffer,
                                   boolean markConsumed)
                            throws EOFException

Extracts a byte array from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract a string.

markConsumed - Writes a CONSUMED_FIELD marker to the field's type element. This can be used to see if the field has already been processed.

Returns:

The String extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing a string.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readShortArray

public static short[] readShortArray(DataBuffer buffer)
                              throws EOFException

Extracts a short array from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract an array.

Returns:

The array extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing an array.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readIntArray

public static int[] readIntArray(DataBuffer buffer)
                          throws EOFException

Extracts an integer array from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract an array.

Returns:

The array extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing an array.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readIntArrayArray

public static int[][] readIntArrayArray(DataBuffer buffer,
                                        boolean allowNulls)
                                 throws EOFException

Extracts an array of integer arrays from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract.

allowNulls - If false, forces allocation of zero length member arrays, if true sets zero length members to null.

Returns:

The array of arrays extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed field containing an array.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

findType

public static boolean findType(DataBuffer buffer,
                               int type)

Finds the next field in the DataBuffer of the specified type.

The read/write position of the DataBuffer is advanced to the beginning of the next field if possible. If not, the read/write position is left at the same place it started at.

Parameters:

buffer - The DataBuffer to examine.

type - The type to look for.

Returns:

true if a field of the specified type could be found; false otherwise.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readInt

public static int readInt(DataBuffer buffer)
                   throws EOFException

Extracts an integer from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract the int

Returns:

The int extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract an int.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readInt

public static int readInt(DataBuffer buffer,
                          boolean markConsumed)
                   throws EOFException

Extracts an integer from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract a long

markConsumed - Write a CONSUMED_FIELD marker to the field's type element. This can be used to see if the field has already been processed.

Returns:

The Integer extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed int.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readLong

public static long readLong(DataBuffer buffer)
                     throws EOFException

Extracts a long integer from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract the long

Returns:

The long extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a long.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

readLong

public static long readLong(DataBuffer buffer,
                            boolean markConsumed)
                     throws EOFException

Extracts a long integer from a DataBuffer.

The read/write position of the DataBuffer is advanced to the next field in the DataBuffer.

Parameters:

buffer - The DataBuffer from which to extract a long

markConsumed - Write a CONSUMED_FIELD marker to the field's type element. This can be used to see if the field has already been processed.

Returns:

The long integer extracted from the DataBuffer.

Throws:

EOFException - If there is insufficient data in the DataBuffer to correctly extract a well-formed int.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.