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

60    Miscellaneous System Functions

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

Crc.h

Prototype

UInt16 Crc16CalcBlock (
   constvoid*bufP,
   UInt16count,
   UInt16crc
)

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

DLServer.h

Prototype

Err DlkControl (
   DlkCtlEnumop,
   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

CCallModuleParams

SysAppLaunchCmdHandleSyncCallAppType

m_wActionCode

action

m_dwParamSize

dwParamSize

m_pParam

paramP

Table 60.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

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

IntlMgr.h

Prototype

void *IntlGetRoutineAddress (
   IntlSelectorinSelector
)

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

IntlMgr.h

Prototype

Err IntlSetRoutineAddress (
   IntlSelectoriSelector,
   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.


WARNING! If your application patches an international manager function using this function, you must remove the patch before your application exits. Do not use this mechanism to permanently patch international manager functions as it may cause unpredictable results for the system and other applications.

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

Localize.h

Prototype

void LocGetNumberSeparators (
   NumberFormatTypenumberFormat,
   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

PceNativeCall.h

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.


NOTE: The call to your native function is guaranteed to be made from ARM mode.

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 "PalmOS Garnet ARM Programming" of the Palm OS Programmer's Companion, vol. I.

Compatibility

Implemented only if 5.0 New Feature Set is present.