46 System Manager

This chapter provides reference material for the system manager. The system manager API is declared in the header files SystemMgr.h and SysUtils.h.

For more information on the system manager, see the chapters "Application Startup and Stop" and "Palm System Features" in the Palm OS Programmer's Companion.

System Functions

SysAppLaunch

Purpose

Open an application from a specified database and card, with the appropriate launch flags. Generally used to launch an application as a subroutine of the caller.

Prototype

Err SysAppLaunch (UInt16 cardNo, LocalID dbID, UInt16 launchFlags, UInt16 cmd, MemPtr cmdPBP, UInt32* resultP)

Parameters

cardNo, dbID

cardNo and dbID identify the application.

launchFlags

Set to 0.

cmd

Launch code.

cmdPBP

Launch code parameter block.

resultP

Pointer to what's returned by the application's PilotMain routine.

Result

Returns 0 if no error, or one of sysErrParamErr, memErrNotEnoughSpace, sysErrOutOfOwnerIDs.

Comments

Launching an application with all launch bits cleared makes the application a subroutine call from the point of view of the caller.

Do not use this function to open the system-supplied Application Launcher application. If another application has replaced the default launcher with one of its own, this function will open the custom launcher instead of the system-supplied one. To open the system-supplied launcher reliably, enqueue a keyDownEvent that contains a launchChr, as shown in the section "Application Launcher" of the user interface chapter in the Palm OS Programmer's Companion.

If the launch flag sysAppLaunchFlagNewThread is set, and you are passing a parameter block (the cmdPBP parameter), you must set the owner of the parameter block chunk to the operating system. To do this, and for more information, see MemPtrSetOwner. If the parameter block structure contains references by pointer or handle to any other chunks, you also must set the owner of those chunks by using MemHandleSetOwner or MemPtrSetOwner.

---

NOTE:  

For important information regarding the correct use of this function, see the "Application Startup and Stop" chapter in the Palm OS Programmer's Companion.

---

See Also

SysBroadcastActionCode, SysUIAppSwitch, SysCurAppDatabase

SysBatteryInfo

Purpose

Retrieve settings for the batteries. Set set to false to retrieve battery settings. (Applications should not change any of the settings).

Use this function only to retrieve settings!

Prototype

UInt16 SysBatteryInfo (Boolean set, UInt16* warnThresholdP, UInt16* criticalThresholdP, UInt16* maxTicksP, SysBatteryKind* kindP, Boolean* pluggedIn UInt8* percentP)

Parameters

set

If false, parameters with non-NULL pointers are retrieved. Never set this parameter to true.

warnThresholdP

Pointer to battery voltage warning threshold in volts*100, or NULL.

criticalThresholdP

Pointer to the battery voltage critical threshold in volts*100, or NULL.

maxTicksP

Pointer to the battery timeout, or NULL.

kindP

Pointer to the battery kind, or NULL.

pluggedIn

Pointer to pluggedIn return value, or NULL.

percentP

Percentage of power remaining in the battery.

Result

Returns the current battery voltage in volts*100.

Comments

Call this function to make sure an upcoming activity won't be interrupted by a low battery warning.

warnThresholdP and maxTicksP are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr key event is put on the queue. Normally, applications call SysHandleEvent which calls SysBatteryDialog in response to this event.

criticalThresholdP is the battery voltage threshold. If battery voltage falls below this level, the system turns itself off without warning and doesn't turn on until battery voltage is above it again.

Compatibility

This function was revised for Palm OS^® 3.0. In Palm OS 3.0, the percentP parameter was added. This enhancement is implemented only if 3.0 New Feature Set is present.

See Also

SysBatteryInfoV20

SysBatteryInfoV20

Purpose

Retrieve settings for the batteries. Set to false to retrieve battery settings. (Applications should not change any of the settings).

Use this function only to retrieve settings!

Prototype

UInt16 SysBatteryInfoV20 (Boolean set, UInt16* warnThresholdP, UInt16* criticalThresholdP, UInt16* maxTicksP, SysBatteryKind* kindP, Boolean* pluggedIn)

Parameters

set

If false, parameters with non-NULL pointers are retrieved. Never set this parameter to true.

warnThresholdP

Pointer to battery voltage warning threshold in volts*100, or NULL.

criticalThresholdP

Pointer to the battery voltage critical threshold in volts*100, or NULL.

maxTicksP

Pointer to the battery timeout, or NULL.

kindP

Pointer to the battery kind, or NULL.

pluggedIn

Pointer to pluggedIn return value, or NULL.

Result

Returns the current battery voltage in volts*100.

Comments

Call this function to make sure an upcoming activity won't be interrupted by a low battery warning.

warnThresholdP and maxTicksP are the battery-warning voltage threshold and time out. If the battery voltage falls below the threshold, or the timeout expires, a lowBatteryChr key event is put on the queue. Normally, applications call SysHandleEvent which calls SysBatteryDialog in response to this event.

criticalThresholdP is the battery voltage threshold. If battery voltage falls below this level, the system turns itself off without warning and doesn't turn on until battery voltage is above it again.

Compatibility

This function corresponds to the Palm OS 2.0 version of SysBatteryInfo. Implemented only if 3.0 New Feature Set is present.

See Also

SysBatteryInfo

SysBinarySearch

Purpose

Search elements in a sorted array for the specified data according to the specified comparison function.

Prototype

Boolean SysBinarySearch (void const *baseP, const UInt16 numOfElements, const Int16 width, SearchFuncPtr searchF, void const *searchData, const Int32 other, Int32* position, const Boolean findFirst)

Parameters

baseP

Base pointer to an array of elements

numOfElements

Number of elements to search, starting at 0 to numOfElements -1. Must be greater than 0.

width

Width of an element comparison function.

searchF

Search function.

searchData

Data to search for. This data is passed to the searchF function.

other

Data to be passed as the third parameter (the other parameter) to the comparison function.

position

Pointer to the position result.

findFirst

If set to true, the first matching element is returned. Use this parameter if the array contains duplicate entries to ensure that the first such entry will be the one returned.

Result

Returns true if an exact match was found. In this case, position points to the element number where the data was found.

Returns false if an exact match was not found. If false is returned, position points to the element number where the data should be inserted if it was to be added to the array in sorted order.

Comments

The array must be sorted in ascending order prior to the search. Use SysInsertionSort or SysQSort to sort the array.

The search starts at element 0 and ends at element (numOfElements - 1).

The search function's (searchF) prototype is:

Int16 _searchF (void const *searchData, void const *arrayData, Int32 other);

The first parameter is the data for which to search, the second parameter is a pointer to an element in the array, and the third parameter is any other necessary data.

The function returns:

• > 0 if the search data is greater than the element
  
  
• < 0 if the search data is less than the element
  
  
• 0 if the search data is the same as the element
  

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysBroadcastActionCode

Purpose

Send the specified action code (launch code) and parameter block to the latest version of every UI application.

Prototype

Err SysBroadcastActionCode (UInt16 cmd, MemPtr cmdPBP)

Parameters

cmd

Action code to send.

cmdPBP

Action code parameter block to send.

Result

Returns 0 if no error, or one of the following errors: sysErrParamErr, memErrNotEnoughSpace, sysErrOutOfOwnerIDs.

See Also

SysAppLaunch, Chapter 3, "Application Startup and Stop." of the Palm OS Programmer's Companion

SysCopyStringResource

Purpose

Copy a resource string to a passed string.

Prototype

void SysCopyStringResource (Char* string, Int16 theID)

Parameters

string

String to copy the resource string to.

theID

Resource string ID.

Result

Stores a copy of the resource string in string.

SysCreateDataBaseList

Purpose

Generate a list of databases found on the memory cards matching a specific type and return the result. If lookupName is true then a name in a tAIN resource is used instead of the database's name and the list is sorted. Only the last version of a database is returned. Databases with multiple versions are listed only once.

Prototype

Boolean SysCreateDataBaseList (UInt32 type, UInt32 creator, UInt16* dbCount, MemHandle *dbIDs, Boolean lookupName)

Parameters

type

Type of database to find (0 for wildcard).

creator

Creator of database to find (0 for wildcard).

dbCount

Pointer to contain count of matching databases.

dbIDs

Pointer to handle allocated to contain the database list.

lookupName

Use tAIN names and sort the list.

Result

Returns false if no databases were found, true if databases were found. dbCount is updated to the number of databases found; dbIDs is updated to the list of matching databases found.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysCreatePanelList

Purpose

Generate a list of panels found on the memory cards and return the result. Multiple versions of a panel are listed once.

Prototype

Boolean SysCreatePanelList (UInt16* panelCount, MemHandle *panelIDs)

Parameters

panelCount

Pointer to set to the number of panels.

panelIDs

Pointer to handle containing a list of panels.

Result

Returns false if no panels were found, true if panels were found. panelCount is updated to the number of panels found; panelIDs is updated to the IDs of panels found.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysCurAppDatabase

Purpose

Return the card number and database ID of the current application's resource database.

Prototype

Err SysCurAppDatabase (UInt16* cardNoP, LocalID* dbIDP)

Parameters

cardNoP

Pointer to the card number; 0 or 1.

dbIDP

Pointer to the database ID.

Result

Returns 0 if no error, or SysErrParamErr if an error occurs.

See Also

SysAppLaunch, SysUIAppSwitch

SysErrString

Purpose

Returns text to describe an error number. This routine looks up the textual description of a system error number in the appropriate List resource and creates a string that can be used to display that error.

The actual string will be of the form: "<error message> (XXXX)" where XXXX is the hexadecimal error number.

This routine looks for a resource of type 'tstl' and resource ID of (err>>8). It then grabs the string at index (err & 0x00FF) out of that resource.

The first string in the resource is called index #1 by Constructor, NOT #0. For example, an error code of 0x0101 will fetch the first string in the resource.

Prototype

Char* SysErrString (Err err, Char* strP, UInt16 maxLen)

Parameters

err

Error number

strP

Pointer to space to form the string

maxLen

Size of strP buffer.

Result

Stores the error number string.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysFormPointerArrayToStrings

Purpose

Form an array of pointers to strings in a block. Useful for setting the items of a list.

Prototype

MemHandle SysFormPointerArrayToStrings (Char* c, Int16 stringCount)

Parameters

c

Pointer to packed block of strings, each terminated by NULL.

stringCount

Count of strings in block.

Result

Unlocked handle to allocated array of pointers to the strings in the passed block. The returned array points to the strings in the passed packed block.

SysGetOSVersionString

Purpose

Return the version number of the Palm operating system.

Prototype

Char* SysGetOSVersionString()

Parameters

Result

Returns a string such as "v. 3.0."

Comments

You must free the returned string using the MemPtrFree function.

Compatibility

Implemented only if 3.0 New Feature Set is present.

SysGetROMToken

Purpose

Return from ROM a value specified by token.

Prototype

Err SysGetROMToken (UInt16 cardNo, UInt32 token, UInt8 **dataP, UInt16 *sizeP)

Parameters

-> cardNo

The card on which the ROM to be queried resides. Currently, no Palm hardware provides multiple cards, so this value must be 0.

-> token

The value to retrieve, as specified by one of the following tokens:

sysROMTokenSnum

The serial number of the ROM, expressed as a text string with no null terminator.

<- dataP

Pointer to a text buffer that holds the requested value when the function returns.

<- sizeP

The number of bytes in the dataP buffer.

Result

Returns the requested value if no error, or an error code if an error occurs. If this function returns an error, or if the returned pointer to the buffer is NULL, or if the first byte of the text buffer is 0xFF, then no serial number is available.

Comments

The serial number is shown to the user in the Application Launcher, along with a checksum digit you can use to validate input when your users read the ID from their device and type it in or tell it to someone else.

Compatibility

Implemented only if 3.0 New Feature Set is present. Serial numbers are available only on flash ROM-based units.

See Also

"Retrieving the ROM Serial Number" section in the Palm OS Programmer's Companion shows how to retrieve the ROM serial number and calculate its associated checksum.

SysGetStackInfo

Purpose

Return the start and end of the current thread's stack.

Prototype

Boolean SysGetStackInfo (MemPtr *startPP, MemPtr *endPP)

Parameters

startPP

Upon return, points to the start of the stack.

endPP

Upon return, points to the end of the stack.

Result

Returns true if the stack has not overflowed, that is, the value of the stack overflow address has not been changed. Returns false if the stack overflow value has been overwritten, meaning that a stack overflow has occurred.

Compatibility

Implemented only if 3.0 New Feature Set is present.

SysGetTrapAddress

Purpose

Return the address of a function given its system trap.

Prototype

void* SysGetTrapAddress (UInt16 trapNum)

Parameters

-> trapNum

One of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.h on Palm OS version 3.5 and higher.

Result

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

Comments

Use this function for performance reasons. You can then use the address it returns to call the function without having to go through the trap dispatch table. This function is mostly useful for optimizing the performance of functions called in a tight loop.

The Palm OS trap dispatch mechanism allows the trap table entries to be modified at any time, either as the result of a system update or a hack. For this reason, it's important to call this function immediately before entering the tight loop. If the trap address changes in between when you call SysGetTrapAddress and you use the address, the wrong function will be called.

SysGraffitiReferenceDialog

Purpose

Pop up the Graffiti^® Reference Dialog.

Prototype

void SysGraffitiReferenceDialog (ReferenceType referenceType)

Parameters

referenceType

Which reference to display. See GraffitiReference.h for more information.

Result

Nothing returned.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysGremlins

Purpose

Query the Gremlins facility. You pass a selector for a function and parameters for that function. Gremlins performs the function call and returns the result.

Prototype

UInt32 SysGremlins (GremlinFunctionType selector, GremlinParamsType *params)

Parameters

selector

The selector for a function to pass to Gremlins.

params

Pointer to a parameter block used to pass parameters to the function specified by selector.

Result

Returns the result of the function performed in Gremlins.

Comments

Currently, only one selector is defined, GremlinIsOn, which takes no parameters. GremlinIsOn returns 0 if Gremlins is not running, non-zero if it is running.

Currently, non-zero values are returned only from the version of Gremlins in the Palm OS emulator. The Gremlins running in the Simulator on a Macintosh and over the serial line via the Palm Debugger return zero for GremlinIsOn.

Use this function if you need to alter the application's behavior when Gremlins is running. For example, the debug 3.0 ROM refuses to bring up the digitizer panel when Gremlins is running under the emulator.

Compatibility

Implemented only if 3.0 New Feature Set is present.

In Palm OS 3.2 and later, SysGremlins is replaced by the functions defined in the file HostControl.h. Specifically, the one selector supported by SysGremlins is replaced with the function HostGremlinIsRunning. For backward compatibility, SysGremlins is mapped to HostGremlinIsRunning.

SysHandleEvent

Purpose

Handle defaults for system events such as hard and soft key presses.

Prototype

Boolean SysHandleEvent (EventPtr eventP)

Parameters

eventP

Pointer to an event.

Result

Returns true if the system handled the event.

Comments

Applications should call this routine immediately after calling EvtGetEvent unless they want to override the default system behavior. However, overriding the default system behavior is almost never appropriate for an application.

See Also

EvtProcessSoftKeyStroke, KeyRates

SysInsertionSort

Purpose

Sort elements in an array according to the passed comparison function.

Prototype

void SysInsertionSort (void* baseP, Int16 numOfElements, Int16 width, const CmpFuncPtr comparF, const Int32 other)

Parameters

baseP

Base pointer to an array of elements.

numOfElements

Number of elements to sort (must be at least 2).

width

Width of an element.

comparF

Comparison function (see Comments).

other

Other data passed to the comparison function.

Result

Returns nothing.

Comments

Only elements which are out of order move. Moved elements are moved to the end of the range of equal elements. If a large amount of elements are being sorted, try to use the quick sort (see SysQSort).

This is the insertion sort algorithm: Starting with the second element, each element is compared to the preceding element. Each element not greater than the last is inserted into sorted position within those already sorted. A binary search for the insertion point is performed. A moved element is inserted after any other equal elements.

In Palm OS 2.0 and later, DmComparF has 6 parameters.

These parameters allow a Palm OS application to pass more information to the system than before, most noticeably the record (and all associated information) which allows sorting by unique ID, so that the Palm OS device and the desktop always match.

The revised callback is used by new sorting routines (and can be used the same way by your application):

typedef Int16 DmComparF (void *, void *, Int16 other, SortRecordInfoPtr, SortRecordInfoPtr,

MemHandle appInfoH);

As a rule, this change in the number of arguments doesn't cause problems when a 1.0 application is run on a 2.0 or later device, because the system only pulls the arguments from the stack that are there.

Note, however, that some optimized applications built with tools other than Metrowerks CodeWarrior for Palm OS may have problems as a result of the change in arguments when running on a 2.0 or later device.

The 2.0 comparison function (comparF) has this prototype:

Int comparF (VoidPtr, VoidPtr, Long other);

The 1.0 comparison function (comparF) had this prototype:

Int comparF (BytePtr A, BytePtr B, Long other);

The function returns:

• > 0 if A > B
  
  
• < 0 if A< B
  
  
• 0 if A = B
  

See Also

SysQSort

SysKeyboardDialog

Purpose

Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly.

Prototype

void SysKeyboardDialog (KeyboardType kbd)

Parameters

kbd

The keyboard type. See Keyboard.h.

Result

Returns nothing. Changes the field's text chunk.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

SysKeyboardDialogV10, FrmSetFocus

SysKeyboardDialogV10

Purpose

Pop up the system keyboard if there is a field object with the focus. The field object's text chunk is edited directly.

Prototype

void SysKeyboardDialogV10 ()

Parameters

Result

Returns nothing. The field's text chunk is changed.

Compatibility

Corresponds to the 1.0 implementation of SysKeyboardDialog.

See Also

SysKeyboardDialog, FrmSetFocus

SysLibFind

Purpose

Return a reference number for a library that is already loaded, given its name.

Prototype

Err SysLibFind (const Char* nameP, UInt16* refNumP)

Parameters

nameP

Pointer to the name of a loaded library.

refNumP

Pointer to a variable for returning the library reference number (on failure, this variable is undefined)

Result

0 if no error; otherwise: sysErrLibNotFound (if the library is not yet loaded), or another error returned from the library's install entry point.

Comments

Most built-in libraries (NetLib, serial, IR) are preloaded automatically when the system is reset. Third-party libraries must be loaded before this call can succeed (use SysLibLoad). You can check if a library is already loaded by calling SysLibFind and checking for a 0 error return value (it will return a non-zero value if the library is not loaded).

SysLibLoad

Purpose

Load a library given its database creator and type.

Prototype

Err SysLibLoad (UInt32 libType, UInt32 libCreator, UInt16* refNumP)

Parameters

libType

Type of library database.

libCreator

Creator of library database.

refNumP

Pointer to variable for returning the library reference number (on failure, sysInvalidRefNum is returned in this variable)

Result

0 if no error; otherwise: sysErrLibNotFound, sysErrNoFreeRAM, sysErrNoFreeLibSlots, or other error returned from the library's install entry point.

Comments

Presently, the "load" functionality is not supported when you use the Palm OS Simulator.

When an application no longer needs a library that it successfully loaded via SysLibLoad, it is responsible for unloading the library by calling SysLibRemove and passing it the library reference number returned by SysLibLoad. More information is available in the white paper on shared libraries, which you can find on the Palm developer support web site.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysLibRemove

Purpose

Unload a library previously loaded with SysLibLoad.

Prototype

Err SysLibRemove (UInt16 refNum)

Parameters

-> refNum

The library reference number.

Result

0 if no error; otherwise sysErrParamErr if the refNum is not a valid library reference number.

Comments

SysLibRemove releases the dynamic memory allocated to the shared library's dispatch table, resources, and global variables.

SysQSort

Purpose

Sort elements in an array according to the passed comparison function. Equal records can be in any position relative to each other because a quick sort tends to scramble the ordering of records. As a result, calling SysQSort multiple times can result in a different order if the records are not completely unique. If you don't want this behavior, use the insertion sort instead (see SysInsertionSort).

To pick the pivot point, the quick sort algorithm picks the middle of three records picked from around the middle of all records. That way, the algorithm can take advantage of partially sorted data.

These optimizations are built in:

• The routine contains its own stack to limit uncontrolled recursion. When the stack is full, an insertion sort is used because it doesn't require more stack space.
  
  
• An insertion sort is also used when the number of records is low. This avoids the overhead of a quick sort which is noticeable for small numbers of records.
  
  
• If the records seem mostly sorted, an insertion sort is performed to move only those few records that need to be moved.
  

Prototype

void SysQSort (void* baseP, Int16 numOfElements, Int16 width, const CmpFuncPtr comparF, const Int32 other)

Parameters

baseP

Base pointer to an array of elements.

numOfElements

Number of elements to sort (must be at least 2).

width

Width of an element.

comparF

Comparison function. See Comments for SysInsertionSort.

other

Other data passed to the comparison function.

Result

Returns nothing.

See Also

SysInsertionSort

SysRandom

Purpose

Return a random number anywhere from 0 to sysRandomMax.

Prototype

Int16 SysRandom (UInt32 newSeed)

Parameters

newSeed

New seed value, or 0 to use existing seed.

Result

Returns a random number.

SysReset

Purpose

Perform a soft reset and reinitialize the globals and the dynamic memory heap.

Prototype

void SysReset (void)

Parameters

Result

No return value.

Comments

This routine resets the system, reinitializes the globals area and all system managers, and reinitializes the dynamic heap. All database information is preserved. This routine is called when the user presses the hidden reset switch on the device.

When running an application using the simulator, this routine looks for two data files that represent the memory of card 0 and card 1. If these are found, the Palm OS memory image is created using them. If they are not found, they are created.

When running an application on the device, this routine simply looks for the memory cards at fixed locations.

SysSetAutoOffTime

Purpose

Set the time out value in seconds for auto-power-off. Zero means never power off.

Prototype

UInt16 SysSetAutoOffTime (UInt16 seconds)

Parameters

seconds

Time out in seconds, or 0 for no time out.

Result

Returns previous value of time out in seconds.

SysSetTrapAddress

Purpose

Set the address of the function corresponding to a system trap.

Prototype

Err SysSetTrapAddress (UInt16 trapNum, void* procP)

Parameters

-> trapNum

One of the routine selectors defined in SysTraps.h (sysTrap...) or CoreTraps.h on Palm OS version 3.5 and higher.

-> procP

Pointer to a function that the trap identified by trapNum is to point to.

Result

Returns 0 if no error, or SysErrParamErr if trapNum is greater than the number of traps in the trap table.

Comments

This function is useful for patching a system trap, in combination with SysGetTrapAddress. To patch a system trap in your application, first call SysGetTrapAddress to get the trap address and then save this value somewhere. Next use SysSetTrapAddress to set the trap address to point to your function. Before your application exits, remove the patch by calling SysSetTrapAddress and passing in the original trap address you saved.

---

WARNING!

If your application patches a system trap using this function, you must remove the patch before your application exits. Do not use this mechanism to permanently patch system traps as it may cause unpredictable results for the system and other applications.

---

SysStringByIndex

Purpose

Copy a string out of a string list resource by index. String list resources are of type 'tSTL' and contain a list of strings and a prefix string.

ResEdit always displays the items in the list as starting at 1, not 0. Consider this when creating your string list.

Prototype

Char* SysStringByIndex (UInt16 resID, UInt16 index, Char* strP, UInt16 maxLen)

Parameters

resID

Resource ID of the string list.

index

String to get out of the list.

strP

Pointer to space to form the string.

maxLen

Size of strP buffer.

Result

Returns a pointer to the copied string. The string returned from this call will be the prefix string appended with the designated index string. Indices are 0-based; index 0 is the first string in the resource.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysTaskDelay

Purpose

Put the processor into doze mode for the specified number of ticks.

Prototype

Err SysTaskDelay (Int32 delay)

Parameters

delay

Number of ticks to wait (see SysTicksPerSecond)

Result

Returns 0 if no error.

See Also

EvtGetEvent

SysTicksPerSecond

Purpose

Return the number of ticks per second. This routine allows applications to be tolerant of changes to the ticks per second rate in the system.

Prototype

UInt16 SysTicksPerSecond (void)

Parameters

Result

Returns the number of ticks per second.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SysUIAppSwitch

Purpose

Try to make the current UI application quit and then launch the UI application specified by card number and database ID.

Prototype

Err SysUIAppSwitch (UInt16 cardNo, LocalID dbID, UInt16 cmd, MemPtr cmdPBP)

Parameters

cardNo

Card number for the new application; currently only card 0 is valid.

dbID

ID of the new application.

cmd

Action code (launch code).

cmdPBP

Action code (launch code) parameter block.

Result

Returns 0 if no error.

Comments

Do not use this function to open the system-supplied Application Launcher application. If another application has replaced the default launcher with one of its own, this function will open the custom launcher instead of the system-supplied one. To open the system-supplied launcher reliably, enqueue a keyDownEvent that contains a launchChr, as shown in the section "Application Launcher" of the user interface chapter in the Palm OS Programmer's Companion.

If you are passing a parameter block (the cmdPBP parameter), you must set the owner of the parameter block chunk to the operating system. To do this, and for more information, see MemPtrSetOwner. If the parameter block structure contains references by pointer or handle to any other chunks, you also must set the owner of those chunks by using MemHandleSetOwner or MemPtrSetOwner.

See Also

SysAppLaunch, Chapter 3, "Application Startup and Stop." in the Palm OS Programmer's Companion.