Part II: System Management

60 Miscellaneous System Functions

Crc16CalcBlock

DlkControl

DlkGetSyncInfo

IntlGetRoutineAddress

IntlSetRoutineAddress

LocGetNumberSeparators

PceNativeCall

This chapter describes miscellaneous system functions. The functions in this chapter are declared in the header files Crc.h, DLServer.h, IntlMgr.h, and Localize.h.

Crc16CalcBlock Function ^TOP^

Purpose

Calculate the 16-bit CRC of a data block using the table lookup method.

Declared In

Prototype

UInt16 Crc16CalcBlock (
   const void *bufP,
   UInt16 count,
   UInt16 crc
)

Parameters

bufP

Pointer to the data buffer.

count

Number of bytes in the buffer.

crc

Seed crc value.

Returns

A 16-bit CRC for the data buffer.

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

Prototype

Err 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.

DlkCallAppReplyParamType

Prototype

typedef struct DlkCallAppReplyParamType {
   UInt16 pbSize;
   UInt32 dwResultCode;
   const void *resultP;
   UInt32 dwResultSize;
   void *dlRefP;
   UInt32 dwReserved1;
} DlkCallAppReplyParamType;

Fields

pbSize

Size of this parameter block. Set it to sizeof(DlkCallAppReplyParamType).

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.

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 60.1 and Table 60.2 list some important mappings from the CCallModuleParams class on the desktop to the SysAppLaunchCmdHandleSyncCallAppType and DlkCallAppReplyParamType structures on the handheld.

Table 60.1  CCallModuleParams to SysAppLaunchCmdHandleSyncCallAppType mapping

Table 60.2  CCallModuleParams to DlkCallAppReplyParamType mapping

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

Prototype

Err DlkGetSyncInfo (
   UInt32 *succSyncDateP,
   UInt32 *lastSyncDateP,
   DlkSyncStateType *syncStateP,
   Char *nameBufP,
   Char *logBufP,
   Int32 *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:

Prototype

typedef enum DlkSyncStateType {
  dlkSyncStateNeverSynced = 0,
  dlkSyncStateInProgress,
  dlkSyncStateLostConnection,
  dlkSyncStateLocalCan,
  dlkSyncStateRemoteCan,
  dlkSyncStateLowMemoryOnTD,
  dlkSyncStateAborted,
  dlkSyncStateCompleted,
  dlkSyncStateIncompatibleProducts,
  dlkSyncStateNPOD
} DlkSyncStateType;

Constants

dlkSyncStateNeverSynced

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.

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); 

Compatibility

The dlkSyncStateIncompatibleProducts enum value was added in Palm OS 3.0. The dlkSyncStateNPOD enum value was added in Palm OS 4.0.

IntlGetRoutineAddress Function ^TOP^

Purpose

Return the address of an international manager or text manager function.

Declared In

Prototype

void *IntlGetRoutineAddress (
   IntlSelector inSelector
)

Parameters

→ inSelector

One of the routine selectors defined in IntlMgr.h.

Returns

Returns the address of the corresponding function. Returns NULL if an invalid routine selector is passed.

Comments

Use this function for performance reasons. It returns the address of an international manager or text manager function. You can then use this address to call the function without having to go through the international manager's trap dispatch table. This function is mostly useful for optimizing the performance of text manager routines that are called in a tight loop.

You might also use this function to check for the presence of newer international manager and text manager functions. If the result is NULL, the function is not implemented on this device.

Compatibility

Implemented only if International Feature Set is present.

See Also

IntlSetRoutineAddress(), SysGetTrapAddress()

IntlSetRoutineAddress Function ^TOP^

Purpose

Set the address of the function corresponding to an international manager or text manager function.

Declared In

Prototype

Err IntlSetRoutineAddress (
   IntlSelector iSelector,
   void *iProcPtr
)

Parameters

→ iSelector

One of the routine selectors defined in IntlMgr.h.

→ iProcPtr

Pointer to a function that the routine identified by iSelector should point to.

Returns

Returns errNone if no error, or intlErrInvalidSelector if iSelector does not refer to a valid international manager or text manager routine.

Comments

This function is useful for patching an international or text manager function. Normally only a locale module would need to patch one of these functions.

Compatibility

Implemented only if 4.0 New Feature Set is present. If 5.0 New Feature Set is present this function is unimplemented.

See Also

IntlGetRoutineAddress(), SysSetTrapAddress()

LocGetNumberSeparators Function ^TOP^

Purpose

Get localized number separators.

Declared In

Prototype

void LocGetNumberSeparators (
   NumberFormatType numberFormat,
   Char *thousandSeparator,
   Char *decimalSeparator
)

Parameters

→ numberFormat

The format to use (see NumberFormatType).

← thousandSeparator

The character used for the thousands separator.

← decimalSeparator

The character used for the decimal separator.

Returns

Returns nothing.

Comments

The format to use is stored in the system preferences. You can obtain it by passing prefNumberFormat to PrefGetPreference().

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

StrLocalizeNumber(), StrDelocalizeNumber(), "Localized Applications" in the Palm OS Programmer's Companion, vol. I

PceNativeCall Function ^TOP^

Purpose

Call a native ARM or Windows NT function from code running in the PACE (68k) environment.

Declared In

Prototype

UInt32 PceNativeCall(
   NativeFuncType *nativeFuncP,
   void *userDataP
)

Parameters

→ nativeFuncP

On a handheld with an ARM processor, this is a pointer to the ARM function to be executed. On Palm OS Simulator, this is a pointer to the name of a DLL and the name of the entry point within that DLL that is to be executed, separated by a null character and terminated with a null character. See the Comments, below, for more details on the format of this argument.

↔ userDataP

Pointer to an application-specific block of data that is passed to the ARM function. This block has no specific alignment requirements; it needn't be aligned on a 16- or 32-bit boundary. Note that your ARM function may impose specific alignment requirements, however.

Returns

The return value of the specified ARM function is returned by PceNativeCall. This value is placed in both the A0 and D0 registers in the emulated 68k CPU, allowing PceNativeCall to support both pointer and immediate return value conventions.

Comments

Applications that employ PceNativeCall won't work on handhelds running a version of Palm OS prior to Palm OS Garnet. Before calling PceNativeCall, your application must verify the underlying processor type, since the calling convention is different on Palm OS Simulator. See "Calling ARM-Native Subroutines" of Palm OS Programmer's Companion, vol. I for more information and an example.

PceNativeCall byte-swaps the parameter pointer and return value as appropriate for the Dragonball-to-ARM transition. This allows you to dereference userDataP directly from your ARM code. Because the operating system has no knowledge of the structure of the parameter block, however, it performs no byte-swapping within this block. Your ARM code must do this as necessary for your application (see "Handle 68K and ARM Technical Differences" of the Palm OS Programmer's Companion, vol. I for more information).

On Palm OS Simulator, rather than passing a pointer to a block of ARM code in nativeFuncP, you instead pass a pointer to the name of a DLL and the name of the function within that DLL that is to be executed. These two names must be separated by a null character, and the entire sequence must be terminated by a null character. For example, to load the DLL found at C:\TEST_DLL\Debug\Simple.dll and call the function TestNativeCall within that DLL, you might pass a pointer to the following character string literal:

"C:\\TEST_DLL\\Debug\\Simple.dll\0TestNativeCall"

Note that if you don't supply an absolute path, Simulator looks for the DLL in (or relative to) the directory from which PalmSim.exe is running. Thus, if the DLL is located in the same directory as PalmSim.exe, you can call the above function with:

"Simple.dll\0TestNativeCall"

On release ROMs, PceNativeCall fails silently if nativeFuncP is NULL. On debug ROMs, it generates an error. All other pointers are treated as valid code and followed. If nativeFuncP is invalid, the processor will try to execute the code anyway and will eventually generate an error.

For more information on how the ARM code should be structured and how to call back and forth between the PACE and ARM environments, see "Palm OS Garnet ARM Programming" of the Palm OS Programmer's Companion, vol. I.

Compatibility

Implemented only if 5.0 New Feature Set is present.