Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

22    Desktop Link Server

System Management

Exploring Palm OS®

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 ^TOP^

DlkCallAppReplyParamType Struct ^TOP^

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 ^TOP^

Purpose

Declared In

DLServer.h

Prototype

typedef Enum8 DlkCtlEnum

Desktop Link Server Constants ^TOP^

^TOP^

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 ^TOP^

Purpose

Declared In

DLServer.h
#define dlkMaxUserNameLength (40)
#define dlkUserNameBufSize (dlkMaxUserNameLength + 1)

DlkCtlEnumTag Enum ^TOP^

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 ^TOP^

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 ^TOP^

DlkControl Function ^TOP^

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 (
   DlkCtlEnum op,
   void *param1P,
   void *param2P
)

Parameters

op
Desktop Link control code. Use dlkCtlSendCallAppReply when sending a result back to the conduit while handling a sysAppLaunchCmdHandleSyncCallApp launch code.
param1P
Pointer to the first parameter (operation-specific). For dlkCtlSendCallAppReply, this parameter should point to a DlkCallAppReplyParamType structure.
param2P
Pointer to the second parameter (operation-specific). For dlkCtlSendCallAppReply, this parameter should be set to NULL.

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

CCallModuleParams

SysAppLaunchCmdHandleSyncCallAppType

m_wActionCode

action

m_dwParamSize

dwParamSize

m_pParam

paramP

Table 22.2  CCallModuleParams to DlkCallAppReplyParamType mapping

CCallModuleParams

DlkCallAppReplyParamType

m_dwResultBufSize

dwResultSize

m_pResultBuf

resultP

m_dwResultCode

dwResultCode

DlkGetSyncInfo Function ^TOP^

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. Supply NULL 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. Supply NULL 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 the logLenP 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 not NULL, on entry you must set this value to the size of the logBufP 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 ^TOP^

Purpose

Declared In

DLServer.h

Prototype

void DlkSetLogEntry (
   const char *textP,
   int16_t textLen,
   Boolean append
)

Parameters

textP
textLen
append

Returns