Desktop Link Server Structures and Types
Desktop Link Server Constants
Desktop Link Server Functions and Macros
The header file DLServer.h
declares the API that this chapter describes.
Desktop Link Server Structures and Types
DlkCallAppReplyParamType Struct
Purpose
Declared In
DLServer.h
Prototype
typedef struct DlkCallAppReplyParamType { uint16_t pbSize; uint16_t padding; uint32_t dwResultCode; const void *resultP; uint32_t dwResultSize; void *dlRefP; uint32_t dwReserved1; } DlkCallAppReplyParamType
Fields
-
pbSize
- Size of this parameter block. Set it to
sizeof(DlkCallAppReplyParamType)
. -
padding
- Padding bytes.
-
dwResultCode
- Result code to be returned to the remote caller.
-
resultP
- Pointer to result data.
-
dwResultSize
- Size of result data block (number of bytes).
-
dlRefP
- Desktop Link reference pointer from
SysAppLaunchCmdHandleSyncCallAppType
. -
dwReserved1
- Reserved. Set to
NULL
.
DlkCtlEnum Typedef
Purpose
Declared In
DLServer.h
Prototype
typedef Enum8 DlkCtlEnum
Desktop Link Server Constants
Purpose
Declared In
DLServer.h
Constants
-
#define dlkErrIncompatibleProducts (dlkErrorClass | 8)
-
#define dlkErrInterrupted (dlkErrorClass | 6)
-
#define dlkErrLostConnection (dlkErrorClass | 5)
-
#define dlkErrMemory (dlkErrorClass | 2)
-
#define dlkErrNoSession (dlkErrorClass | 3)
-
#define dlkErrNPOD (dlkErrorClass | 9)
-
#define dlkErrParam (dlkErrorClass | 1)
-
#define dlkErrSizeErr (dlkErrorClass | 4)
-
#define dlkErrUserCan (dlkErrorClass | 7)
Miscellaneous Desktop Link Server Constants
Purpose
Declared In
DLServer.h
DlkCtlEnumTag Enum
Purpose
Declared In
DLServer.h
Constants
-
dlkCtlFirst = 0
-
dlkCtlGetPCHostName
-
dlkCtlSetPCHostName
-
dlkCtlGetCondFilterTable
-
dlkCtlSetCondFilterTable
-
dlkCtlGetLANSync
-
dlkCtlSetLANSync
-
dlkCtlGetHSTCPPort
-
dlkCtlSetHSTCPPort
-
dlkCtlSendCallAppReply
-
dlkCtlGetPCHostAddr
-
dlkCtlSetPCHostAddr
-
dlkCtlGetPCHostMask
-
dlkCtlSetPCHostMask
-
dlkCtlGetPostSyncErr
-
dlkCtlSetPostSyncErr
-
dlkCtlLAST
DlkSyncStateType Enum
Purpose
State information returned by DlkGetSyncInfo
.
Declared In
DLServer.h
Constants
-
dlkSyncStateNeverSynced = 0
- The handheld has never been synced.
-
dlkSyncStateInProgress
- A sync is currently in progress.
-
dlkSyncStateLostConnection
- The connection was lost during sync.
-
dlkSyncStateLocalCan
- Sync was cancelled by the user on the handheld.
-
dlkSyncStateRemoteCan
- Sync was cancelled by the user from the desktop.
-
dlkSyncStateLowMemoryOnTD
- Sync ended due to a low memory condition on the handheld.
-
dlkSyncStateAborted
- Sync was aborted for some other reason.
-
dlkSyncStateCompleted
- Sync completed normally.
-
dlkSyncStateIncompatibleProducts
- Sync ended because the desktop HotSync product is incompatible with this version of the handheld HotSync.
-
dlkSyncStateNPOD
- The sync could not take place because the handheld has a 4.0-style password but the desktop hasn't yet been updated to a compatible version.
Desktop Link Server Functions and Macros
DlkControl Function
Purpose
Perform an operation at the behest of the desktop software. Among other things, this function is used to return values to the conduit during the handling of sysAppLaunchCmdHandleSyncCallApp
.
Declared In
DLServer.h
Prototype
status_t DlkControl ( DlkCtlEnumop
, void*param1P
, void*param2P
)
Parameters
-
→ op
- Desktop Link control code. Use
dlkCtlSendCallAppReply
when sending a result back to the conduit while handling asysAppLaunchCmdHandleSyncCallApp
launch code. -
↔ param1P
- Pointer to the first parameter (operation-specific). For
dlkCtlSendCallAppReply
, this parameter should point to aDlkCallAppReplyParamType
structure. -
↔ param2P
- Pointer to the second parameter (operation-specific). For
dlkCtlSendCallAppReply
, this parameter should be set toNULL
.
Returns
errNone
if no error, or an error code if there was a problem during the call to DlkControl
. In either case, place the value returned from DlkControl
into the replyErr
field of the SysAppLaunchCmdHandleSyncCallAppType structure when handling sysAppLaunchCmdHandleSyncCallApp.
Comments
This function is needed to return data back to a conduit during the handling of sysAppLaunchCmdHandleSyncCallApp
. Set param1P
to point to a DlkCallAppReplyParamType
structure, as described below. See the Example for an illustration of how to handle sysAppLaunchCmdHandleSyncCallApp
.
Example
The SysAppLaunchCmdHandleSyncCallAppType
structure that accompanies the sysAppLaunchCmdHandleSyncCallApp
launch code contains all of the information passed into SyncCallRemoteModule
on the desktop as well as the necessary fields to pass the result pack to the desktop. At the end of your sysAppLaunchCmdHandleSyncCallApp
launch code handler, you'll need to send a DlkCallAppReplyParamType
reply structure back to the device using DlkControl
.
#include <DLServer.h> ... case sysAppLaunchCmdHandleSyncCallApp: { SysAppLaunchCmdHandleSyncCallAppType *theCommandPtr; DlkCallAppReplyParamType theReplyParams; CharPtr theReplyBuffer = "SUCCESS"; // Cast the cmdPBP to a SysAppLaunchCmdHandleSyncCallAppType // pointer so that we can work with it. theCommandPtr = (SysAppLaunchCmdHandleSyncCallAppType*)cmdPBP; // Do whatever work is necessary here. If you set the m_wActionCode // field in your CCallModuleParams class on the desktop, then you // can handle that code by looking at the action field of theCommandPtr // (i.e.) if (theCommandPtr->action == 1) // Create the reply to send back to the desktop // First clear out all the fields. This is necessary so that the reserved // fields are set to NULL. MemSet( &theReplyParams, sizeof(DlkCallAppReplyParamType), 0 ); // Set the size of the reply. This is required. theReplyParams.pbSize = sizeof(DlkCallAppReplyParamType); // Set the result code. Normally this will be set to zero unless you want // to send an error code back to the desktop. theReplyParams.dwResultCode = 0; // Fill in the reply buffer and buffer length theReplyParams.resultP = theReplyBuffer; theReplyParams.dwResultSize = StrLen(theReplyBuffer) + 1; // Fill in the DL reference pointer. This is required. theReplyParams.dlRefP = theCommandPtr->dlRefP; // Set the handled field to true. This is required to let the desktop // know that the sysAppLaunchCmdHandleSyncCallApp was handled. If you // don't set this to true, the call to SyncCallRemoteModule will return // SYNCERR_UNKNOWN_REQUEST. theCommandPtr->handled = true; // Finally, set the replyErr field by passing the reply parameters to // DlkControl. This is required for the DLServer to properly handle the // reply request. theCommandPtr->replyErr = DlkControl (dlkCtlSendCallAppReply, &theReplyParams, NULL); break; }
Table 22.1 and Table 22.2 list some important mappings from the CCallModuleParams
class on the desktop to the SysAppLaunchCmdHandleSyncCallAppType
and DlkCallAppReplyParamType
structures on the handheld.
Table 22.1 CCallModuleParams to SysAppLaunchCmdHandleSyncCallAppType mapping
Table 22.2 CCallModuleParams to DlkCallAppReplyParamType mapping
DlkGetSyncInfo Function
Purpose
Get the sync info managed by Desktop Link. This function is often used to obtain the user name on the handheld.
Declared In
DLServer.h
Prototype
status_t DlkGetSyncInfo ( uint32_t*succSyncDateP
, uint32_t*lastSyncDateP
, DlkSyncStateType*syncStateP
, char*nameBufP
, char*logBufP
, int32_t*logLenP
)
Parameters
-
← succSyncDateP
- Pointer to the location where the date of the last successful sync is stored. Supply
NULL
for this parameter if this date isn't needed. -
← lastSyncDateP
- Pointer to the location where the date of the last sync, successful or otherwise, is stored. Supply
NULL
for this parameter if this date isn't needed. -
← syncStateP
- Pointer to a
DlkSyncStateType
enum into which the state of the last sync is stored. SupplyNULL
for this parameter if the state information isn't needed. See the Comments, below, for a description of this enum. -
← nameBufP
- Pointer to a string buffer into which the null-terminated handheld user name is stored. This string buffer must have been preallocated to be at least
dlkUserNameBufSize
bytes in length. SupplyNULL
for this parameter if the user name isn't needed. -
← logBufP
- Pointer to a string buffer into which the sync log text, null-terminated, is stored. Supply
NULL
for this parameter if the log text isn't needed. If you supply a valid pointer for this parameter, you must specify the preallocated buffer length using thelogLenP
parameter; the returned log text will be truncated, if necessary, to fit within the buffer. -
↔ logLenP
- Pointer to the log buffer size. If
logBufP
is notNULL
, on entry you must set this value to the size of thelogBufP
buffer. When this function returns, this value indicates the actual length of the log text, not counting the null terminator.
Returns
Returns errNone
if no error, or dlkErrMemory
if the Desktop Link preferences resource couldn't be locked.
Comments
The state information returned through syncStateP
has one of the values defined by the DlkSyncStateType
enum.
Example
This function is most often used to obtain the handheld user name. The following code excerpt shows how to do this (for clarity, error-checking has been omitted):
MemHandle nameH; char *nameP; // Allocate a buffer for the user name nameH = MemHandleNew(dlkUserNameBufSize); nameP = MemHandleLock(nameH); // Obtain the user's name DlkGetSyncInfo(NULL, NULL, NULL, nameP, NULL, NULL); // ... Do something with the user name here ... // Now that we're done with the user name, free the buffer MemPtrUnlock(nameP);
DlkSetLogEntry Function
Purpose
Declared In
DLServer.h
Prototype
void DlkSetLogEntry ( const char*textP
, int16_ttextLen
, Booleanappend
)