com.syncbuilder.sync
Class Dlp

java.lang.Object
  |
  +--com.syncbuilder.sync.Dlp

public final class Dlp

extends java.lang.Object

A representation of a DLP (HotSync)-connection.

DLP is layered on top of a reliable stream and can initiate many operations on the Pilot, in the areas of Database operations and global information (system time, user ID, preferences).

From Developing Palm OS 2.0 Applications:

The Desktop Link Protocol (DLP) provides remote access to Palm OS data storage and other subsystems.

DLP facilitates efficient data synchronization between desktop (PC, Macintosh, etc.) and Palm OS applications, database backup, installation of code patches, extensions, applications, and other databases ...

Most method names have been taken from the original documentation as provided by Palm Computing, but some names have been changed to more closely resemble their true purpose.

See Also:

Socket

Field Summary

static int	DL_1_0 DL protocol version 1.0
static int	DL_1_1 DL protocol version 1.1
static int	DL_1_2 DL protocol version 1.2
static int	END_INCOMPATIBLE_PRODUCTS Synchronisation terminated because of incompatible versions of the DLP protocol on the Desktop and on the Palm device
static int	END_NORMAL Synchronisation ended normally
static int	END_OTHER Synchronisation ended with an unspecified problem
static int	END_OUT_OF_MEMORY Synchronisation ended because of low memory on the Palm device
static int	END_USER_CANCELLED Synchronisation ended because user cancelled the operation

Method Summary

void	addSyncLogEntry(java.lang.String message)
DeviceDatabase	createDB(DatabaseImpl dbimpl, int flags, int version) Create a new database on the default card of the Palm device.
DeviceDatabase	createDB(DatabaseImpl dbimpl, int flags, int version, int card) Create a new database on the specified card of the Palm device.
DeviceDatabase	createDB(java.lang.String name, Char4 creator, Char4 type, int flags, int version) Create a new database on the default card of the Palm device.
DeviceDatabase	createDB(java.lang.String name, Char4 creator, Char4 type, int flags, int version, int card) Create a new database on the specified card of the Palm device.
Pref	createPref(Char4 creator, int id) A factory method for a Pref object.
Pref	createPref(Char4 creator, int id, int version) A factory method for a Pref object.
Pref	createPref(Char4 creator, int id, int version, boolean backup)
void	deleteDB(java.lang.String dbname)
void	deleteDB(java.lang.String dbname, int card)
void	dlp_CleanUpDatabase(int handle)
void	dlp_CloseDB(int handle) CAUTION ****************** CAUTION ***************** CAUTION ***************** CAUTION *********** The following methods are very low-level.
void	dlp_DeleteRecord(int handle, int flags, int id) Delete records from a database.
void	dlp_DeleteResource(int handle, boolean all, Char4 type, int id)
DBInfo	dlp_findDBByName(int card, java.lang.String name)
DBInfo	dlp_findDBByOpenHandle(int handle)
void	dlp_MoveCategory(int handle, int from, int to)
AppBlock	dlp_ReadAppBlock(int handle, DatabaseImpl dbimpl)
Pref	dlp_ReadAppPreference(Char4 creator, int id, boolean backup, DatabaseImpl dbimpl)
Record	dlp_ReadNextModifiedRec(int handle, DatabaseImpl dbimpl)
Record	dlp_ReadNextModifiedRecInCategory(int handle, int category, DatabaseImpl dbimpl)
Record	dlp_ReadNextRecInCategory(int handle, int category, DatabaseImpl dbimpl)
int	dlp_readOpenDBInfo(int handle)
Record	dlp_ReadRecordByID(int handle, RecordID id, DatabaseImpl dbimpl)
Record	dlp_ReadRecordByIndex(int handle, int index, DatabaseImpl dbimpl)
RecordID[]	dlp_ReadRecordIDList(int handle, boolean sort, int start, int max)
Resource	dlp_ReadResourceByIndex(int handle, int index, DatabaseImpl dbimpl)
Resource	dlp_ReadResourceByType(int handle, Char4 type, int id, DatabaseImpl dbimpl)
SortBlock	dlp_ReadSortBlock(int handle, DatabaseImpl dbimpl)
void	dlp_ResetRecordIndex(int handle) Resets the "next record" index to the beginning
void	dlp_ResetSyncFlags(int handle)
void	dlp_WriteAppBlock(int handle, AppBlock appblock)
void	dlp_WriteRecord(int handle, Record record)
void	dlp_WriteResource(int handle, Resource resource)
void	dlp_WriteSortBlock(int handle, SortBlock sortblock)
void	endHotSync() Finish the HotSync-process successfully.
void	endHotSync(int status) Finish the HotSync-process with a specified status-code Invoking this method ends the life-cycle of the Dlp.
DBInfo	getDBInfo(int index, boolean RAM, boolean ROM, int card)
int	getFeature(Char4 creator, int number) Get the feature with the specified Creator ID and number
NetSyncInfo	getNetSyncInfo()
Pref	getPref(Char4 creator, int id) Get a Pref object that is associated with a particular application.
Pref	getPref(Char4 creator, int id, boolean backup) Get a Pref object that is associated with a particular application.
StorageInfo	getStorageInfo()
SysInfo	getSysInfo()
java.util.Date	getTime()
UserInfo	getUserInfo() Get information about the HotSync user.
int	getVersion() Get the protocol-version of the DL protocol.
DeviceDatabase	openDB(Char4 creator, java.lang.String name, int mode, int card) Open a database by its name, and with information about its creator.
DeviceDatabase	openDB(DatabaseImpl dbimpl) Open a database with a known DatabaseImpl.
DeviceDatabase	openDB(DatabaseImpl dbimpl, int mode) Open a database with a known DatabaseImpl.
DeviceDatabase	openDB(DatabaseImpl dbimpl, int mode, int card) Open a database with a known DatabaseImpl.
DeviceDatabase	openDB(java.lang.String name) Open a database by its name.
DeviceDatabase	openDB(java.lang.String name, int mode) Open a database by its name.
DeviceDatabase	openDB(java.lang.String name, int mode, int card) Open a database by its name.
void	processRPC(int trap, Index a0, Index d0, RPCParam[] params) Send an RPC for execution by the TouchDown RPC Executor (which is part of the Palm OS).
int	reopenDB(java.lang.String name, int mode, int card) Open a database by its name.
void	resetDevice()
void	setNetSyncInfo(NetSyncInfo info)
void	setPref(Pref pref) Set a Pref object that is associated with a particular application.
void	setTime(java.util.Date date)
void	setUserInfo(UserInfo uinfo)
void	switchMessage() This method serves two purposes: Switch the message on the Palm device from 'Identifying User' to 'Synchronizing'.

Methods inherited from class java.lang.Object

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

Field Detail

END_NORMAL

public static final int END_NORMAL

Synchronisation ended normally

END_OUT_OF_MEMORY

public static final int END_OUT_OF_MEMORY

Synchronisation ended because of low memory on the Palm device

END_USER_CANCELLED

public static final int END_USER_CANCELLED

Synchronisation ended because user cancelled the operation

END_OTHER

public static final int END_OTHER

Synchronisation ended with an unspecified problem

END_INCOMPATIBLE_PRODUCTS

public static final int END_INCOMPATIBLE_PRODUCTS

Synchronisation terminated because of incompatible versions of the DLP protocol on the Desktop and on the Palm device

DL_1_0

public static final int DL_1_0

DL protocol version 1.0

DL_1_1

public static final int DL_1_1

DL protocol version 1.1

DL_1_2

public static final int DL_1_2

DL protocol version 1.2

Method Detail

openDB

public DeviceDatabase openDB(java.lang.String name)
                      throws DlpException

Open a database by its name. Database will be opened R/W, exclusive. It will be looked for on card 0 (built-in).
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

Parameters:

name - the name of the database

openDB

public DeviceDatabase openDB(java.lang.String name,
                             int mode)
                      throws DlpException

Open a database by its name. Database will be looked for on card 0 (built-in).
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

Parameters:

name - the name of the database

mode - the mode in which the database will be opened. Use the Database.OPEN_*-constants.

openDB

public DeviceDatabase openDB(java.lang.String name,
                             int mode,
                             int card)
                      throws DlpException

Open a database by its name.
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

Parameters:

name - the name of the database

mode - the mode in which the database will be opened. Use the Database.OPEN_*-constants.

card - the memory card where the database is located. Current devices only support card #0 (CardInfo.DEFAULTCARD).

openDB

public DeviceDatabase openDB(Char4 creator,
                             java.lang.String name,
                             int mode,
                             int card)
                      throws DlpException

Open a database by its name, and with information about its creator. The creator ID will not be used to find the database, but to add more information to the resulting DeviceDatabase object.
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

Parameters:

creator - the creator ID of the database

name - the name of the database

mode - the mode in which the database will be opened. Use the Database.OPEN_*-constants.

card - the memory card where the database is located. Current devices only support card #0 (CardInfo.DEFAULTCARD).

openDB

public DeviceDatabase openDB(DatabaseImpl dbimpl)
                      throws DlpException

Open a database with a known DatabaseImpl.
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

openDB

public DeviceDatabase openDB(DatabaseImpl dbimpl,
                             int mode)
                      throws DlpException

Open a database with a known DatabaseImpl.
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

openDB

public DeviceDatabase openDB(DatabaseImpl dbimpl,
                             int mode,
                             int card)
                      throws DlpException

Open a database with a known DatabaseImpl.
Caution: It is impossible to keep more than one database open at the same time! This is a limitation of DLP and not of this framework. Use DeviceDatabase.close() to close databases.

createDB

public DeviceDatabase createDB(java.lang.String name,
                               Char4 creator,
                               Char4 type,
                               int flags,
                               int version)
                        throws DlpException

Create a new database on the default card of the Palm device. The name of the database needs to be unique! That means, no two databases on the same device may have an identical name, even if their other attributes (Creator, type), are different!

Parameters:

name - the name of the database

creator - the Creator ID

type - the type

flags -

version -

createDB

public DeviceDatabase createDB(java.lang.String name,
                               Char4 creator,
                               Char4 type,
                               int flags,
                               int version,
                               int card)
                        throws DlpException

Create a new database on the specified card of the Palm device. The name of the database needs to be unique! That means, no two databases on the same device may have an identical name, even if their other attributes (Creator, type), are different!

Parameters:

name - the name of the database

creator - the Creator ID

type - the type

flags -

version -

card - the memory card where the database is located. Current devices only support card #0 (CardInfo.DEFAULTCARD).

createDB

public DeviceDatabase createDB(DatabaseImpl dbimpl,
                               int flags,
                               int version)
                        throws DlpException

Create a new database on the default card of the Palm device. The name of the database needs to be unique! That means, no two databases on the same device may have an identical name, even if their other attributes (Creator, type), are different!

Parameters:

dbimpl - the DatabaseImpl to be used. This needs to have a known type!

flags -

version -

createDB

public DeviceDatabase createDB(DatabaseImpl dbimpl,
                               int flags,
                               int version,
                               int card)
                        throws DlpException

Create a new database on the specified card of the Palm device. The name of the database needs to be unique! That means, no two databases on the same device may have an identical name, even if their other attributes (Creator, type), are different!

Parameters:

dbimpl - the DatabaseImpl to be used. This needs to have a known type!

flags -

version -

card - the memory card where the database is located. Current devices only support card #0 (CardInfo.DEFAULTCARD).

deleteDB

public void deleteDB(java.lang.String dbname)
              throws DlpException

deleteDB

public void deleteDB(java.lang.String dbname,
                     int card)
              throws DlpException

getDBInfo

public DBInfo getDBInfo(int index,
                        boolean RAM,
                        boolean ROM,
                        int card)
                 throws DlpException

getPref

public Pref getPref(Char4 creator,
                    int id)
             throws DlpException

Get a Pref object that is associated with a particular application. Do not invoke this method while there is a database from the same application open! This will lead to problems with Palm devices running Palm OS 1.0! Use the getPref()-method from the DeviceDatabase class instead.

getPref

public Pref getPref(Char4 creator,
                    int id,
                    boolean backup)
             throws DlpException,
                    NoCreatorException

Get a Pref object that is associated with a particular application. Do not invoke this method while there is a database from the same application open! This will lead to problems with Palm devices running Palm OS 1.0! Use the getPref()-method from the DeviceDatabase class instead.

Returns:

Pref object, or null if the preference could not be found

setPref

public void setPref(Pref pref)
             throws DlpException

Set a Pref object that is associated with a particular application. Do not invoke this method while there is a database from the same application open! This will lead to problems with Palm devices running Palm OS 1.0! Use the setPref()-method from the DeviceDatabase class instead.

createPref

public Pref createPref(Char4 creator,
                       int id)
                throws DlpException,
                       NoCreatorException

A factory method for a Pref object. The new Pref will be a specialization of com.syncbuilder.storage.Pref that matches the specified creator. The Pref's version will be set to 1. It's backup-flag will be set.

Parameters:

creator - the creator ID

-

Returns:

a Pref object.

createPref

public Pref createPref(Char4 creator,
                       int id,
                       int version)
                throws DlpException,
                       NoCreatorException

A factory method for a Pref object. The new Pref will be a specialization of com.syncbuilder.storage.Pref that matches the specified creator and id. It's backup-flag will be set.

Returns:

a Pref object.

createPref

public Pref createPref(Char4 creator,
                       int id,
                       int version,
                       boolean backup)
                throws DlpException,
                       NoCreatorException

getFeature

public int getFeature(Char4 creator,
                      int number)
               throws DlpException,
                      NoCreatorException

Get the feature with the specified Creator ID and number

See Also:

SystemFeature

endHotSync

public void endHotSync()
                throws DlpException,
                       java.io.IOException

Finish the HotSync-process successfully. Invoking this method ends the life-cycle of the Dlp. It cannot be used afterwards.

endHotSync

public void endHotSync(int status)
                throws DlpException,
                       java.io.IOException

Finish the HotSync-process with a specified status-code Invoking this method ends the life-cycle of the Dlp. It cannot be used afterwards.

Parameters:

status - the way in which the HotSync ended (use Dlp.END_*-constants).

resetDevice

public void resetDevice()
                 throws DlpException

getStorageInfo

public StorageInfo getStorageInfo()
                           throws DlpException

getTime

public java.util.Date getTime()
                       throws DlpException

setTime

public void setTime(java.util.Date date)
             throws DlpException

getUserInfo

public UserInfo getUserInfo()
                     throws DlpException

Get information about the HotSync user.

Returns:

a filled-in UserInfo object or null if no user-information has been established on the device, yet.

setUserInfo

public void setUserInfo(UserInfo uinfo)
                 throws DlpException

getSysInfo

public SysInfo getSysInfo()
                   throws DlpException

switchMessage

public void switchMessage()
                   throws CancelSyncException,
                          DlpException

This method serves two purposes:

• Switch the message on the Palm device from 'Identifying User' to 'Synchronizing'.
• Probe for user cancel.

You should call this method before you start any synchronization work.

Throws:

CancelSyncException - The user cancelled the synchronization procedure

getNetSyncInfo

public NetSyncInfo getNetSyncInfo()
                           throws DlpException

setNetSyncInfo

public void setNetSyncInfo(NetSyncInfo info)
                    throws DlpException

addSyncLogEntry

public void addSyncLogEntry(java.lang.String message)
                     throws DlpException

processRPC

public void processRPC(int trap,
                       Index a0,
                       Index d0,
                       RPCParam[] params)
                throws DlpException

Send an RPC for execution by the TouchDown RPC Executor (which is part of the Palm OS). This is a poorly documented, high-risk method of executing arbitrary Palm OS system-functions through a DLP connection.

getVersion

public int getVersion()

Get the protocol-version of the DL protocol. This information can be used to distinguish devices running Palm OS 1.0 from those devices running Palm OS 2.0 and higher.
Devices running Palm OS 1.0 have limitations and bugs and therefore need to be treated specially in some respects.
The classes in this framework iron out these differences in a way that is completely transparent to the developer.

dlp_CloseDB

public void dlp_CloseDB(int handle)
                 throws DlpException

CAUTION ****************** CAUTION ***************** CAUTION ***************** CAUTION *********** The following methods are very low-level. You should use the high-level versions where possible. CAUTION ****************** CAUTION ***************** CAUTION ***************** CAUTION

reopenDB

public int reopenDB(java.lang.String name,
                    int mode,
                    int card)
             throws DlpException

Open a database by its name. Do not construct a DeviceDatabase object, but only return the handle.

dlp_readOpenDBInfo

public int dlp_readOpenDBInfo(int handle)
                       throws DlpException

dlp_CleanUpDatabase

public void dlp_CleanUpDatabase(int handle)
                         throws DlpException

dlp_MoveCategory

public void dlp_MoveCategory(int handle,
                             int from,
                             int to)
                      throws DlpException

dlp_ResetRecordIndex

public void dlp_ResetRecordIndex(int handle)
                          throws DlpException

Resets the "next record" index to the beginning

dlp_ResetSyncFlags

public void dlp_ResetSyncFlags(int handle)
                        throws DlpException

dlp_findDBByOpenHandle

public DBInfo dlp_findDBByOpenHandle(int handle)
                              throws DlpException

dlp_findDBByName

public DBInfo dlp_findDBByName(int card,
                               java.lang.String name)
                        throws DlpException

dlp_ReadRecordByIndex

public Record dlp_ReadRecordByIndex(int handle,
                                    int index,
                                    DatabaseImpl dbimpl)
                             throws DlpException

dlp_ReadRecordByID

public Record dlp_ReadRecordByID(int handle,
                                 RecordID id,
                                 DatabaseImpl dbimpl)
                          throws DlpException

dlp_WriteRecord

public void dlp_WriteRecord(int handle,
                            Record record)
                     throws DlpException

dlp_ReadNextRecInCategory

public Record dlp_ReadNextRecInCategory(int handle,
                                        int category,
                                        DatabaseImpl dbimpl)
                                 throws DlpException

dlp_ReadRecordIDList

public RecordID[] dlp_ReadRecordIDList(int handle,
                                       boolean sort,
                                       int start,
                                       int max)
                                throws DlpException

dlp_DeleteRecord

public void dlp_DeleteRecord(int handle,
                             int flags,
                             int id)
                      throws DlpException

Delete records from a database.

Parameters:

handle - DB handle

flags - 0x00 - delete rec with specified id, 0x80 - delete ALL recs, 0x40 - delete all recs with category id

id - record id, or category id (when flag is 0x40). Ignored when flag is 0x80.

dlp_ReadNextModifiedRec

public Record dlp_ReadNextModifiedRec(int handle,
                                      DatabaseImpl dbimpl)
                               throws DlpException

dlp_ReadNextModifiedRecInCategory

public Record dlp_ReadNextModifiedRecInCategory(int handle,
                                                int category,
                                                DatabaseImpl dbimpl)
                                         throws DlpException

dlp_WriteResource

public void dlp_WriteResource(int handle,
                              Resource resource)
                       throws DlpException

dlp_ReadResourceByType

public Resource dlp_ReadResourceByType(int handle,
                                       Char4 type,
                                       int id,
                                       DatabaseImpl dbimpl)
                                throws DlpException

dlp_ReadResourceByIndex

public Resource dlp_ReadResourceByIndex(int handle,
                                        int index,
                                        DatabaseImpl dbimpl)
                                 throws DlpException

dlp_DeleteResource

public void dlp_DeleteResource(int handle,
                               boolean all,
                               Char4 type,
                               int id)
                        throws DlpException

dlp_ReadAppPreference

public Pref dlp_ReadAppPreference(Char4 creator,
                                  int id,
                                  boolean backup,
                                  DatabaseImpl dbimpl)
                           throws DlpException

dlp_ReadAppBlock

public AppBlock dlp_ReadAppBlock(int handle,
                                 DatabaseImpl dbimpl)
                          throws DlpException

dlp_ReadSortBlock

public SortBlock dlp_ReadSortBlock(int handle,
                                   DatabaseImpl dbimpl)
                            throws DlpException

dlp_WriteAppBlock

public void dlp_WriteAppBlock(int handle,
                              AppBlock appblock)
                       throws DlpException

dlp_WriteSortBlock

public void dlp_WriteSortBlock(int handle,
                               SortBlock sortblock)
                        throws DlpException