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
bufP | Pointer to the data buffer. |
count | Number of bytes in the buffer. |
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
<- 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. |
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
-> inSelector | One 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
-> iSelector | One of the routine selectors defined in IntlMgr.h. |
-> iProcPtr | Pointer 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
<- thousandSeparator | The character used for the thousands separator. |
<- decimalSeparator | The 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
|