org.jSyncManager.API.Conduit
Class ConduitHandler

java.lang.Object
  org.jSyncManager.API.Conduit.ConduitHandler

public final class ConduitHandler

extends java.lang.Object

The Conduit Handler class. This class provides high-level access to Palm data structures for synchronization logic classes conforming to the jConduit specification. Note that this class cannot be constructed outside its parent package. jConduits are passed an active instance of the ConduitHandler at sync time.

Version:

$Revision: 3.21 $

Author:

Brad BARCLAY <bbarclay@jsyncmanager.org>
Last modified by: $Author: yaztromo $ on $Date: 2004/08/16 03:11:00 $.

Field Summary

static java.awt.Frame	frame
static byte	READ_ID_LIST_SORT_FLAG
static double	version
static byte	WRITE_APP_PREF_BACKUP

Constructor Summary

ConduitHandler(ConduitManager cmanager, JHotSync jhotsync)
Constructs a new Conduit Handler object, using the specified jSyncManager instance as its parent, and the specified jHotSync instance for Palm communications.

Method Summary

void	addSyncLogEntry(java.lang.String text) Adds an entry to the Palm's synchronization log.
void	cleanupDatabase(byte dbID) Cleans-up the specified database.
void	closeAllDatabases() Closes all open databases.
void	closeDatabase(byte dbID) Closes a specified database.
void	closeVFSFile(FileReference file) Closes the specified file reference on a VFS volume.
byte	createDatabase(java.lang.String creator, java.lang.String type, java.lang.String dbName, char flags, char version) Creates a new database with the specified parameters.
void	createVFSDirectory(VolumeReference volRef, java.lang.String pathname) Creates the specified directory on the specified VFS volume.
void	createVFSFile(VolumeReference volRef, java.lang.String filename) Creates a file on the specified VFS volume.
void	deleteDatabase(java.lang.String dbName) Deletes the specified database.
void	deleteRecord(byte dbID, byte flags, int recordID) Deletes a record from the remote Palm.
void	deleteResource(byte dbID, byte flags, int type, char resourceID) Deletes the specified resource from the specified Palm database.
void	deleteVFSFile(VolumeReference volRef, java.lang.String filename) Deletes the specified file from a VFS filesystem.
DirectoryEntryEnumeration	enumerateDirectory(FileReference file, int iterator) Retrieves an enumeration of the entries in the specified directory.
VolumeReference[]	enumerateVFSVolumes() Enumerates all the VFS volumes available on the system.
void	exportDatabaseToVFSFile(VolumeReference volRef, char cardNum, int dbID, java.lang.String filename) Exports a handheld database to a file on a VFS filesystem.
DLPFindDBResponse	findDatabaseByCreator(byte flags, byte searchFlags, int type, int creator) Finds a database based on its creator information.
DLPFindDBResponse	findDatabaseByCreator(byte flags, byte searchFlags, java.lang.String type, java.lang.String creator) Finds a database based on its creator information.
DLPFindDBResponse	findDatabaseByName(byte flags, byte cardNumber, java.lang.String dbName) Finds the specified database by name.
DLPFindDBResponse	findDatabaseByOpenHandle(byte flags, byte dbID) Finds information on a database using its open database handle.
void	formatVFSVolume(MountParameters mountParams) Formats the specified VFS volume.
DLPBlock	getApplicationBlock(byte dbID) Retrieves the application block for the specified database.
DLPDatabaseInfo	getDatabaseInfo(java.lang.String dbName) Retrieves the Database Info object for a specified database.
java.util.Vector	getDatabaseInfoList() Retrieves a Vector containing the DLPDatabaseInfo objects for every database on the remote Palm.
java.lang.String	getDeviceSerialNumber() Retreives the handhelds serial number.
DLPExpansionCardInfo	getExpansionCardInfo(SlotReference slotRef) Reads the information for the specified expansion card.
SlotReference[]	getExpansionSlotEnumeration() Retrieves a list of the slot reference IDs present on this device.
java.awt.Frame	getFrameHandle() Returns a handle to the main jSyncManager frame.
int	getOpenDatabaseInfo(byte dbID) Returns the number of resources or records in a currently open database.
java.lang.Object	getProperty(java.lang.Object key) Gets a named property from the ConduitHandler.
int	getRecordCount(byte dbID) Deprecated. as of v1.1, this method has been renamed to getOpenDatabaseInfo.
DLPBlock	getSortBlock(byte dbID) Retrieves the Sort Block from the specified database, if one exists.
DLPStorageInfo	getStorageInfo() Deprecated. This method is no longer suggested for use, as it only returns storage information from the beginning of the synchronization process. Please use getStorageInfo(byte) instead.
DLPStorageInfo	getStorageInfo(byte card) Gets the current storage info for the specified memory card.
DLPSystemInfo	getSystemInfo() Retrieves the Palm's system information object.
DLPUserInfo	getUserInfo() Retrieves the user information from the Palm.
static double	getVersion() Returns the version number for this ConduitHandler class.
java.lang.String	getVFSDefaultDirectory(VolumeReference volRef, java.lang.String fileType) Retrieves the VFS Default Directory.
java.util.Calendar	getVFSFileDate(FileReference file, char dateType) Retrieves a file date for the specified file.
int	getVFSFileSize(FileReference file) Retrieves the size of the specified file.
VolumeInfo	getVFSVolumeInfo(VolumeReference volRef) Retrieves the volume information for the specified volume.
java.lang.String	getVFSVolumeLabel(VolumeReference volRef) Retrieves the VFS Volume label.
VolumeSize	getVFSVolumeSize(VolumeReference volRef) Retrieves the volume size information for the specified volume.
boolean	hasDatabase(java.lang.String dbName) Checks to see if the Palm has the specified database.
ImportDBFromVFSFileResponse	importDatabaseFromVFSFile(VolumeReference volRef, java.lang.String filename) Imports a handheld database from a file on a VFS filesystem.
boolean	isExpansionCardPresent(SlotReference slotRef) Tests to see wether a card is present in the specified expansion slot.
boolean	isModemSync() This method is used to determine wether this is a modem or cradle synchronization.
boolean	isPopupAllowed() Used to query wether the jSyncManager has been set to supress popups or not.
boolean	isVFSFileAtEOF(FileReference file) Determines wether or not the given file reference's pointer is at the End Of File (EOF).
char[]	makeVFSCustomControlRequest(int fsCreator, int apiCreator, char apiSelector, char[] buffer) VFS File custom control method.
void	moveCategory(byte dbID, byte to, byte from) Moves a category from one ID to another for the specified database.
void	openConduit() Informs the remote Palm that a new jConduit is being opened.
byte	openDatabase(java.lang.String dbName, byte mode) Opens the specified database in the specified mode.
FileReference	openVFSFile(VolumeReference volRef, char openMode, java.lang.String pathString) Opens a VFS file.
void	postToLog(java.lang.String s) Adds a text message to the jSyncManager's synchronization log.
float	queryDLPVersion() Queries the remote Palm's DLP version number.
int	queryVFSFileAttributes(FileReference file) Retrieves the file attributes for the specified file.
int	queryVFSFilePosition(FileReference file) Retrieves the location of the file pointer in the specified VFS file.
DLPAppPreference	readAppPreference(byte[] creatorID, char prefID, char size, byte flags) Reads the specified application preference.
DLPAppPreference	readAppPreference(int creatorID, char prefID, char size, byte flags) Reads the specified application preference.
DLPAppPreference	readAppPreference(java.lang.String creatorID, char prefID, char size, byte flags) Reads the specified application preference.
DLPDatabase	readDatabase(java.lang.String dbName) Reads an entire database from the Palm.
int	readFeature(int creator, char featureNum) Reads the specified feature from the handheld.
int	readFeature(java.lang.String creator, char featureNum) Reads the specified feature from the handheld.
DLPRecord	readNextModifiedRecord(byte dbID) Read the next record from the specified database which has it's Modified flag set.
DLPRecord	readNextModifiedRecordInCategory(byte dbID, byte category) Read the next record from the specified database and category which has it's Modified flag set.
DLPRecord	readNextRecordInCategory(byte dbID, byte category) Read the next record from the specified database and category.
DLPRecord	readRecord(byte dbID, char index) Deprecated. this method has been replaced by readRecordByIndex, as it is too easy to incorrectly cast and confuse calls between the overloaded readRecord methods.
DLPRecord	readRecord(byte dbID, int recordID) Deprecated. this method has been replaced by readRecordByID, as it is too easy to incorrectly cast and confuse calls between the overloaded readRecord methods.
DLPRecord	readRecordByID(byte dbID, int recordID) Reads the record from the specified database that has the specified record ID.
DLPRecord	readRecordByIndex(byte dbID, char recordIndex) Reads the record from the specified database that has the specified record index.
int[]	readRecordIDList(byte dbID, byte flags, char firstRecNum, char maximumEntries) Reads the ID list for the records contained within the specified database.
DLPResource	readResource(byte dbID, char resourceIndex) Deprecated. this method has been replaced by readResourceByIndex, as it is too easy to incorrectly cast and confuse calls between the overloaded readResource methods.
DLPResource	readResource(byte dbID, int type, char resourceID) Deprecated. this method has been replaced by readResourceByID, as it is too easy to incorrectly cast and confuse calls between the overloaded readResource methods.
DLPResource	readResourceByID(byte dbID, int type, char resourceID) Reads the resource from the specified database that has the specified resource ID.
DLPResource	readResourceByIndex(byte dbID, char resourceIndex) Reads the resource from the specified database that has the specified resource index.
byte[]	readVFSFile(FileReference file, int numBytes) Reads the specified number of bytes from a VFS file.
int	readVFSFileToStream(FileReference file, int numBytes, java.io.OutputStream out) Reads the specified number of bytes from a VFS file, and outputs it to a stream.
void	renameVFSFile(VolumeReference volRef, java.lang.String oldFilename, java.lang.String newFilename) Rennames the specified VFS file to the newly specified name.
void	resetRecordIndex(byte dbID) Resets the readNextModifiedRecord counters back to the beginning of the database.
void	resetSyncFlags(byte dbID) Resets all dirty flags in the specified database, and sorts the last sync time to now.
void	resetSystem() Causes the Palm to require a reboot after synchronization completes.
void	resizeVFSFile(FileReference file, int newSize) Resizes the specified file to the specified new size in bytes.
void	seekVFSFile(FileReference file, char origin, int offset) Seeks to the specified position in the specified VFS file.
void	setDatabaseInfo(byte dbID, char clearFlags, char setFlags, char dbVersion, DLP_Date creationDate, DLP_Date modifiedDate, DLP_Date backupDate, int dbTypeID, int dbCreator, java.lang.String dbName) Sets the specified information for a database.
static void	setFrameHandle(java.awt.Frame f) Sets the Frame handle to use for dialogs.
void	setStatus(java.lang.String status) Displays a text string in the Sync Windows status line.
void	setVFSFileAttributes(FileReference file, int attributes) Sets the atttributes for the specified file
void	setVFSFileDate(FileReference file, char dateType, java.util.Calendar newValue) Sets the specified date for the specified file.
void	setVFSVolumeLabel(VolumeReference volRef, java.lang.String newLabel) Sets the volume label for the specified VFS Volume.
void	startTickles() Starts the sending of tickle packets.
void	stopTickles() Stops the transmission of tickle packets.
void	storeProperty(java.lang.Object key, java.lang.Object data) Stores a jConduit property.
void	writeApplicationBlock(byte dbID, byte[] appBlock) Writes an application block to the remote device.
void	writeApplicationBlock(byte dbID, DLPBlock appBlock) Writes an application block to the remote device.
void	writeAppPreference(int creatorID, char prefID, byte flags, DLPAppPreference preference) Writes an application preference to the remote device.
void	writeDatabase(DLPDatabase dbName) Write an entire database to the remote device.
int	writeRecord(byte dbID, byte flags, DLPRecord record) Writes a record to the remote device.
int	writeRecord(byte dbID, byte flags, int recordID, byte attributes, byte category, byte[] data) Writes a record to the remote device.
void	writeResource(byte dbID, DLPResource resource) Writes a resource to the remote device.
void	writeResource(byte dbID, int type, char resourceID, byte[] data) Writes a resource to the remote device.
void	writeSortBlock(byte dbID, byte[] sortBlock) Writes an sort block to the remote device.
void	writeSortBlock(byte dbID, DLPBlock sortBlock) Writes an sort block to the remote device.
int	writeVFSFile(FileReference file, byte[] data) Write the specified data to a VFS file.
int	writeVFSFileFromStream(FileReference file, java.io.InputStream stream) Write the specified data stream to a VFS file.
int	writeVFSFileFromStream(FileReference file, java.io.InputStream stream, int length) Write the specified data stream to a VFS file.

Methods inherited from class java.lang.Object

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

Field Detail

version

public static final double version

See Also:

Constant Field Values

frame

public static java.awt.Frame frame

READ_ID_LIST_SORT_FLAG

public static final byte READ_ID_LIST_SORT_FLAG

See Also:

Constant Field Values

WRITE_APP_PREF_BACKUP

public static final byte WRITE_APP_PREF_BACKUP

See Also:

Constant Field Values

Constructor Detail

ConduitHandler

public ConduitHandler(ConduitManager cmanager,
                      JHotSync jhotsync)

Constructs a new Conduit Handler object, using the specified jSyncManager instance as its parent, and the specified jHotSync instance for Palm communications.

Parameters:

cmanager - a handle to the active instance of ConduitManager.

jhotsync - a handle to the active JHotSync object.

Method Detail

addSyncLogEntry

public void addSyncLogEntry(java.lang.String text)

Adds an entry to the Palm's synchronization log. Note that this data is not written to the Palm until the end of the synchronization process. An end-of-line will automatically be appended to each text object before writing.

Parameters:

text - the text string to write to the Palm's sync log.

cleanupDatabase

public void cleanupDatabase(byte dbID)
                     throws ConduitHandlerException,
                            NotConnectedException

Cleans-up the specified database. Calls to this method causes the Palm to discard any records flagged for deletion in the specified database. This should be called at the end of a database synchronization in order to free up memory on the Palm.

Parameters:

dbID - the handle of an open database to be cleaned up.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

closeAllDatabases

public void closeAllDatabases()
                       throws ConduitHandlerException,
                              NotConnectedException

Closes all open databases. This method will close every open database on the Palm.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

closeDatabase

public void closeDatabase(byte dbID)
                   throws ConduitHandlerException,
                          NotConnectedException

Closes a specified database. This method will immediately close the speficied open database.

Parameters:

dbID - the handle of the open database to be closed.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

createDatabase

public byte createDatabase(java.lang.String creator,
                           java.lang.String type,
                           java.lang.String dbName,
                           char flags,
                           char version)
                    throws ConduitHandlerException,
                           NotConnectedException

Creates a new database with the specified parameters. The newly created database will automatically be open. The returned byte will contain the database handle for use with subsequent read and write requests (don't forget to close the database when you're finished with it, otherwise you risk causing a "too many databases open" error during subsequent attempts to open databases).

Parameters:

creator - the 4 character creator ID for the database being created (if more than 4 characters are present, only the first four will be used).

type - the 4 character database type identifier for the database being created (if more than 4 characters are present, only the first four will be used).

dbName - the name of the database to create.

flags - the database creation flags.

version - the version number for the database being created.

Returns:

the database handle for the newly created database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

deleteDatabase

public void deleteDatabase(java.lang.String dbName)
                    throws ConduitHandlerException,
                           NotConnectedException

Deletes the specified database. This method deletes the specified database from the remote Palm device. Note that without a host-side backup, these deletions are permenent. The database to be deleted should not be open when specified for deletion, otherwise an error will occur.

Parameters:

dbName - the name of the database to delete.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

deleteRecord

public void deleteRecord(byte dbID,
                         byte flags,
                         int recordID)
                  throws ConduitHandlerException,
                         NotConnectedException

Deletes a record from the remote Palm.

Parameters:

dbID - the handle to the database containing the record to be deleted.

flags - the record deletion flags.

recordID - the ID number of the record to be deleted. If you are deleting a complete category (@see DLPRecord#DELETE_ALL_IN_CATEGORY), give the category ID here.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

for possible values.

deleteResource

public void deleteResource(byte dbID,
                           byte flags,
                           int type,
                           char resourceID)
                    throws ConduitHandlerException,
                           NotConnectedException

Deletes the specified resource from the specified Palm database.

Parameters:

dbID - the handle of the open database to delete the specified resource from.

flags - the resource flags to use during the deletion.

type - the resource type information.

resourceID - the ID number of the resource to delete.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getApplicationBlock

public DLPBlock getApplicationBlock(byte dbID)
                             throws ConduitHandlerException,
                                    NotConnectedException

Retrieves the application block for the specified database.

Parameters:

dbID - the handle of the open database from which to retrieve the Application Block.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getDatabaseInfo

public DLPDatabaseInfo getDatabaseInfo(java.lang.String dbName)
                                throws ConduitHandlerException

Retrieves the Database Info object for a specified database. Note that the jSyncManager collects this information at the beginning of the synchronization, thus this information may not be available for databases created since this time, and may be incorrect for databases created since this time.

Parameters:

dbName - the name of the database the retrieve information on.

Returns:

the DLPDatabaseInfo object for the requested database.

Throws:

ConduitHandlerException - thrown if the specified database did not exist at the start of sync.

getDatabaseInfoList

public java.util.Vector getDatabaseInfoList()

Retrieves a Vector containing the DLPDatabaseInfo objects for every database on the remote Palm. Note that this information is obtained at the beginning of synchronization, and thus may be out-of-date when read by a jConduit.

Returns:

a Vector of DLPDatabaseInfo objects.

See Also:

DLPDatabaseInfo

getFrameHandle

public java.awt.Frame getFrameHandle()

Returns a handle to the main jSyncManager frame. This method is suitable for grabbing the jSyncManager as a Frame object for passing into a Dialog constructor for jConduits requiring GUI display. This method returns null if the Frame parent has not been set.

Returns:

the Frame handle to the jSyncManager object.

getOpenDatabaseInfo

public int getOpenDatabaseInfo(byte dbID)
                        throws ConduitHandlerException,
                               NotConnectedException

Returns the number of resources or records in a currently open database.

Parameters:

dbID - the handle of the open database to query.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getProperty

public java.lang.Object getProperty(java.lang.Object key)

Gets a named property from the ConduitHandler. The ConduitHandler is constructed at the beginning of sync time, and is iteritively passed to each installed and active jConduit. Multiple jConduits which form a grouping may do simple inter-conduit communications by leaving a message with the ConduitHandler with a specified key, which can be later retrieved via this method by a subsequent jConduit. All such keys and values are destroyed at the end of synchronization - jConduits which require persistent storage should use their own object variables (note that all jConduit object variables are serialized persistently across jSyncManager invocations unless they are marked as being transient).

Parameters:

key - the key value to retrieve from the property hash.

Returns:

an Object corresponding to the associated key, or null if the specified key is not found.

See Also:

storeProperty(java.lang.Object, java.lang.Object)

getRecordCount

public int getRecordCount(byte dbID)
                   throws ConduitHandlerException,
                          NotConnectedException

Deprecated. as of v1.1, this method has been renamed to getOpenDatabaseInfo.

Returns the number of records in the specified database.

Parameters:

dbID - the handle of the open database to query.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

getOpenDatabaseInfo(byte)

getSortBlock

public DLPBlock getSortBlock(byte dbID)
                      throws ConduitHandlerException,
                             NotConnectedException

Retrieves the Sort Block from the specified database, if one exists.

Parameters:

dbID - the handle of the open database from which to retrieve the sort block, if one exists.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getStorageInfo

public DLPStorageInfo getStorageInfo()

Deprecated. This method is no longer suggested for use, as it only returns storage information from the beginning of the synchronization process. Please use getStorageInfo(byte) instead.

Retrieves the storage info object obtained at the beginning of the synchronization.

Returns:

the DLPStorageInfo object representing the storage information at the start of the synchronization.

See Also:

getStorageInfo(byte)

getStorageInfo

public DLPStorageInfo getStorageInfo(byte card)
                              throws ConduitHandlerException,
                                     NotConnectedException

Gets the current storage info for the specified memory card. Unlike getStorageInfo(), this method queries and returns the information directly from the Palm at the time of the call, and can thus be considered to be current and correct.

Parameters:

card - the card number to query (currently, this should always be set to 0).

Returns:

the DLPStorageInfo object for the specified memory card.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getSystemInfo

public DLPSystemInfo getSystemInfo()

Retrieves the Palm's system information object. Note that this information is obtained at the beginning of synchronization, however, this information does not change during the course of the synchronization, and thus is considered accurate.

Returns:

the DLPSystemInfo containing the Palm's system information.

getUserInfo

public DLPUserInfo getUserInfo()

Retrieves the user information from the Palm. Note that this information is obtained at the beginning of synchronization, however, this information does not change during the course of the synchronization, and thus is considered accurate.

Returns:

a DLPUserInfo object containing the current Palm users information.

getVersion

public static final double getVersion()

Returns the version number for this ConduitHandler class. The version number should be queried by jConduit which require methods and features not found in previous versions of the ConduitHandler in order to verify that they will be available.

Returns:

the ConduitHandler version, as a double.

hasDatabase

public boolean hasDatabase(java.lang.String dbName)
                    throws NotConnectedException

Checks to see if the Palm has the specified database. This information is based on the database information on the Palm as of the start of synchronization.

Parameters:

dbName - the name of the database to check for existance.

Throws:

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

isModemSync

public boolean isModemSync()

This method is used to determine wether this is a modem or cradle synchronization. This method is useful for jConduits which have different operations based on wether the synchronization type is via a local dock, or via a remote modem dialup.

Returns:

true if this is a modem synchronization, false otherwise.

isPopupAllowed

public boolean isPopupAllowed()

Used to query wether the jSyncManager has been set to supress popups or not. jConduits which present a GUI interface should honour this user setting by suppressing popups when this method returns false. This is important for embedded application use, and for modem and network synchronization where the Palm and user may not be present at the synchronization host to dismiss dialogs.

Returns:

boolean true if it's okay to display popups, false otherwise.

moveCategory

public void moveCategory(byte dbID,
                         byte to,
                         byte from)
                  throws ConduitHandlerException,
                         NotConnectedException

Moves a category from one ID to another for the specified database.

Parameters:

dbID - the handle of the open database in which to move the categories.

to - the category ID to move the records to.

from - the category ID to move the records from.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

openConduit

public void openConduit()
                 throws ConduitHandlerException,
                        NotConnectedException

Informs the remote Palm that a new jConduit is being opened. Calls to this method update the Palm's display during the HotSync to show that actions are being undertaken on the host side. Note that calling this method is not normally necessary, as the jSyncManager always makes this call prior to calling a jConduit's startSync(ConduitHandler) method. This method should only be used by jConduits which internally implement multiple conduits to multiple databases.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

openDatabase

public byte openDatabase(java.lang.String dbName,
                         byte mode)
                  throws ConduitHandlerException,
                         NotConnectedException

Opens the specified database in the specified mode.

Parameters:

dbName - the name of the database to open.

mode - the mode in which to open this database (see DLPDatabase for available modes).

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPDatabase

postToLog

public void postToLog(java.lang.String s)

Adds a text message to the jSyncManager's synchronization log. Note that this method will not display any text in the Sync Window's status line. If you require status info to be displayed, use setStatus(String).

Parameters:

s - a String to add to the jSyncManager synchronization log.

See Also:

setStatus(java.lang.String)

queryDLPVersion

public float queryDLPVersion()

Queries the remote Palm's DLP version number. This method is useful for jConduit which may sync differently for different DLP versions. Note that if this information is not available, this method will return 1.0.

Returns:

the DLP version number as a float consisting if major revision.minor revision

readAppPreference

public DLPAppPreference readAppPreference(int creatorID,
                                          char prefID,
                                          char size,
                                          byte flags)
                                   throws ConduitHandlerException,
                                          NotConnectedException

Reads the specified application preference.

Parameters:

creatorID - the app preference creator ID.

prefID - the desired preference ID.

size - the size in bytes to read.

flags - Valid preference flags.

Returns:

The DLPAppPreference object representing the requested app preference.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPAppPreference

readAppPreference

public DLPAppPreference readAppPreference(java.lang.String creatorID,
                                          char prefID,
                                          char size,
                                          byte flags)
                                   throws ConduitHandlerException,
                                          NotConnectedException

Reads the specified application preference.

Parameters:

creatorID - the app preference creator ID.

prefID - the desired preference ID.

size - the size in bytes to read.

flags - Valid preference flags.

Returns:

The DLPAppPreference object representing the requested app preference.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPAppPreference

readAppPreference

public DLPAppPreference readAppPreference(byte[] creatorID,
                                          char prefID,
                                          char size,
                                          byte flags)
                                   throws ConduitHandlerException,
                                          NotConnectedException

Reads the specified application preference.

Parameters:

creatorID - the app preference creator ID.

prefID - the desired preference ID.

size - the size in bytes to read.

flags - Valid preference flags.

Returns:

The DLPAppPreference object representing the requested app preference.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPAppPreference

readDatabase

public DLPDatabase readDatabase(java.lang.String dbName)
                         throws ConduitHandlerException,
                                NotConnectedException

Reads an entire database from the Palm. This method will read an entire database from the Palm, including all records, resources, blocks and attributes. The resulting database can be saved in serialized form, or as a PRC/PDB file, and otherwise generally manipulated.

Parameters:

dbName - the name of the Database to retrieve.

Returns:

a DLPDatabase object representing the desired database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readNextModifiedRecord

public DLPRecord readNextModifiedRecord(byte dbID)
                                 throws ConduitHandlerException,
                                        NotConnectedException

Read the next record from the specified database which has it's Modified flag set. This method will return the next modified record. Modified records are those which have been changed since the last synchronization. If there are no more modified records to be read, a ConduitHandlerException will be thrown with a DLP_Packet.ERR_NOT_FOUND result.

Parameters:

dbID - the ID of the database to read the next modified record from.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readNextModifiedRecordInCategory

public DLPRecord readNextModifiedRecordInCategory(byte dbID,
                                                  byte category)
                                           throws ConduitHandlerException,
                                                  NotConnectedException

Read the next record from the specified database and category which has it's Modified flag set. This method will return the next modified record in the specified category. Modified records are those which have been changed since the last synchronization. If there are no more modified records to be read, a ConduitHandlerException will be thrown with a DLP_Packet.ERR_NOT_FOUND result.

Parameters:

dbID - the ID of the database to read the next modified record from.

category - the category ID to read the record from.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readNextRecordInCategory

public DLPRecord readNextRecordInCategory(byte dbID,
                                          byte category)
                                   throws ConduitHandlerException,
                                          NotConnectedException

Read the next record from the specified database and category. This method will return the next record in the specified category. If there are no more records to be read, a ConduitHandlerException will be thrown with a DLP_Packet.ERR_NOT_FOUND result.

Parameters:

dbID - the ID of the database to read the next record from.

category - the category ID to read the record from.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readRecord

public DLPRecord readRecord(byte dbID,
                            char index)
                     throws ConduitHandlerException,
                            NotConnectedException

Deprecated. this method has been replaced by readRecordByIndex, as it is too easy to incorrectly cast and confuse calls between the overloaded readRecord methods.

Reads the record from the specified database that has the specified record index.

Parameters:

dbID - the ID of the database to read from.

index - the index of the record to be read. This index is a 1-based ordinal denoting the record order within the database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

readRecordByIndex(byte, char)

readRecord

public DLPRecord readRecord(byte dbID,
                            int recordID)
                     throws ConduitHandlerException,
                            NotConnectedException

Deprecated. this method has been replaced by readRecordByID, as it is too easy to incorrectly cast and confuse calls between the overloaded readRecord methods.

Reads the record from the specified database that has the specified record ID.

Parameters:

dbID - the ID of the database to read from.

recordID - the ID number of the record to be read. Record ID nubmers are unique identifiers for each record.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

readRecordByID(byte, int)

readRecordByID

public DLPRecord readRecordByID(byte dbID,
                                int recordID)
                         throws ConduitHandlerException,
                                NotConnectedException

Reads the record from the specified database that has the specified record ID.

Parameters:

dbID - the ID of the database to read from.

recordID - the ID number of the record to be read. Record ID nubmers are unique identifiers for each record.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readRecordByIndex

public DLPRecord readRecordByIndex(byte dbID,
                                   char recordIndex)
                            throws ConduitHandlerException,
                                   NotConnectedException

Reads the record from the specified database that has the specified record index.

Parameters:

dbID - the ID of the database to read from.

recordIndex - the index of the record to be read. This index is a 1-based ordinal denoting the record order within the database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readRecordIDList

public int[] readRecordIDList(byte dbID,
                              byte flags,
                              char firstRecNum,
                              char maximumEntries)
                       throws ConduitHandlerException,
                              NotConnectedException

Reads the ID list for the records contained within the specified database. This method returns a list of ID numbers contained within the selected database.

Parameters:

dbID - the handle to the open database.

flags - Set to ConduitHandler.READ_ID_LIST_SORT_FLAG to sort the returned record IDs, or 0 otherwise.

firstRecNum - the first record index number to return. If out of bounds, a ConditHandlerException will be thrown with DLP_Packet.ERR_NOT_FOUND set.

maximumEntries - the maximum number of entries to return.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readResource

public DLPResource readResource(byte dbID,
                                char resourceIndex)
                         throws ConduitHandlerException,
                                NotConnectedException

Deprecated. this method has been replaced by readResourceByIndex, as it is too easy to incorrectly cast and confuse calls between the overloaded readResource methods.

Reads the resource from the specified database that has the specified resource index.

Parameters:

dbID - the ID of the database to read from.

resourceIndex - the index of the resource to be read. This index is a 1-based ordinal denoting the resource order within the database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

readResourceByIndex(byte, char)

readResource

public DLPResource readResource(byte dbID,
                                int type,
                                char resourceID)
                         throws ConduitHandlerException,
                                NotConnectedException

Deprecated. this method has been replaced by readResourceByID, as it is too easy to incorrectly cast and confuse calls between the overloaded readResource methods.

Reads the resource from the specified database that has the specified resource ID.

Parameters:

dbID - the ID of the database to read from.

type - the resource type.

resourceID - the ID number of the resource to be read. Resource ID numbers are unique identifiers for each resource.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

readResourceByID(byte, int, char)

readResourceByID

public DLPResource readResourceByID(byte dbID,
                                    int type,
                                    char resourceID)
                             throws ConduitHandlerException,
                                    NotConnectedException

Reads the resource from the specified database that has the specified resource ID.

Parameters:

dbID - the ID of the database to read from.

type - the resource type.

resourceID - the ID number of the resource to be read. Resource ID numbers are unique identifiers for each resource.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readResourceByIndex

public DLPResource readResourceByIndex(byte dbID,
                                       char resourceIndex)
                                throws ConduitHandlerException,
                                       NotConnectedException

Reads the resource from the specified database that has the specified resource index.

Parameters:

dbID - the ID of the database to read from.

resourceIndex - the index of the resource to be read. This index is a 1-based ordinal denoting the resource order within the database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

resetRecordIndex

public void resetRecordIndex(byte dbID)
                      throws ConduitHandlerException,
                             NotConnectedException

Resets the readNextModifiedRecord counters back to the beginning of the database. Calling this method will reset where the readNextModifiedRecord methods read records from. It resets the pointer back to the first modified record in the specified database.

Parameters:

dbID - the handle to the database to reset.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

resetSyncFlags

public void resetSyncFlags(byte dbID)
                    throws ConduitHandlerException,
                           NotConnectedException

Resets all dirty flags in the specified database, and sorts the last sync time to now. Calls to this method will reset all of the modified flags for the specified database. The database last sync time will also be set to the time of this call.

Parameters:

dbID - the handle to the database to reset.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

resetSystem

public void resetSystem()
                 throws ConduitHandlerException,
                        NotConnectedException

Causes the Palm to require a reboot after synchronization completes. Calls to this method will cause the Palm, at the end of sync, to tell the user that their Palm needs to be restarted, providing them with a button to do so. This method should only be called for OS patches and other system-level databases that require a system restart to take effect.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

setFrameHandle

public static void setFrameHandle(java.awt.Frame f)

Sets the Frame handle to use for dialogs. Note that jConduits should not call this method.

Parameters:

f - the Frame object handle.

setStatus

public void setStatus(java.lang.String status)

Displays a text string in the Sync Windows status line. Calls to this method display the specified text in the jSyncManager's Sync Window status line, and also adds the specified text to the jSyncManager's synchronization log. To post just to the log, please use postToLog(String).

Parameters:

status - the status String to be displayed.

See Also:

postToLog(java.lang.String)

startTickles

public void startTickles()

Starts the sending of tickle packets. Tickle packets are transmitted to the Palm from the PADP protocol layer in order to prevent timeouts during lengthy operations, and are sent at predetermined intervals until explicitly stopped. This method should be called by jConduit before doing any stenuous operations, such as file IO, which may cause the Palm time out before processing is completed. Tickle packets should be explicitly stopped before making any other calls to this class.

See Also:

stopTickles()

stopTickles

public void stopTickles()

Stops the transmission of tickle packets.

See Also:

startTickles()

storeProperty

public void storeProperty(java.lang.Object key,
                          java.lang.Object data)

Stores a jConduit property.

See Also:

getProperty(java.lang.Object)

writeApplicationBlock

public void writeApplicationBlock(byte dbID,
                                  DLPBlock appBlock)
                           throws ConduitHandlerException,
                                  NotConnectedException

Writes an application block to the remote device. This method will write an application block to the specified database.

Parameters:

dbID - the handle to an open database to write the app block to.

appBlock - the application block (as a DLPBlock object) to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

writeApplicationBlock

public void writeApplicationBlock(byte dbID,
                                  byte[] appBlock)
                           throws ConduitHandlerException,
                                  NotConnectedException

Writes an application block to the remote device. This method will write an application block to the specified database.

Parameters:

dbID - the handle to an open database to write the app block to.

appBlock - the application block (as an array of bytes) to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

writeAppPreference

public void writeAppPreference(int creatorID,
                               char prefID,
                               byte flags,
                               DLPAppPreference preference)
                        throws ConduitHandlerException,
                               NotConnectedException

Writes an application preference to the remote device. This method allows for the writing aof application preferences to the remote device.

Parameters:

creatorID - the desired creator ID.

prefID - the desired preference ID.

flags - Set to either ConduitHandler.WRITE_APP_PREF_BACKUP to restore a backed up app preference. Set to 0 otherwise.

preference - the preference to write.

Throws:

jSyncManager.Protocol.DLPFunctionCallException - The exception description.

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

writeDatabase

public void writeDatabase(DLPDatabase dbName)
                   throws ConduitHandlerException,
                          NotConnectedException

Write an entire database to the remote device. Calls to this method allow for the writing of an entire DLPDatabase object to the remote device.

Parameters:

dbName - the DLPDatabase object to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

writeRecord

public int writeRecord(byte dbID,
                       byte flags,
                       int recordID,
                       byte attributes,
                       byte category,
                       byte[] data)
                throws ConduitHandlerException,
                       NotConnectedException

Writes a record to the remote device. This method will write the specified record to the remote device.

Parameters:

dbID - the open database handle to write to.

flags - the record writing flags. See DLPRecord for valid flags.

recordID - the ID of the record to be written. Set to 0 to allow the remote device to assign a suitable ID number.

attributes - the record attributes. See DLPRecord for valid attributes.

category - the category ID to write to.

data - the record data to be written.

Returns:

the records ID number.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPRecord

writeRecord

public int writeRecord(byte dbID,
                       byte flags,
                       DLPRecord record)
                throws ConduitHandlerException,
                       NotConnectedException

Writes a record to the remote device. This method will write the specified record to the remote device.

Parameters:

dbID - the open database handle to write to.

flags - the record writing flags. See DLPRecord for valid flags.

record - the DLPRecord object to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPRecord

writeResource

public void writeResource(byte dbID,
                          int type,
                          char resourceID,
                          byte[] data)
                   throws ConduitHandlerException,
                          NotConnectedException

Writes a resource to the remote device. This method will write the specified resource to the remote device.

Parameters:

dbID - the open database handle to write to.

type - the resource type buing written.

resourceID - the ID of the resource to be written. Set to 0 to allow the remote device to assign a suitable ID number.

data - the byte array containing the resource data to be written.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPResource

writeResource

public void writeResource(byte dbID,
                          DLPResource resource)
                   throws ConduitHandlerException,
                          NotConnectedException

Writes a resource to the remote device. This method will write the specified resource to the remote device.

Parameters:

dbID - the open database handle to write to.

resource - the DLPResource object to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

See Also:

DLPResource

writeSortBlock

public void writeSortBlock(byte dbID,
                           DLPBlock sortBlock)
                    throws ConduitHandlerException,
                           NotConnectedException

Writes an sort block to the remote device. This method will write an sort block to the specified database.

Parameters:

dbID - the handle to an open database to write the sort block to.

sortBlock - the sort block (as a DLPBlock object) to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

writeSortBlock

public void writeSortBlock(byte dbID,
                           byte[] sortBlock)
                    throws ConduitHandlerException,
                           NotConnectedException

Writes an sort block to the remote device. This method will write an sort block to the specified database.

Parameters:

dbID - the handle to an open database to write the sort block to.

sortBlock - the sort block (as an array of bytes) to write.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getDeviceSerialNumber

public java.lang.String getDeviceSerialNumber()
                                       throws ConduitHandlerException,
                                              NotConnectedException

Retreives the handhelds serial number. This method uses RPC to read the serial number of the handheld device. Note that this function may not work on all handheld devices.

Returns:

a String containing the serial number information.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readFeature

public int readFeature(int creator,
                       char featureNum)
                throws ConduitHandlerException,
                       NotConnectedException

Reads the specified feature from the handheld. Features are used to store short application-specific data from the handheld. Features are stored as a 4-byte value, and are identified by a creator ID and a feature number.

Parameters:

creator - the creator ID, expressed as an integer.

featureNum - the feature number to be read.

Returns:

the requested feature value.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

readFeature

public int readFeature(java.lang.String creator,
                       char featureNum)
                throws ConduitHandlerException,
                       NotConnectedException

Reads the specified feature from the handheld. Features are used to store short application-specific data from the handheld. Features are stored as a 4-byte value, and are identified by a creator ID and a feature number.

Parameters:

creator - the 4-character creator ID, expressed as a String.

featureNum - the feature number to be read.

Returns:

the requested feature value.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

openVFSFile

public FileReference openVFSFile(VolumeReference volRef,
                                 char openMode,
                                 java.lang.String pathString)
                          throws ConduitHandlerException,
                                 NotConnectedException

Opens a VFS file.

Parameters:

volRef - the volume reference to open the file from.

openMode - the open mode flags for the file.

pathString - the path and filename of the file to open.

Returns:

the file reference to the opened file.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

setDatabaseInfo

public void setDatabaseInfo(byte dbID,
                            char clearFlags,
                            char setFlags,
                            char dbVersion,
                            DLP_Date creationDate,
                            DLP_Date modifiedDate,
                            DLP_Date backupDate,
                            int dbTypeID,
                            int dbCreator,
                            java.lang.String dbName)
                     throws ConduitHandlerException,
                            NotConnectedException

Sets the specified information for a database.

Parameters:

dbID - the database ID handle of the database to modify.

clearFlags - a set of flags to denote which fields should be cleared.

setFlags - a set of flags to denote which flags should be set.

dbVersion - the new database version.

creationDate - the new creation date for the database.

modifiedDate - the new modification date for the database.

backupDate - the new backup date for the database.

dbTypeID - the databases new type ID.

dbCreator - the new creator for the database.

dbName - the new name for the database.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

findDatabaseByName

public DLPFindDBResponse findDatabaseByName(byte flags,
                                            byte cardNumber,
                                            java.lang.String dbName)
                                     throws ConduitHandlerException,
                                            NotConnectedException

Finds the specified database by name.

Parameters:

flags - the search flags to use.

cardNumber - the card number to search on.

dbName - the name of the database to find.

Returns:

the handhelds search results object.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

findDatabaseByOpenHandle

public DLPFindDBResponse findDatabaseByOpenHandle(byte flags,
                                                  byte dbID)
                                           throws ConduitHandlerException,
                                                  NotConnectedException

Finds information on a database using its open database handle.

Parameters:

flags - the search flags to use.

dbID - the open database handle to query.

Returns:

the handhelds search results object.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

findDatabaseByCreator

public DLPFindDBResponse findDatabaseByCreator(byte flags,
                                               byte searchFlags,
                                               int type,
                                               int creator)
                                        throws ConduitHandlerException,
                                               NotConnectedException

Finds a database based on its creator information.

Parameters:

flags - the search flags to use.

searchFlags - the search flags to use.

type - the type information for the database to find.

creator - the creator ID of the database to find.

Returns:

the handhelds search results object.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

findDatabaseByCreator

public DLPFindDBResponse findDatabaseByCreator(byte flags,
                                               byte searchFlags,
                                               java.lang.String type,
                                               java.lang.String creator)
                                        throws ConduitHandlerException,
                                               NotConnectedException

Finds a database based on its creator information.

Parameters:

flags - the search flags to use.

searchFlags - the search flags to use.

type - the type information for the database to find.

creator - the creator ID of the database to find.

Returns:

the handhelds search results object.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getExpansionSlotEnumeration

public SlotReference[] getExpansionSlotEnumeration()
                                            throws ConduitHandlerException,
                                                   NotConnectedException

Retrieves a list of the slot reference IDs present on this device. To query the number of slots, use returnedValue.length.

Returns:

a list of the slot reference IDs present on this device.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

isExpansionCardPresent

public boolean isExpansionCardPresent(SlotReference slotRef)
                               throws ConduitHandlerException,
                                      NotConnectedException

Tests to see wether a card is present in the specified expansion slot.

Parameters:

slotRef - the expansion slot reference to test.

Returns:

true if a card is present, false otherwise.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

getExpansionCardInfo

public DLPExpansionCardInfo getExpansionCardInfo(SlotReference slotRef)
                                          throws ConduitHandlerException,
                                                 NotConnectedException

Reads the information for the specified expansion card.

Parameters:

slotRef - the expansion slot reference to query.

Returns:

the information for the specified expansion card.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - thrown if the connection to the Palm has been or is lost during this method call.

makeVFSCustomControlRequest

public char[] makeVFSCustomControlRequest(int fsCreator,
                                          int apiCreator,
                                          char apiSelector,
                                          char[] buffer)
                                   throws ConduitHandlerException,
                                          NotConnectedException

VFS File custom control method. Calls to this method will make the corresponding custom control calls to the handhelds VFS Manager filesystem API.

Parameters:

fsCreator - the fsCreator value.

apiCreator - the apiCreator value.

apiSelector - the API Selector

buffer - the data to transmit with this request.

Returns:

an array of char containing the returned data.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSDefaultDirectory

public java.lang.String getVFSDefaultDirectory(VolumeReference volRef,
                                               java.lang.String fileType)
                                        throws ConduitHandlerException,
                                               NotConnectedException

Retrieves the VFS Default Directory.

Parameters:

volRef - the volume reference number of the volume to query.

fileType - a String containing the file type information.

Returns:

the default directory for the specified volume and filetype.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

createVFSFile

public void createVFSFile(VolumeReference volRef,
                          java.lang.String filename)
                   throws ConduitHandlerException,
                          NotConnectedException

Creates a file on the specified VFS volume.

Parameters:

volRef - the volume reference number of the volume to query.

filename - a String containing the files path and filename.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

closeVFSFile

public void closeVFSFile(FileReference file)
                  throws ConduitHandlerException,
                         NotConnectedException

Closes the specified file reference on a VFS volume.

Parameters:

file - the file reference of the file to close.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

importDatabaseFromVFSFile

public ImportDBFromVFSFileResponse importDatabaseFromVFSFile(VolumeReference volRef,
                                                             java.lang.String filename)
                                                      throws ConduitHandlerException,
                                                             NotConnectedException

Imports a handheld database from a file on a VFS filesystem. Calling this method will take a PRC or PDB file on a VFS volume, and will install it as a handheld database.

Parameters:

volRef - the volume reference number of the volume to query.

filename - a String containing the files path and filename.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

exportDatabaseToVFSFile

public void exportDatabaseToVFSFile(VolumeReference volRef,
                                    char cardNum,
                                    int dbID,
                                    java.lang.String filename)
                             throws ConduitHandlerException,
                                    NotConnectedException

Exports a handheld database to a file on a VFS filesystem. Calling this method will take a handheld database, and will then save it to a VFS filesystem as a PRC or PDB file.

Parameters:

volRef - the volume reference number of the volume to query.

cardNum - the card number the database resides on.

dbID - the databases ID number.

filename - a String containing the files path and filename.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

deleteVFSFile

public void deleteVFSFile(VolumeReference volRef,
                          java.lang.String filename)
                   throws ConduitHandlerException,
                          NotConnectedException

Deletes the specified file from a VFS filesystem.

Parameters:

volRef - the volume reference number of the volume to delete from.

filename - a String containing the files path and filename.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

renameVFSFile

public void renameVFSFile(VolumeReference volRef,
                          java.lang.String oldFilename,
                          java.lang.String newFilename)
                   throws ConduitHandlerException,
                          NotConnectedException

Rennames the specified VFS file to the newly specified name.

Parameters:

volRef - the volume reference number of the volume to delete from.

oldFilename - a String containing the name of the file to be renamed.

newFilename - a String containing the new name for the file.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

queryVFSFilePosition

public int queryVFSFilePosition(FileReference file)
                         throws ConduitHandlerException,
                                NotConnectedException

Retrieves the location of the file pointer in the specified VFS file.

Parameters:

file - the file reference of the file to query.

Returns:

an integer containing the value for the specified files current I/O position pointer.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

resizeVFSFile

public void resizeVFSFile(FileReference file,
                          int newSize)
                   throws ConduitHandlerException,
                          NotConnectedException

Resizes the specified file to the specified new size in bytes.

Parameters:

file - the file reference of the file to resize.

newSize - the new size of the file.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

queryVFSFileAttributes

public int queryVFSFileAttributes(FileReference file)
                           throws ConduitHandlerException,
                                  NotConnectedException

Retrieves the file attributes for the specified file.

Parameters:

file - the file reference of the file to query.

Returns:

an integer containing the files attributes bitmap.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

setVFSFileAttributes

public void setVFSFileAttributes(FileReference file,
                                 int attributes)
                          throws ConduitHandlerException,
                                 NotConnectedException

Sets the atttributes for the specified file

Parameters:

file - the file reference of the file to set the attributes for.

attributes - the new file attributes bitmap.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSFileSize

public int getVFSFileSize(FileReference file)
                   throws ConduitHandlerException,
                          NotConnectedException

Retrieves the size of the specified file.

Parameters:

file - the file reference of the file to query.

Returns:

an integer containing the requested file size.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

createVFSDirectory

public void createVFSDirectory(VolumeReference volRef,
                               java.lang.String pathname)
                        throws ConduitHandlerException,
                               NotConnectedException

Creates the specified directory on the specified VFS volume.

Parameters:

volRef - the volume reference number of the volume to create the directory onto.

pathname - a String containing the directory's path.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

enumerateVFSVolumes

public VolumeReference[] enumerateVFSVolumes()
                                      throws ConduitHandlerException,
                                             NotConnectedException

Enumerates all the VFS volumes available on the system.

Returns:

a char array containing all of the available VFS volumes on the handheld device.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSVolumeLabel

public java.lang.String getVFSVolumeLabel(VolumeReference volRef)
                                   throws ConduitHandlerException,
                                          NotConnectedException

Retrieves the VFS Volume label.

Parameters:

volRef - the volume reference number of the volume to query.

Returns:

the volume label for the specified VFS volume.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

setVFSVolumeLabel

public void setVFSVolumeLabel(VolumeReference volRef,
                              java.lang.String newLabel)
                       throws ConduitHandlerException,
                              NotConnectedException

Sets the volume label for the specified VFS Volume.

Parameters:

volRef - the volume reference number of the volume to query.

newLabel - the new label to use on the specified volume.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSFileDate

public java.util.Calendar getVFSFileDate(FileReference file,
                                         char dateType)
                                  throws ConduitHandlerException,
                                         NotConnectedException

Retrieves a file date for the specified file. This method can return three possible file dates: the creation date, modified date, and last accessed date. To specify which to return, use one of the VFS date constants in the DLP_Date class.

Parameters:

file - the file reference of the file to query.

dateType - the date type to return.

Returns:

a Calendar object containing the requested date data.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

See Also:

DLP_Date

setVFSFileDate

public void setVFSFileDate(FileReference file,
                           char dateType,
                           java.util.Calendar newValue)
                    throws ConduitHandlerException,
                           NotConnectedException

Sets the specified date for the specified file. This method can set three possible file dates: the creation date, modified date, and last accessed date. To specify which to set, use one of the VFS date constants in the DLP_Date class.

Parameters:

file - the file reference of the file to query.

dateType - the date type to be set.

newValue - the new value for the specified date.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

See Also:

DLP_Date

formatVFSVolume

public void formatVFSVolume(MountParameters mountParams)
                     throws ConduitHandlerException,
                            NotConnectedException

Formats the specified VFS volume.

Parameters:

mountParams - the mount parameters to use to do the formatting.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

isVFSFileAtEOF

public boolean isVFSFileAtEOF(FileReference file)
                       throws ConduitHandlerException,
                              NotConnectedException

Determines wether or not the given file reference's pointer is at the End Of File (EOF).

Parameters:

file - the file reference of the file to query.

Returns:

true if we're at the end-of-file, false otherwise.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

readVFSFile

public byte[] readVFSFile(FileReference file,
                          int numBytes)
                   throws ConduitHandlerException,
                          NotConnectedException

Reads the specified number of bytes from a VFS file.

Parameters:

file - the file reference to read from.

numBytes - the number of bytes to be read.

Returns:

an array of bytes containing the read data.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

readVFSFileToStream

public int readVFSFileToStream(FileReference file,
                               int numBytes,
                               java.io.OutputStream out)
                        throws ConduitHandlerException,
                               NotConnectedException

Reads the specified number of bytes from a VFS file, and outputs it to a stream. This method is less memory intensive than readVFSFile for large files.

Parameters:

file - the file reference to read from.

numBytes - the number of bytes to be read.

out - the OutputStream object to write the data to.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

writeVFSFile

public int writeVFSFile(FileReference file,
                        byte[] data)
                 throws ConduitHandlerException,
                        NotConnectedException

Write the specified data to a VFS file.

Parameters:

file - the file reference to write to.

data - the data to be written.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

seekVFSFile

public void seekVFSFile(FileReference file,
                        char origin,
                        int offset)
                 throws ConduitHandlerException,
                        NotConnectedException

Seeks to the specified position in the specified VFS file.

Parameters:

file - the file reference to seek in.

origin - the location to seek from.

offset - the offset to seek to (may be negative).

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

See Also:

FileReference.SEEK_ORIGIN_BEGINNING, FileReference.SEEK_ORIGIN_CURRENT_POSITION, FileReference.SEEK_ORIGIN_END

writeVFSFileFromStream

public int writeVFSFileFromStream(FileReference file,
                                  java.io.InputStream stream,
                                  int length)
                           throws ConduitHandlerException,
                                  NotConnectedException

Write the specified data stream to a VFS file.

Parameters:

file - the file reference to write to.

stream - the data stream to be written from.

length - the number of bytes to be written.

Returns:

the response from the handheld write proccess.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

enumerateDirectory

public DirectoryEntryEnumeration enumerateDirectory(FileReference file,
                                                    int iterator)
                                             throws ConduitHandlerException,
                                                    NotConnectedException

Retrieves an enumeration of the entries in the specified directory.

Parameters:

file - the file reference of the directory to enumerate.

iterator - the directory entry iterator (pass 0 to start the enumeration).

Returns:

the enumeration of the directory entries.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSVolumeInfo

public VolumeInfo getVFSVolumeInfo(VolumeReference volRef)
                            throws ConduitHandlerException,
                                   NotConnectedException

Retrieves the volume information for the specified volume.

Parameters:

volRef - the volume reference to query.

Returns:

the VolumeInfo object for this volume.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

getVFSVolumeSize

public VolumeSize getVFSVolumeSize(VolumeReference volRef)
                            throws ConduitHandlerException,
                                   NotConnectedException

Retrieves the volume size information for the specified volume.

Parameters:

volRef - the volume reference to query.

Returns:

the VolumeSize object for this volume.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

writeVFSFileFromStream

public int writeVFSFileFromStream(FileReference file,
                                  java.io.InputStream stream)
                           throws ConduitHandlerException,
                                  NotConnectedException,
                                  java.io.IOException

Write the specified data stream to a VFS file. This method will write the supplied data stream as a series of 1KB packets. This is convienent if you don't know the length of the data in the stream beforehand, however it is somewhat slower due to all of the extra protocol handler packet overhead.

Parameters:

file - the file reference to write to.

stream - the data stream to be written from.

Returns:

the response from the handheld write proccess.

Throws:

ConduitHandlerException - thrown if the underlying DLP protocol layer reports an error.

NotConnectedException - if we're not connected, or the connection is lost during processing.

java.io.IOException