/****************************************************************************** * * Copyright (c) 1995-2000 Palm, Inc. or its subsidiaries. * All rights reserved. * * File: DLServer.h * * Release: Palm OS SDK 4.0 (63220) * * Description: * Desktop Link Protocol(DLP) Server implementation definitions. * * History: * vmk 7/12/95 Created by Vitaly Marty Kruglikov * vmk 7/12/96 Converted to HTAL architecture * jmp 12/23/99 Fix <> vs. "" problem. * *****************************************************************************/ #ifndef __DL_SERVER_H__ #define __DL_SERVER_H__ // Pilot common definitions #include #include // for DmOpenRef #include /************************************************************ * DLK result codes * (dlkErrorClass is defined in SystemMgr.h) *************************************************************/ #pragma mark *Error Codes* #define dlkErrParam (dlkErrorClass | 1) // invalid parameter #define dlkErrMemory (dlkErrorClass | 2) // memory allocation error #define dlkErrNoSession (dlkErrorClass | 3) // could not establish a session #define dlkErrSizeErr (dlkErrorClass | 4) // reply length was too big #define dlkErrLostConnection (dlkErrorClass | 5) // lost connection #define dlkErrInterrupted (dlkErrorClass | 6) // sync was interrupted (see sync state) #define dlkErrUserCan (dlkErrorClass | 7) // cancelled by user #define dlkErrIncompatibleProducts (dlkErrorClass | 8) // incompatible desktop version #define dlkErrNPOD (dlkErrorClass | 9) // New Password, Old Desktop /******************************************************************** * Desktop Link system preferences resource for user info * id = sysResIDDlkUserInfo, defined in SystemResources.h ********************************************************************/ #pragma mark *User Info Preference* #define dlkMaxUserNameLength 40 #define dlkUserNameBufSize (dlkMaxUserNameLength + 1) #if ERROR_CHECK_LEVEL == ERROR_CHECK_FULL #define dlkMaxLogSize (20 * 1024) #else #define dlkMaxLogSize (2 * 1024) #endif typedef enum DlkSyncStateType { dlkSyncStateNeverSynced = 0, // never synced dlkSyncStateInProgress, // sync is in progress dlkSyncStateLostConnection, // connection lost during sync dlkSyncStateLocalCan, // cancelled by local user on handheld dlkSyncStateRemoteCan, // cancelled by user from desktop dlkSyncStateLowMemoryOnTD, // sync ended due to low memory on handheld dlkSyncStateAborted, // sync was aborted for some other reason dlkSyncStateCompleted, // sync completed normally // Added in PalmOS v3.0: dlkSyncStateIncompatibleProducts, // sync ended because desktop HotSync product // is incompatible with this version // of the handheld HotSync dlkSyncStateNPOD // New Password, Old Desktop } DlkSyncStateType; #define dlkUserInfoPrefVersion 0x0102 // current user info pref version: 1.2 typedef struct DlkUserInfoHdrType { UInt16 version; // pref version number UInt32 userID; // user id UInt32 viewerID; // id assigned to viewer by the desktop UInt32 lastSyncPC; // last sync PC id UInt32 succSyncDate; // last successful sync date UInt32 lastSyncDate; // last sync date DlkSyncStateType lastSyncState; // last sync status UInt8 reserved1; // Explicitly account for 16-bit alignment padding UInt16 lanSyncEnabled;// if non-zero, LAN Sync is enabled UInt32 hsTcpPortNum; // TCP/IP port number of Desktop HotSync UInt32 dwReserved1; // RESERVED -- set to NULL! UInt32 dwReserved2; // RESERVED -- set to NULL! UInt8 userNameLen; // length of name field(including null) UInt8 reserved2; // Explicitly account for 16-bit alignment padding UInt16 syncLogLen; // length of sync log(including null) } DlkUserInfoHdrType; typedef struct DlkUserInfoType { DlkUserInfoHdrType header; // fixed size header Char nameAndLog[2]; // user name, followed by sync log; // both null-terminated(for debugging) } DlkUserInfoType; typedef DlkUserInfoType* DlkUserInfoPtr; // user info pointer /******************************************************************** * Desktop Link system preferences resource for the Conduit Filter Table * id = sysResIDDlkCondFilterTab, defined in SystemResources.h ********************************************************************/ #pragma mark *Conduit Filter Preference* // // Table for specifying conduits to "filter out" during HotSync // // This table consists of DlkCondFilterTableHdrType header followed by a // variable number of DlkCondFilterEntryType entries typedef struct DlkCondFilterTableHdrType { UInt16 entryCount; } DlkCondFilterTableHdrType; typedef DlkCondFilterTableHdrType* DlkCondFilterTableHdrPtr; typedef struct DlkCondFilterEntryType { UInt32 creator; UInt32 type; } DlkCondFilterEntryType; typedef DlkCondFilterEntryType* DlkCondFilterEntryPtr; typedef struct DlkCondFilterTableType { DlkCondFilterTableHdrType hdr; // table header DlkCondFilterEntryType entry[1]; // variable number of entries } DlkCondFilterTableType; typedef DlkCondFilterTableType* DlkCondFilterTablePtr; /******************************************************************** * DLK Session Structures ********************************************************************/ #pragma mark *Session Structures* // DesktopLink event notification callback. If non-zero is returned, // sync will be cancelled as soon as a safe point is reached. typedef enum { dlkEventOpeningConduit = 1, // conduit is being opened -- paramP // is null; dlkEventDatabaseOpened, // client has opened a database -- paramP // points to DlkEventDatabaseOpenedType; dlkEventCleaningUp, // last stage of sync -- cleaning up (notifying apps, etc) -- // paramP is null dlkEventSystemResetRequested // system reset was requested by the desktop client // (the normal action is to delay the reset until // end of sync) -- paramP is null } DlkEventType; // Prototype for the event notification callback typedef Int16 (*DlkEventProcPtr)(UInt32 eventRef, DlkEventType dlkEvent, void * paramP); // Parameter structure for dlkEventDatabaseOpened // Added new fields for Pilot v2.0 vmk 12/24/96 typedef struct DlkEventDatabaseOpenedType { DmOpenRef dbR; // open database ref (v2.0) Char * dbNameP; // database name UInt32 dbType; // databse type (v2.0) UInt32 dbCreator; // database creator } DlkEventDatabaseOpenedType; // Prototype for the "user cancel" check callback function typedef Int16 (*DlkUserCanProcPtr)(UInt32 canRef); // // List of modified database creators maintained by DLP Server // typedef struct DlkDBCreatorList { UInt16 count; // number of entries in the list MemHandle listH; // chunk handle of the creators list } DlkDBCreatorList; // // Desktop Link Server state flags // #define dlkStateFlagVerExchanged 0x8000 #define dlkStateFlagSyncDateSet 0x4000 // // DLP Server session information // typedef struct DlkServerSessionType { UInt16 htalLibRefNum; // HTAL library reference number - the library has a live connection UInt32 maxHtalXferSize; // Maximum transfer block size // Information supplied by user DlkEventProcPtr eventProcP; // ptr to DesktopLink event notification proc UInt32 eventRef; // user reference value for event proc DlkUserCanProcPtr canProcP; // ptr to user-cancel function UInt32 canRef; // parameter for canProcP() MemHandle condFilterH; // handle of conduit filter table(DlkCondFilterTableHdrPtr) or 0 for none // Current database information UInt8 dlkDBID; // Desktop Link database handle of the open database UInt8 reserved1; DmOpenRef dbR; // TouchDown database access pointer -- if null, no current db UInt16 cardNo; // memory module number UInt32 dbCreator; // creator id Char dbName[dmDBNameLength]; // DB name UInt16 dbOpenMode; // database open mode Boolean created; // true if the current db was created Boolean isResDB; // set to true if resource database Boolean ramBased; // true if the db is in RAM storage Boolean readOnly; // true if the db is read-only LocalID dbLocalID; // TouchDown LocalID of the database UInt32 initialModNum; // initial DB modification number UInt32 curRecIndex; // current record index for enumeration functions // (0=beginning) // List of modified database creators maintained by DLP Server DlkDBCreatorList creatorList; // Session status information DlkSyncStateType syncState; // current sync state; Boolean complete; // set to true when completion request // has been received Boolean conduitOpened; // set to true after the first coduit // is opened by remote Boolean logCleared; // set to true after sync log has been // cleared during the current session; // The log will be cleared before any new entries are added or at // the end of sync in case no new entries were added. // (we do not clear the log at the beginning of sync in case the // user cancels during the "identifying user" phase; in this // event, the spec calls for preserving the original log) Boolean resetPending; // set to true if system reset is pending; // the reset will be carried out at end // of sync // Current request information Boolean gotCommand; // set to true when got a request UInt8 cmdTID; // current transaction ID UInt8 reserved2; UInt16 cmdLen; // size of data in request buffer void * cmdP; // pointer to command MemHandle cmdH; // handle of command buffer // Fields added in PalmOS v3.0 UInt16 wStateFlags; // bitfield of dlkStateFlag... bits DmSearchStateType dbSearchState; // database search state for iterative // searches using DmGetNextDatabaseByTypeCreator // Fields added in PalmOS v4.0 MemHandle openFileRefsH; // Table of open file refs Int16 numOpenFileRefs; // Current size of the file ref table. Boolean pre40Desktop; // are we using a pre-4.0 desktop (DLP v1.2) Boolean passwordSet; // is a password set? } DlkServerSessionType; typedef DlkServerSessionType* DlkServerSessionPtr; /******************************************************************** * DLK Function Parameter Structures ********************************************************************/ #pragma mark *Function Parameter Structures* // // Parameter passed to DlkControl() // typedef enum DlkCtlEnum { dlkCtlFirst = 0, // reserve 0 // // Pilot v2.0 control codes: // dlkCtlGetPCHostName, // param1P = ptr to text buffer; (can be null if *(UInt16 *)param2P is 0) // param2P = ptr to buffer size(UInt16); // returns actual length, including null, in *(UInt16 *)param2P which may be bigger than # of bytes copied. dlkCtlSetPCHostName, // param1P = ptr to host name(zero-terminated) or NULL if *param2 is 0 // param2P = ptr to length(UInt16), including NULL (if length is 0, the current name is deleted) dlkCtlGetCondFilterTable, // param1P = ptr to destination buffer for filter table, or NULL if *param2 is 0 // param2P = on entry, ptr to size of buffer(UInt16) (the size may be 0) // on return, size, in bytes, of the actual filter table dlkCtlSetCondFilterTable, // param1P = ptr to to conduit filter table, or NULL if *param2 is 0 // param2P = ptr to size of filter table(UInt16) (if size is 0, the current table will be deleted) dlkCtlGetLANSync, // param1P = ptr to store for the LANSync setting(UInt16): 0 = off, otherwise on // param2P = not used, set to NULL dlkCtlSetLANSync, // param1P = ptr to the LANSync setting(UInt16): 0 = off, otherwise on // param2P = not used, set to NULL dlkCtlGetHSTCPPort, // param1P = ptr to store for the Desktop HotSync TCP/IP port number(UInt32) -- zero if not set // param2P = not used, set to NULL dlkCtlSetHSTCPPort, // param1P = ptr to the Desktop HotSync TCP/IP port number(UInt32) // param2P = not used, set to NULL dlkCtlSendCallAppReply, // param1P = ptr to DlkCallAppReplyParamType structure // param2P = not used, set to NULL // // RETURNS: send error code; use this error code // as return value from the action code handler dlkCtlGetPCHostAddr, // param1P = ptr to text buffer; (can be null if *(UInt16 *)param2P is 0) // param2P = ptr to buffer size(UInt16); // returns actual length, including null, in *(UInt16 *)param2P which may be bigger than # of bytes copied. dlkCtlSetPCHostAddr, // param1P = ptr to host address string(zero-terminated) or NULL if *param2 is 0 // param2P = ptr to length(UInt16), including NULL (if length is 0, the current name is deleted) dlkCtlGetPCHostMask, // param1P = ptr to text buffer; (can be null if *(UInt16 *)param2P is 0) // param2P = ptr to buffer size(UInt16); // returns actual length, including null, in *(UInt16 *)param2P which may be bigger than # of bytes copied. dlkCtlSetPCHostMask, // param1P = ptr to subnet mask string(zero-terminated) or NULL if *param2 is 0 // param2P = ptr to length(UInt16), including NULL (if length is 0, the current name is deleted) dlkCtlLAST // *KEEP THIS ENTRY LAST* } DlkCtlEnum; // // Parameter passed to DlkStartServer() // typedef struct DlkServerParamType { UInt16 htalLibRefNum; // HTAL library reference number - the library has a live connection DlkEventProcPtr eventProcP; // ptr to DesktopLink event notification proc UInt32 eventRef; // user reference value for event proc UInt32 reserved1; // reserved - set to NULL UInt32 reserved2; // reserved - set to NULL MemHandle condFilterH; // handle of conduit filter table(DlkCondFilterTableHdrPtr) or 0 for none } DlkServerParamType; typedef DlkServerParamType* DlkServerParamPtr; // // Parameter passed with DlkControl()'s dlkCtlSendCallAppReply code // typedef struct DlkCallAppReplyParamType { UInt16 pbSize; // size of this parameter block (set to sizeof(DlkCallAppReplyParamType)) UInt32 dwResultCode; // result code to be returned to remote caller const void * resultP; // ptr to result data UInt32 dwResultSize; // size of reply data in number of bytes void * dlRefP; // DesktopLink reference pointer from // SysAppLaunchCmdHandleSyncCallAppType UInt32 dwReserved1; // RESERVED -- set to null!!! } DlkCallAppReplyParamType; /******************************************************************** * DesktopLink Server Routines ********************************************************************/ #pragma mark *Function Prototypes* #ifdef __cplusplus extern "C" { #endif // // SERVER API // // * RETURNED: 0 if session ended successfully; otherwise: dlkErrParam, // * dlkErrNoSession, dlkErrLostConnection, dlkErrMemory, // * dlkErrUserCan extern Err DlkStartServer(DlkServerParamPtr paramP) SYS_TRAP(sysTrapDlkStartServer); extern Err DlkGetSyncInfo(UInt32 * succSyncDateP, UInt32 * lastSyncDateP, DlkSyncStateType* syncStateP, Char * nameBufP, Char * logBufP, Int32 * logLenP) SYS_TRAP(sysTrapDlkGetSyncInfo); extern void DlkSetLogEntry(const Char * textP, Int16 textLen, Boolean append) SYS_TRAP(sysTrapDlkSetLogEntry); // Dispatch a DesktopLink request (exposed for patching) extern Err DlkDispatchRequest(DlkServerSessionPtr sessP) SYS_TRAP(sysTrapDlkDispatchRequest); extern Err DlkControl(DlkCtlEnum op, void * param1P, void * param2P) SYS_TRAP(sysTrapDlkControl); #ifdef __cplusplus } #endif /******************************************************************** * DLK Macros ********************************************************************/ #endif // __DL_SERVER_H__