Miscellaneous System Functions
 

 < Home   < Developers   < Development Support   < Documentation

56 Miscellaneous System Functions


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

56 Miscellaneous System Functions

Crc16CalcBlock

DlkGetSyncInfo

IntlGetRoutineAddress

IntlSetRoutineAddress

LocGetNumberSeparators

       

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

Purpose

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

Prototype

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

Parameters

bufPPointer to the data buffer.
countNumber of bytes in the buffer.
crcSeed crc value.

Result

A 16-bit CRC for the data buffer.

DlkGetSyncInfo

Purpose

Get the sync info managed by Desktop Link. This function is often used to obtain the user name on the handheld.

Prototype

Err DlkGetSyncInfo (UInt32 *succSyncDateP, UInt32 *lastSyncDateP, DlkSyncStateType *syncStateP, Char *nameBufP, Char *logBufP, Int32 *logLenP)

Parameters

<- succSyncDatePPointer to the location where the date of the last successful sync is stored. Supply NULL for this parameter if this date isn't needed.
<- lastSyncDatePPointer 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.
<- syncStatePPointer 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.
<- nameBufPPointer 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.
<- logBufPPointer 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.
<-> logLenPPointer 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.

Result

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:

typedef enum DlkSyncStateType { 
  dlkSyncStateNeverSynced = 0, 
  dlkSyncStateInProgress, 
  dlkSyncStateLostConnection, 
  dlkSyncStateLocalCan, 
  dlkSyncStateRemoteCan, 
  dlkSyncStateLowMemoryOnTD, 
  dlkSyncStateAborted, 
  dlkSyncStateCompleted, 
  dlkSyncStateIncompatibleProducts, 
  dlkSyncStateNPOD 
} DlkSyncStateType; 
  
Value
Description
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

Purpose

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

Prototype

void *IntlGetRoutineAddress (IntlSelector inSelector)

Parameters

-> inSelectorOne of the routine selectors defined in IntlMgr.h.

Result

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

New IntlSetRoutineAddress

Purpose

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

Prototype

Err IntlSetRoutineAddress (IntlSelector iSelector, void *iProcPtr)

Parameters

-> iSelectorOne of the routine selectors defined in IntlMgr.h.
-> iProcPtrPointer to a function that the routine identified by iSelector should point to.

Result

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.

See Also

IntlGetRoutineAddress, SysSetTrapAddress

LocGetNumberSeparators

Purpose

Get localized number separators.

Prototype

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

Parameters

-> numberFormatThe format to use (see NumberFormatType).
<- thousandSeparatorThe character used for the thousands separator.
<- decimalSeparatorThe character used for the decimal separator.

Result

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