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 methods 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, where n is the length specified in the first short:

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

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;
       default:
         // Unrecognised tag, so ConverterUtilities.skipField( 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 readString(net.rim.device.api.util.DataBuffer), you may also perform special processing to extract the next field, provided that the read/write pointer of the data buffer 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.

Since:
JDE 3.6.0
See Also:
SyncConverter

Field Summary
 Category: Signed static int CONSUMED_FIELD
          Marker indicates that the field has been consumed.
 
Method Summary
 Category: Signed static boolean findType(DataBuffer buffer, int type)
          Finds the next field in the data buffer of the specified type.
 Category: Signed static int getType(DataBuffer buffer)
          Extracts the type of the next field in the data buffer.
 Category: Signed static boolean isType(DataBuffer buffer, int type)
          Determines whether the next field in the data buffer matches a specified type.
 Category: Signed static byte[] readByteArray(DataBuffer buffer)
          Extracts a byte array from a data buffer.
 Category: Signed static byte[] readByteArray(DataBuffer buffer, boolean markConsumed)
          Extracts a byte array from a data buffer.
 Category: Signed static int readInt(DataBuffer buffer)
          Extracts an integer from a data buffer.
 Category: Signed static int readInt(DataBuffer buffer, boolean markConsumed)
          Extracts an integer from a data buffer.
 Category: Signed static int[] readIntArray(DataBuffer buffer)
          Extracts an integer array from a data buffer.
 Category: Signed static int[][] readIntArrayArray(DataBuffer buffer, boolean allowNulls)
          Extracts an array of integer arrays from a data buffer.
 Category: Signed static long readLong(DataBuffer buffer)
          Extracts a long integer from a data buffer.
 Category: Signed static long readLong(DataBuffer buffer, boolean markConsumed)
          Extracts a long integer from a data buffer.
 Category: Signed static short[] readShortArray(DataBuffer buffer)
          Extracts a short array from a data buffer.
 Category: Signed static String readString(DataBuffer buffer)
          Extracts a string from a data buffer without consuming the field.
 Category: Signed static String readString(DataBuffer buffer, boolean markConsumed)
          Extracts a string from a DataBuffer.
 Category: Signed static void skipField(DataBuffer buffer)
          Skips over the next field in the data buffer.
 Category: Signed static void writeByteArray(DataBuffer buffer, int type, byte[] s)
          Writes a binary string with the specified type in the provided data buffer.
 Category: Signed static void writeCharArrayArray(DataBuffer buffer, int type, char[][] array)
          Writes an array of character arrays with the specified type in the provided data buffer.
 Category: Signed static void writeEmptyField(DataBuffer buffer, int type)
          Writes an empty field of the specified type in the provided data buffer.
 Category: Signed static void writeInt(DataBuffer buffer, int type, int value)
          Writes an integer scalar in the provided data buffer as 8 bytes.
 Category: Signed static void writeIntArray(DataBuffer buffer, int type, int[] array)
          Writes an array of integers with the specified type in the provided data buffer.
 Category: Signed static void writeIntArrayArray(DataBuffer buffer, int type, int[][] array)
          Writes an array of integer arrays with the specified type in the provided data buffer.
 Category: Signed static void writeLong(DataBuffer buffer, int type, long value)
          Writes a long scalar in the provided data buffer as 8 bytes.
 Category: Signed static void writeShort(DataBuffer buffer, int type, short value)
          Writes a short scalar in the provided data buffer as 8 bytes.
 Category: Signed static void writeShortArray(DataBuffer buffer, int type, short[] array)
          Writes an array of shorts with the specified type in the provided data buffer.
 Category: Signed static void writeString(DataBuffer buffer, int type, String text)
          Writes an encoded string into the provided data buffer.
 
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
Marker indicates that the field has been consumed.
Since:
JDE 3.6.0
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

readString

public static String readString(DataBuffer buffer)
                         throws EOFException
Extracts a string from a data buffer without consuming the field.

This method advances the read/write position of the data buffer to the next field in the buffer, but does not mark the read field as consumed: that is, it invokes readString(buffer,false).

Parameters:
buffer - The buffer from which to extract a null-terminated string.
Returns:
String extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing a string.
Since:
JDE 4.0.2
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.

This method advances the read/write position of the data buffer to the next field in the buffer. The maximum data size is 65535B.

The buffer is expected to be in one of the following formats:

If the first bytes are 0xFE 0xFF, then the buffer is encoded in UTF-16 big endian.
The BOM 0xFE 0xFF is removed and the remaining bytes are interpreted as UTF-16 big endian. Newlines are assumed to be 0x000A.

If the first bytes are 0xEF 0xBB 0xBF, then the buffer is encoded in UTF-8. Otherwise, the buffer is encoded in ISO-8859-1.
The BOM 0xEF 0xBB 0xBF is removed and the remaining bytes are interpreted as UTF-8. Newlines are assumed to be 0x000A.

In all other cases, the buffer is encoded in ISO-8859-1.
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 data buffer 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:
String extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing a string.
Since:
JDE 4.0.2
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.

writeString

public static void writeString(DataBuffer buffer,
                               int type,
                               String text)
Writes an encoded string into the provided data buffer.

In general, no transformations other than encoding take place. Newlines are kept as newlines (not converted to CRLF). No null termination is added. Other behaviour depends on the encoding of the buffer:

If the String contains Unicode
The bytes 0xFE 0xFF are written followed by the 16 bit chars in big endian UTF-16. The right of writing UTF-8 is reserved: compliant readers must handle the case where the buffer contains bytes 0xEF 0xBB 0xBF followed by the string in UTF-8.

If the String contains only ISO-8859-1
The string is written without a Unicode BOM, only a series of bytes ISO-8859-1 encoded. For legacy reasons, if the string is encoded as Latin-1 bytes and the string ends in 0x00, then an extra 0x00 is appended to the end.

Parameters:
buffer - Data buffer to contain written string.
type - Type byte to write into buffer before string.
text - String to write into buffer.
Since:
JDE 4.0.2
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)
Writes a binary string with the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the string.
type - Type to tag the string.
s - Byte array to encode.
Since:
JDE 4.0.2
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)
Writes an array of character arrays with the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the array.
type - Type to tag the array.
array - Array to encode.
Since:
JDE 4.0.2
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)
Writes an integer scalar in the provided data buffer as 8 bytes.
Parameters:
buffer - Data buffer to receive the data.
type - Type to tag the data.
value - Integer to encode.
Since:
JDE 4.0.2
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)
Writes an array of integers with the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the array.
type - Type to tag the array.
array - Array whose bytes to encode
Since:
JDE 4.0.2
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)
Writes an array of integer arrays with the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the array.
type - Type to tag the array.
array - Array whose bytes to encode.
Since:
JDE 4.0.2
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)
Writes a short scalar in the provided data buffer as 8 bytes.
Parameters:
buffer - Data buffer to receive the data.
type - Type to tag the data.
value - Short integer to encode.
Since:
JDE 4.0.2
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)
Writes an array of shorts with the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the array.
type - Type to tag the array.
array - Array whose bytes to encode.
Since:
JDE 4.0.2
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)
Writes a long scalar in the provided data buffer as 8 bytes.
Parameters:
buffer - Data buffer to receive the data.
type - Type to tag the data.
value - Long integer value to encode.
Since:
JDE 4.0.2
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)
Writes an empty field of the specified type in the provided data buffer.
Parameters:
buffer - Data buffer to receive the empty field.
type - Type to tag the empty field.
Since:
JDE 4.0.2
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 data buffer.

The read/write position of the data buffer is not affected by this method.

Parameters:
buffer - Buffer to examine.
Returns:
Type of the next field in the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to extract a type field.
Since:
JDE 4.0.2
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 data buffer.
Parameters:
buffer - Buffer to advance.
Throws:
EOFException - If there is insufficient data in the data buffer to advance past the field.
Since:
JDE 4.0.2
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 data buffer matches a specified type.

The read/write position of the data buffer is not affected by this method.

Parameters:
buffer - Data buffer to examine.
type - Type to be matched.
Returns:
TRUE if the next field in the data buffer has the specified type; FALSE if the next field does not have the specified type or if there is insufficient data in the data buffer to determine a field type.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer from which to extract a binary string.
Returns:
The String extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing a string.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer from which to extract a string.
markConsumed - If true, 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:
String extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing a string.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer from which to extract an array.
Returns:
The array extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing an array.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - The data buffer from which to extract an array.
Returns:
The array extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing an array.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer 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 data buffer. .
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed field containing an array.
Since:
JDE 4.0.2
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 data buffer of the specified type.

The read/write position of the data buffer 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 - Data buffer to examine.
type - Type to look for.
Returns:
True if a field of the specified type could be found; false otherwise.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer from which to extract the integer.
Returns:
Integer extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract an integer.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - The data buffer from which to extract an integer.
markConsumed - If true, 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:
Integer extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed integer.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - The data buffer from which to extract the long integer.
Returns:
Long integer extracted from the data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a long integer.
Since:
JDE 4.0.2
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 data buffer.

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

Parameters:
buffer - Data buffer from which to extract a long integer
markConsumed - If true, 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 data buffer.
Throws:
EOFException - If there is insufficient data in the data buffer to correctly extract a well-formed long integer.
Since:
JDE 4.0.2
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.


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.