8 Palm System Features

In this chapter, you learn how to work with the features that the Palm OS^® system provides, such as sound, alarms, and floating-point operations. Most parts of the Palm OS are controlled by a manager, which is a group of functions that work together to implement a certain functionality. As a rule, all functions that belong to one manager use the same prefix and work together to implement a certain aspect of functionality.

This chapter discusses these topics:

• Alarms
  
  
• Features
  
  
• Notifications
  
  
• Sound
  
  
• System Boot and Reset
  
  
• Hardware Interaction
  
  
• The Microkernel
  
  
• Retrieving the ROM Serial Number
  
  
• Time
  
  
• Floating-Point
  
  
• Summary of System Features
  

Alarms

The Palm OS alarm manager provides support for setting real-time alarms, for performing some periodic activity, or for displaying a reminder. The alarm manager:

• Works closely with the time manager to handle real-time alarms.
  
  
• Sends launch codes to applications that set a specific time alarm to inform the application the alarm is due.
  
  
• Handles alarms by application in a two cycle operation
  
  • First, it notifies each application that the alarm has occurred.
  • Second, it allows each application to display some UI.
  
  
• Allows only one alarm to be set per application.
  

However, the alarm manager:

• Doesn't provide reminder dialog boxes.
  
  
• Doesn't play the alarm sound.
  

This section looks in some detail at how the alarm manager and applications interact when processing an alarm. It covers:

• Setting an Alarm
  
  
• Alarm Scenario
  
  
• Setting a Procedure Alarm
  

Setting an Alarm

The most common use of the alarm manager is to set a real-time alarm within an application. Often, you set this type of alarm because you want to inform the user of an event. For example, the Datebook application sets alarms to inform users of their appointments.

Implementing such an alarm is a two step process. First, use the function AlmSetAlarm to set the alarm. Specify when the alarm should trigger and which application should be informed at that time.

Listing 8.1 shows how the Datebook application sets an alarm.

Listing 8.1 Setting an alarm

Second, have your PilotMain function respond to the launch codes sysAppLaunchCmdAlarmTriggered and sysAppLaunchCmdDisplayAlarm.

When an alarm is triggered, the alarm manager notifies each application that set an alarm for that time via the sysAppLaunchCmdAlarmTriggered launch code. After each application has processed this launch code, the alarm manager sends each application sysAppLaunchCmdDisplayAlarm so that the application can display the alarm. The section "Alarm Scenario" gives more information about when these launch codes are received and what actions your application might take. For a specific example of responding to these launch codes, see the Datebook sample code.

It's important to note the following:

• An application can have only one alarm pending at a time. If you call AlmSetAlarm and then call it again before the first alarm has triggered, the alarm manager replaces the first alarm with the second alarm. You can use the AlmGetAlarm function to find out if the application has any alarms pending.
  
  
• You do not have access to global variables or code outside segment 0 (in a multi-segment application) when you respond to the launch codes. AlmSetAlarm takes a UInt32 parameter that you can use to pass a specific value so that you have access to it when the alarm triggers. (This is the ref parameter shown in Listing 8.1.) The parameter blocks for both launch codes provide access to this reference parameter. If the reference parameter isn't sufficient, you can define an application feature. See the section "Features" in this chapter.
  
  
• The database ID that you pass to AlmSetAlarm is the local ID of the application (the prc file), not of the record database that the application accesses. You use record database's local ID more frequently than you do the application's local ID, so this is a common mistake to make.
  
  
• In AlmSetAlarm, the alarm time is given as the number of seconds since 1/1/1904. If you need to convert a conventional date and time value to the number of seconds since 1/1/1904, use TimDateTimeToSeconds.
  
  
• If you want to clear a pending alarm, call AlmSetAlarm with 0 specified for the alarm seconds parameter.
  

Alarm Scenario

Here's how an application and the alarm manager typically interact when processing an alarm:

• Set the next alarm.
• Play a short sound.
• Perform some quick maintenance activity.

• Display a dialog box.
• Display some other type of reminder.

Setting a Procedure Alarm

Beginning with Palm OS version 3.2, the system supports setting procedure alarms in addition to the application-based alarms described in the previous sections. The differences between a procedure alarm and an application-based alarm are:

• When you set a procedure alarm, you specify a pointer to a function that should be called when the alarm triggers instead of an application that should be notified.
  
  
• When the alarm triggers, the alarm manager calls the specified procedure directly instead of using launch codes.
  
  
• If the system is in sleep mode, the alarm triggers without causing the LCD to light up.
  

You might use procedure alarms if:

• You want to perform a background task that is completely hidden from the user.
  
  
• You are writing a shared library and want to implement an alarm within that library.
  

To set a procedure alarm, you call AlmSetProcAlarm instead of AlmSetAlarm. (Similarly, you use the AlmGetProcAlarm function instead of AlmGetAlarm to see if any alarms are pending for this procedure.)

AlmSetProcAlarm is currently implemented as a macro that calls AlmSetAlarm using a special value for the card number parameter to notify the alarm manager that this is a procedure alarm. Instead of specifying the application's local ID and card number, you specify a function pointer. The other rules for AlmSetAlarm still apply. Notably, a given function can only have one alarm pending at a time, and you can clear any pending alarm by passing 0 for the alarm time.

When the alarm triggers, the alarm manager calls the function you specified. The function should have the prototype:

void myAlarmFunc (UInt16 almProcCmd, SysAlarmTriggeredParamType *paramP)

---

IMPORTANT: The function pointer must remain valid from the time AlmSetProcAlarm is called to the time the alarm is triggered. If the procedure is in a shared library, you must keep the library open. If the procedure is in a separately loaded code resource, the resource must remain locked until the alarm fires. When you close a library or unlock a resource, you must remove any pending alarms. If you don't, the system will crash when the alarm is triggered.

---

The first parameter to your function specifies why the alarm manager has called the function. Currently, the alarm manager calls the function in two instances:

• The alarm has triggered.
  
  
• The user has changed the system time, so the alarm time should be adjusted.
  

The second parameter is the same structure that is passed with the sysAppLaunchCmdAlarmTriggered launch code. It provides access to the reference parameter specified when the alarm was set, the time specified when the alarm was set, and the purgeAlarm field, which specifies if the alarm should be removed from the queue. In the case of procedure alarms, the alarm should always be removed from the queue. The system sets the purgeAlarm value to true after calling your function.

Features

A feature is a 32-bit value that has special meaning to both the feature publisher and to users of that feature. Features can be published by the system or by applications.

Each feature is identified by a feature creator and a feature number:

• The feature creator is a unique creator registered with Palm Computing^®. You usually use the creator type of the application that publishes the feature.
  
  
• The feature number is any 16-bit value used to distinguish between different features of a particular creator.
  

Once a feature is published, it remains present until it is explicitly unregistered or the device is reset. A feature published by an application sticks around even after the application quits.

This section introduces the feature manager by discussing these topics:

• The System Version Feature
  
  
• Application-Defined Features
  
  
• Using the Feature Manager
  
  
• Feature Memory
  

The System Version Feature

An example for a feature is the system version. This feature is published by the system and contains a 32-bit representation of the system version. The system version has a feature creator of sysFtrCreator and a feature number of sysFtrNumROMVersion). Currently, the different versions of the system software have the following numbers:

0x01003001	Palm OS 1.0
0x02003000	Palm OS 2.0
0x03003000	Palm OS 3.0
0x03103000	Palm OS 3.1
0x03103000	Palm OS 3.1
0x03103000	Palm OS 3.1
0x03203000	Palm OS 3.2
0x03503000	Palm OS 3.5

Any application can find out the system version by looking for this feature. For example:

// See if we're on ROM version 2.0 or later.

FtrGet(sysFtrCreator, sysFtrNumROMVersion,
    &romVersion);
if (romVersion >= 0x02000000) {
    ....
}

Other system features are defined in SystemMgr.h. System features are stored in a feature table in the ROM. (In Palm OS 3.1 and higher, the contents of this table are copied into the RAM feature table at system startup.) Checking for the presence of system features allows an application to be compatible with multiple versions of the system by refining its behavior depending on which capabilities are present or not. Future hardware platforms may lack some capabilities present in the first platform, so checking the system version feature is important.

---

IMPORTANT: For best results, we recommend that you check for specific features rather than relying on the system version number to determine if a specific API is available. For more details on checking for features, see the appendix Compatibility Guide in Palm OS SDK Reference.

---

Application-Defined Features

Applications may find the feature manager useful for their own private use. For example, an application may want to publish a feature that contains a pointer to some private data it needs for processing launch codes. Because an application's global data is not generally available while it processes launch codes, using the feature manager is usually the easiest way for an application to get to its data.

The feature manager maintains one feature table in the RAM as well as the feature table in the ROM. Application-defined features are stored in the RAM feature table.

Using the Feature Manager

To check whether a particular feature is present, call FtrGet and pass it the feature creator and feature number. If the feature exists, FtrGet returns the 32-bit value of the feature. If the feature doesn't exist, an error code is returned.

To publish a new feature or change the value of an existing one, call FtrSet and pass the feature creator, number, and the 32-bit value of the feature. A published feature remains available until it is explicitly removed by a call to FtrUnregister or until the system resets; simply quitting an application doesn't remove a feature published by that application.

Call FtrUnregister to remove features that were created by calling FtrSet.

You can get a complete list of all published features by calling FtrGetByIndex repeatedly. Passing an index value starting at 0 to FtrGetByIndex and incrementing repeatedly by 1 eventually returns all available features. FtrGetByIndex accepts a parameter that specifies whether to search the ROM feature table or RAM feature table. Note that in Palm OS version 3.1 and higher, the contents of the ROM table are copied into the RAM table at system startup; thus the RAM table serves the entire system.

Feature Memory

Palm OS 3.1 adds support for feature memory. Feature memory provides quick, efficient access to data that persists between invocations of an application. The values stored in feature memory persist until the device is reset or until you explicitly free the memory. Feature memory is memory allocated from the storage heap. Thus, you write to feature memory using DmWrite, which means that writing to feature memory is no faster than writing to a database. However, feature memory can provide more efficient access to that data in certain circumstances.

To allocate a chunk of feature memory, call FtrPtrNew, specifying a feature creator, a feature number, the number of bytes to allocate, and a location where the feature manager can return a pointer to the newly allocated memory chunk. For example:

FtrPtrNew(appCreator,
myFtrMemFtr, 32, &ftrMem);

Elsewhere in your application, you can obtain the pointer to the feature memory chunk using FtrGet.

---

NOTE:  

Starting with Palm OS 3.5 FtrPtrNew allows allocating chunks larger than 64k. Do keep in mind standard issues with allocating large chunks of memory: there might not be enough contiguous space, and it can impact system performance.

---

Feature memory is considered a performance optimization. The conditions under which you'd use it are not common, and you probably won't find them in a typical application. You use feature memory in code that:

• Is executed infrequently
  
  
• Does not have access to global variables
  
  
• Needs access to data whose contents change infrequently and that cannot be stored in a 32-bit feature value
  

For example, suppose you've written a function that is called in response to a launch code, and you expect to receive this launch code frequently. Suppose that function needs access to the application's preferences database. At the start of the function, you'd need to open the database and read the data from it. If the function is called frequently, opening the database each time can be a drain on performance. Instead, you can allocate a chunk of feature memory and write the values you need to that chunk. Because the chunk persists until the device is reset, you only need to open the database once. Listing 8.2 illustrates this example.

Listing 8.2 Using feature memory

Another potential use of feature memory is to "publish" data from your application or library to other applications when that data doesn't fit in a normal 32-bit feature value. For example, suppose you are writing a communications library and you want to publish an icon that client applications can use to draw the current connection state. The library can use FtrPtrNew to allocate a feature memory chunk and store an icon representing the current state in that location. Applications can then use FtrGet to access the icon and pass the result to WinDrawBitmap to display the connection state on the screen.

Notifications

On systems where the Notification Feature Set is present, your application can receive notifications when certain system-level events or application-level events occur. Notifications are similar to application launch codes, but differ from them in two important ways:

• Notifications can be sent to any code resource, such as a shared library or a system extension (for example, a hack installed with the HackMaster program). Launch codes can only be sent to applications. Any code resource that is registered to receive a notification is called a notification client.
  
  
• Notifications are only sent to applications or code resources that have specifically registered to receive them, making them more efficient than launch codes. Many launch codes are sent to all installed applications to give each application a chance to respond.
  

The Palm OS system and the built-in applications send notifications when certain events occur. See the chapter "Notification Manager" in the Palm OS SDK Reference for a complete list. (The notification manager broadcasts the notifications and maintains a list of clients for each notification).

It's also possible for your application to create and broadcast its own notifications. However, doing so is rare. It's more likely that you'll want to register to receive the predefined notifications.

Three general types of event flow are possible using the notification manager:

• Single consumer
  

  Each client is notified that the event has occurred and handles it in its own way without modifying any information in the parameter block.

  
  
• Collaborative
  

  The notification's parameter block contains a handled flag. Clients can set this flag to communicate to other clients that the event has been handled, while still allowing them to receive the notification. An example of this is the sysNotifyAntennaRaisedEvent for Palm VII^™ series devices. A client might decide to handle the antenna key down event and in this case, sets handled to true to inform other clients that the event has been handled.

  
  
• Collective
  

  Each client can add information to the notification's parameter block, allowing the data to be accumulated for all clients. This style of notification could be used, for example, to build a menu dynamically by letting each client add its own menu text. The sysNotifyMenuCmdBarOpenEvent is similar to this style of notification.

Registering for a Notification

To receive notification that an event has occurred, you must register for it using the SysNotifyRegister function. Once you register for a notification, you remain registered until the system is reset or until you explicitly unregister for this notification using SysNotifyUnregister.

To register an application for the HotSync^® notification, you'd use a function call similar to the one in Listing 8.3.

Listing 8.3 Registering an application for a notification

If you are writing a shared library instead of an application and you want to be notified about the HotSync event, your call to SysNotifyRegister looks slightly different. See Listing 8.4.

Listing 8.4 Registering a shared library for a notification

The parameters you pass to the SysNotifyRegister function specify the following:

• The first two parameters are the card number and database ID for the prc file. Be sure you're not passing the local ID of the record database that your application accesses. You use the record database's local ID more frequently than you do the application's local ID, so this is a common mistake to make.
  
  
• sysNotifySyncStartEvent specifies that you want to be informed when a HotSync operation is about to start. There is also a sysNotifySyncFinishEvent that specifies that a HotSync operation has ended.
  
  
• The next parameter specifies how the notification should be received. This is where Listing 8.3 and Listing 8.4 differ.
  

  Applications use NULL for this parameter to specify that they should be notified through the application launch code sysAppLaunchCmdNotify. As with all other launch codes, the system passes this to the application's PilotMain function.

  The shared library has no PilotMain function and therefore no way to receive a launch code, so it passes a pointer to a callback routine. Only use a callback routine if your code doesn't have a PilotMain.

  Note that it's always necessary to pass the card number and database ID of your prc file even if you specify a callback routine.

  
  
• sysNotifyNormalPriority means that you don't want your code to receive any special consideration when receiving the notification. Notifications are broadcast synchronously in priority order. The lower the number you specify here, the earlier you receive the notification in the list.
  

  In virtually all cases, you should use sysNotifyNormalPriority. If you absolutely must ensure that your code is notified in a certain order (either before most notifications or after most notifications), use a value between -15 and +15 for the priority. Using a value in this range ensures that your code won't collide with the system's handling of notifications.

  
  
• myDataP is a pointer to any data you need to access in your notification handler routine. As with most launch codes, sysAppLaunchCmdNotify does not provide access to global variables, so you should use this pointer to pass yourself any needed data.
  

After you've made the calls shown in Listing 8.3 and Listing 8.4 and the system is about to begin a HotSync operation, it broadcasts the sysNotifySyncStartEvent notification to both clients.

The application is notified through the sysAppLaunchCmdNotify launch code. This launch code's parameter block is a SysNotifyParamType structure containing the notification name, the broadcaster, and a pointer to your specific data (myDataP in the example above). Some notifications contain extra information in a notifyDetailsP field in this structure. The HotSync notifications do not use the notifyDetailsP field.

The shared library is notified by a call to its SyncNotifyHandler function. This function is passed the same SysNotifyParamType structure that is passed through the launch code mechanism.

---

IMPORTANT: Because the callback pointer is used to directly call the function, the pointer must remain valid from the time SysNotifyRegister is called to the time the notification is broadcast. If the function is in a shared library, you must keep the library open. If the function is in a separately loaded code resource, the resource must remain locked while registered for the notification. When you close a library or unlock a resource, you must first unregister for any notifications. If you don't, the system will crash when the notification is broadcast.

---

Writing a Notification Handler

The application's response to sysAppLaunchCmdNotify and the shared library's callback function are called notification handlers. A notification handler may perform any processing necessary, including displaying a user interface or broadcasting other notifications.

When displaying a user interface, consider the possibility that you may be blocking other applications from receiving the notification. For this reason, it's generally not a good idea to display a modal form or do anything else that requires waiting for the user to respond. Also, many of the notifications are broadcast during SysHandleEvent, which means your application event loop may not have progressed to the point where it is possible for you to display a user interface, or you may overflow the stack.

If you need to perform some lengthy process in a notification handler, one way to ensure that you aren't blocking other events is to send yourself a deferred notification. For example, Listing 8.5 shows a notification handler for the sysNotifyTimeChangeEvent notification that performs no work other than setting up a deferred notification (myDeferredNotifyEvent) and scheduling it for broadcast. When the application receives the myDeferredNotifyEvent, it calls the MyNotifyHandler function, which is where the application really handles the time change event.

Listing 8.5 Deferring notification within a handler

The SysNotifyBroadcastDeferred function broadcasts the specified notification to all interested parties; however, it waits to do so until the current event has completed processing. Thus, by using a separate deferred notification, you can be sure that all other clients have had a chance to respond to the first notification.

There are two functions that broadcast notifications: SysNotifyBroadcast, which immediately broadcasts the notification, and SysNotifyBroadcastDeferred, which waits until the next time EvtGetEvent is called. Notification handlers should use SysNotifyBroadcastDeferred to avoid the possibility of overflowing the notification stack.

A special case of dealing with lengthy computations in a notification handler occurs when the system is being put to sleep. See "Sleep and Wake Notifications" below.

Sleep and Wake Notifications

Several notifications are broadcast at various stages when the system goes to sleep and when the system wakes up. These are:

• sysNotifySleepRequestEvent
  
  
• sysNotifySleepNotifyEvent
  
  
• sysNotifyEarlyWakeupEvent
  
  
• sysNotifyLateWakeupEvent
  

These notifications are not guaranteed to be broadcast. For example, if the system goes to sleep because the user removes the batteries, sleep notifications are not sent. Thus, these notifications are unsuitable for applications where external hardware must be shut off to conserve power before the system goes to sleep.

If you want to know when the system is going to sleep because you have a small amount of cleanup that should occur beforehand, then register for sysNotifySleepNotifyEvent.

It is recommended that you not perform any sort of prolonged activity, such as displaying an alert panel that requests confirmation, in response to a sleep notification. If you do, the alert might be displayed long enough to trigger another auto-off event, which could be detrimental to other handlers of the sleep notify event.

In a few instances, you might need to prevent the system from going to sleep. For example, your code might be in the middle of performing some lengthy computation or in the middle of attempting a network connection. If so, register for the sysNotifySleepRequestEvent instead. This notification informs all clients that the system might go to sleep. If necessary, your handler can delay the sleep request by doing the following:

notify->notifyDetailsP->deferSleep++;

The system checks the deferSleep value when each notification handler returns. If it is nonzero, it cancels the sleep event.

After you defer sleep, your code is free to finish what it was doing. When it is finished, you must allow the system to continue with the sleep event. To do so, create a keyDownEvent with the resumeSleepChr and the command key bit set (to signal that the character is virtual) and add it to the event queue. When the system receives this event, it will again broadcast the sysNotifySleepRequestEvent to all clients. If deferSleep is 0 after all clients return, then the system knows it is safe to go to sleep, and it broadcasts the sysNotifySleepNotifyEvent to all of its clients.

Notice that you may potentially receive the sysNotifySleepRequestEvent many times before the system actually goes to sleep, but you receive the sysNotifySleepNotifyEvent exactly once.

During a wake-up event, the other two notifications listed above are broadcast. The sysNotifyEarlyWakeupEvent is broadcast very early on in the wakeup process, generally before the screen has turned on. At this stage, it is not guaranteed that the system will fully wake up. It may simply handle an alarm or a battery charger event and go back to sleep. Most applications that need notification of a wakeup event will probably want to register for sysNotifyLateWakeupEvent instead. At this stage, the screen has been turned on and the system is guaranteed to fully wake up.

Sound

The Palm Computing platform device has primitive sound generation. A square wave is generated directly from the 68328's PWM circuitry. There is frequency, duration, and volume control. Additionally, Palm OS 3.0 and higher support creating and playing standard MIDI sounds.

The Palm OS sound manager provides an extendable API for playing custom sounds and system sounds, and for controlling default sound settings. Although the sound API accommodates multichannel design, the system provides only a single sound channel at present.

The sound hardware can play only one simple tone at a time through an onboard piezoelectric speaker. Note that for a particular amplitude level, the Palm III^™ device is slightly louder than its predecessors.

Single tones can be played by the SndDoCmd function and system sounds are played by the SndPlaySystemSound function. The end-user can control the amplitude of alarm sounds, game sounds, and system sounds by means of the Preferences application. System-supplied sounds include the Information, Warning, Error, Startup, Alarm, Confirmation, and Click sounds.

Palm OS 3.0 introduces support for Standard MIDI Files (SMFs), format 0. An SMF is a note-by-note description of a tune--Palm OS doesn't support sampled sound, multiple voices, or complex "instruments." You can download the SMF format specification from the http://www.midi.org Web site.

The alarm sounds used in the built-in Date Book application are SMFs stored in the System MIDI Sounds database and can be played by the SndPlaySmf function.

All SMF records in the System MIDI Sounds database are available to the user. Developers can add their own alarm SMFs to this database as a way to add variety and personalization to their devices. You can use the sysFileTMidi file type and sysFileCSystem creator to open this database.

Each record in the database is a single SMF, with a header structure containing the user-visible name. The record includes a song header, then a track header, followed by any number of events. The system only recognizes the keyDown, keyUp and tempo events in a single track; other commands which might be in the SMF are ignored. For more information, see the following:

• Adding a Standard MIDI File to a Database in this chapter.
  
  
• SndCallbackInfoType in the Palm OS SDK Reference.
  
  
• SndMidiRecHdrType in the Palm OS SDK Reference.
  

You can use standard MIDI tools to create SMF blocks on desktop computers, or you can write code to create them on the Palm OS device. The sample code project "RockMusic," particularly the routines in the MakeSMF.c file, can be helpful to see how to create an SMF programmatically.

Previous versions of Palm OS don't support SMFs or asynchronous notes; don't use the new routines or commands when the FtrGet function returns a system version of less than 0x03000000. Doing so will crash your application. See the section "The System Version Feature" for more information.

Synchronous and Asynchronous Sound

The SndDoCmd function executes synchronously or asynchronously according to the operation it is to perform. The sndCmdNoteOn and sndCmdFrqOn operations execute asynchronously; that is, they are non-blocking and can be interrupted by another sound command. In contrast, the sndCmdFreqDurationAmp operation is synchronous and blocking (it cannot be interrupted).

The SndPlaySmf function is also synchronous and blocking; however, the Sound Manager polls the key queue periodically during playback and halts playback in progress if it finds events generated by user interaction with the screen, digitizer, or hardware-based buttons. Optionally, the caller can override this default behavior to specify that the SndPlaySmf function play the SMF to completion without being interrupted by user events.

Using the Sound Manager

Before playing custom sounds that require a volume (amplitude) setting, your code needs to discover the user's current volume settings. To do so in Palm OS 3.X, pass one of the prefSysSoundVolume, prefGameSoundVolume, or prefAlarmSoundVolume selectors to the PrefGetPreference function.

---

NOTE:  

See "Sound Preferences Compatibility Information" for important information regarding the correct use of sound preferences in various versions of Palm OS.

---

You can pass the returned amplitude information to the SndPlaySmf function as one element of a SndSmfOptionsType parameter block. Alternatively, you can pass amplitude information to the SndDoCmd function as an element of a SndCommandType parameter block.

To execute a sound manager command, pass to the SndDoCmd function a sound channel pointer (presently, only NULL is supported and maps to the shared channel), a pointer to a structure of SndCommandType, and a flag indicating whether the command should be performed asynchronously.

To play SMFs, call the SndPlaySMF function. This function, which is new in Palm OS 3.0, is used by the built in Date Book application to play alarm sounds.

To play single notes, you can use either of the SndPlaySMF or SndDoCmd functions. Of course, you can use the SndPlaySMF function to play a single MIDI note from an SMF. You can also use the SndDoCmd function to play a single MIDI note by passing the sndCmdNoteOn command selector to this function. To specify by frequency the note to be played, pass the sndCmdFrqOn command selector to the SndDoCmd function.You can pass the sndCmdQuiet selector to this function to stop playback of the current note.

The system provides no specialized API for playing game sounds or alarm sounds. When an alarm triggers, the application that set the alarm must use the standard Sound Manager API to play the sound associated with that alarm. Similarly, game sounds are implemented by the game developer using any appropriate element of the Sound Manager API. Games should observe the prefGameSoundVolume setting, as described in the section "Sound Preferences Compatibility Information."

To play a default system sound, such as a click or an error beep, pass the appropriate system sound ID to the SndPlaySystemSound function, which will play that sound at the volume level specified by the user's system sound preference. For the complete list of system sound IDs, see the SoundMgr.h file provided by the Palm OS SDK.

Adding a Standard MIDI File to a Database

To add a format 0 standard MIDI file to the system MIDI database, you can use code similar to the AddSmfToDatabase example function shown in the following code listing. This function returns 0 if successful, and returns a non-zero value otherwise. To use a different database, pass different creator and type values to the DmOpenDatabaseByTypeCreator function.

Listing 8.6 AddSmfToDatabase

Saving References to Standard MIDI Files

To save a reference to a SMF stored in a particular database, save its record ID and the name of the database in which it is stored. Do not store the database ID between invocations of your application, because various events, such as a HotSync, can invalidate database IDs. Using an invalid database ID can crash your application.

Retrieving a Standard MIDI File From a Database

Standard MIDI Files (SMFs) are stored as individual records in a MIDI record database--one SMF per record. Palm OS defines the database type sysFileTMidi for MIDI record databases. The system MIDI database, with type sysFileTMidi and creator sysFileCSystem, holds multiple system alarm sounds. In addition, your applications can create their own private MIDI databases of type sysFileTMidi and your own creator.

To obtain a particular SMF, you need to identify the database in which it resides and the specific database record which holds the SMF data. The database record itself is always identified by record ID. The MIDI database in which it resides may be identified by name or by database ID. If you know the creator of the SMF, you can use the SndCreateMidiList utility function to retrieve this information. Alternatively, you can use the Data Manager record API functions to iterate through MIDI database records manually in search of this information.

The SndCreateMidiList utility function retrieves information about Standard Midi Files from one or more MIDI databases. This information is returned as a table of entries. Each entry contains the name of an SMF; its unique record ID; and the database ID and card number of the record database in which it resides.

Once you have the appropriate identifiers for the record and the database in which it resides, you need to open the MIDI database. If you have identified the database by type and creator, pass the sysFileTMidi type and an appropriate creator value to the DmOpenDatabaseByTypeCreator function. For example, to retrieve a SMF from the system MIDI database, pass type sysFileTMidi and creator sysFileCSystem. The DmOpenDatabaseByTypeCreator function returns a reference to the open database.

If you have identified the database by name, rather than by creator, you'll need to discover its database ID in order to open it. The DmFindDatabase function returns the database ID for a database specified by name and card number. You can pass the returned ID to the DmOpenDatabase function to open the database and obtain a reference to it.

Once you have opened the MIDI database, call DmFindRecordByID to get the index of the SMF record. To retrieve the record itself, pass this index value to either of the functions DmQueryRecord or DmGetRecord. When you intend to modify the record, use the DmGetRecord function--it marks the record as busy. When you intend to use the record in read-only fashion, use the DmQueryRecord function --it does not mark the record as busy. You must lock the handle returned by either of these functions before making further use of it.

To lock the database record's handle, pass it to the MemHandleLock function, which returns a pointer to the locked record holding the SMF data. You can pass this pointer to the SndPlaySmf function in the smfP parameter to play the MIDI file.

When you've finished using the record, unlock the pointer to it by calling the MemPtrUnlock function. If you've used DmGetRecord to open the record for editing, you must call DmReleaseRecord to make the record available once again to other callers. If you used DmQueryRecord to open the record for read-only use, you need not call DmReleaseRecord.

Finally, close the database by calling the DmCloseDatabase function.

Sound Preferences Compatibility Information

The sound preferences implementation and API varies slightly among versions 1.0, 2.0, and 3.X of Palm OS. This section describes how to use sound preferences correctly for various versions of Palm OS.

Because versions 2.0 and 3.X of Palm OS provide backward compatibility with previous sound preference mechanisms, applications written for an earlier version of the sound preferences API will get correct sound preference information from newer versions of Palm OS. However, it is strongly recommended that new applications use the latest API.

Using Sound Preferences on All Palm OS Devices

Because the user chooses sound preference settings, your application should respect them and adhere to their values. Further, you should always treat sound preferences as read-only values.

At reset time, the sound manager reads stored preference values and caches them for use at run time. The user interface controls update both the stored preference values and the sound manager's cached values.

The PrefSetPreference function writes to stored preference values without affecting cached values. New values are read at the next system reset. The system-use-only SndSetDefaultVolume function updates cached values but not stored preferences. Applications should avoid modifying stored preferences or cached values in favor of respecting the user's choices for preferences.

Using Palm OS 1.0 Sound Preferences

To read sound preference values in version 1.0 of Palm OS, call the PrefGetPreferences function to obtain the data structure shown in Listing 8.7. This SystemPreferencesTypeV10 structure holds the current values of all system-wide preferences. You must extract from this structure the values of the sysSoundLevel and alarmSoundLevel fields. These values are the only sound preference information that Palm OS version 1.0 provides.

Each of these fields holds a value of either slOn (on) or slOff (off). Your code must interpret the values read from these fields as an indication of whether those volumes should be on or off, then map them to appropriate amplitude values to pass to Sound Manager functions: map the slOn selector to the sndMaxAmp constant (defined in SoundMgr.h) and map the slOff selector to the value 0 (zero).

Listing 8.7 SystemPreferencesTypeV10 data structure

Using Palm OS 2.0 Sound Preferences

Version 2.0 of Palm OS introduces a new API for retrieving individual preference values from the system. You can pass any of the selectors prefSysSoundLevelV20, prefGameSoundLevelV20, or prefAlarmSoundLevelV20 to the PrefGetPreference function to retrieve individual amplitude preference values for alarm sounds, game sounds, or for overall (system) sound amplitude. As in Palm OS 1.0, each of these settings holds values of either slOn (on) or slOff (off), as defined in the Preferences.h file. Your code must interpret the values read from these fields as an indication of whether those volumes should be on or off, then map them to appropriate amplitude values to pass to Sound Manager functions: map the slOn selector to the sndMaxAmp constant (defined in SoundMgr.h file) and map the slOff selector to the value 0 (zero).

For a complete listing of selectors you can pass to the PrefGetPreference function, see the Preferences.h file.

Using Palm OS 3.X Sound Preferences

Palm OS version 3.X enhances the resolution of sound preference settings by providing discrete amplitude levels for games, alarms, and the system overall. As usual, do not set preferences yourself, but treat them as read-only values indicating the proper volume level for your application to use.

Palm OS 3.X defines the new sound amplitude selectors prefSysSoundVolume, prefGameSoundVolume, and prefAlarmSoundVolume for use with the PrefGetPreference function. The values this function returns for these selectors are actual amplitude settings that may be passed directly to Sound Manager functions.

---

NOTE:  

The amplitude selectors used in previous versions of Palm OS (all ending with the Level suffix, such as prefGameSoundLevel) are obsoleted in version 3.0 of Palm OS and replaced by new selectors. The old selectors remain available in Palm OS 3.X to ensure backward compatibility and are suffixed V20 (for example, prefGameSoundLevelV20).

---

Ensuring Sound Preferences Compatibility

For greatest compatibility with multiple versions of the sound preferences mechanism, your application should condition its sound preference code according to the version of Palm OS on which it is running. See "The System Version Feature" for more information.

When your application is launched, it should retrieve the system version number and save the results in its global variables (or equivalent structure) for use elsewhere. If the major version number is 3 (three) or greater, then use the 3.0 mechanism for obtaining sound amplitude preferences, since this reflects the user's selection most accurately. If the major version number is 2 (two), then use the 2.0 mechanism described in "Using Palm OS 2.0 Sound Preferences." If it is 1 (one), then use the 1.0 mechanism described in "Using Palm OS 1.0 Sound Preferences."

Avoid calling new APIs (including new selectors) when running on older versions of Palm OS that do not implement them. In particular, note that violating any of the following conditions will cause your application to crash:

• Do not call either of the SndPlaySmf or SndCreateMidiList functions on versions of Palm OS prior to 3.0.
  
  
• Do not pass any selector other than sndCmdFreqDurationAmp to the SndDoCmd function on versions of Palm OS prior to 3.0.
  

System Boot and Reset

Any reset is normally performed by sticking a bent-open paper clip or a large embroidery needle into the small hole in the back of the device. This hole, known as the "reset switch" is above and to the right of the serial number sticker (on Palm III devices). Depending on additional keys held down, the reset behavior varies, as follows:

Soft Reset

A soft reset clears all of the dynamic heap (Heap 0, Card 0). The storage heaps remain untouched. The operating system restarts from scratch with a new stack, new global variables, restarted drivers, and a reset communication port. All applications on the device receive a sysAppLaunchCmdSystemReset launch code.

Soft Reset + Up Arrow

Holding the up-arrow down while pressing the reset switch with a paper clip causes the same soft reset logic with the following two exceptions:

• The sysAppLaunchCmdSystemReset launch code is not sent to applications. This is useful if there is an application on the device that crashes upon receiving this launch code (not uncommon) and therefore prevents the system from booting.
  
  
• The OS won't load any system patches during startup. This is useful if you have to delete or replace a system patch database. If the system patches are loaded and therefore open, they cannot be replaced or deleted from the system.
  

Hard Reset

A hard reset is performed by pressing the reset switch with a paper clip while holding down the power key. This has all the effects of the soft reset. In addition, the storage heaps are erased. As a result, all programs, data, patches, user information, etc. are lost. A confirmation message is displayed asking the user to confirm the deletion of all data.

The sysAppLaunchCmdSystemReset launch code is sent to the applications at this time. If the user selected the "Delete all data" option, the digitizer calibration screen comes up first. The default databases for the four main applications is copied out of the ROM.

If you hold down the up arrow key when the "Delete all data" message is displayed, and then press the other four application buttons while still holding the up arrow key, the system is booted without reading the default databases for the four main applications out of ROM.

System Reset Calls

The system manager provides support for booting the Palm OS device. It calls SysReset to reset the device. This call does a soft reset and has the same effect as pressing the reset switch on the unit. Normally applications should not use this call.

SysReset is used, for example, by the Sync application. When the user copies an extension onto the Palm OS device, the Sync application automatically resets the device after the sync is completed to allow the extension to install itself.

The SysColdBoot call is similar, but even more dangerous. It performs a hard reset that clears all user storage RAM on the device, destroying all user data.

Hardware Interaction

Palm OS differs from a traditional desktop system in that it's never really turned off. Power is constantly supplied to essential subsystems and the on/off key is merely a way of bringing the device in or out of low-power mode. The obvious effect of pressing the on/off key is that the LCD turns on or off. When the user presses the power key to turn the device off, the LCD is disabled, which makes it appear as if power to the entire unit is turned off. In fact, the memory system, real-time clock, and the interrupt generation circuitry are still running, though they are consuming little current.

This section looks at Palm OS power management, discussing the following topics:

• Palm OS Power Modes
  
  
• Guidelines for Application Developers
  
  
• Power Management Calls
  

Palm OS Power Modes

To minimize power consumption, the operating system dynamically switches between three different modes of operation: sleep mode, doze mode, and running mode. The system manager controls transitions between different power modes and provides an API for controlling some aspects of the power management.

• In sleep mode, the device looks like it's turned off: the display is blank, the digitizer is inactive, and the main clock is stopped. The only circuits still active are the real-time clock and interrupt generation circuitry.
  

  The device enters this mode when there is no user activity for a number of minutes or when the user presses the off button. The device comes out of sleep mode only when there is an interrupt, for example, when the user presses a button.

  To enter sleep mode, the system puts as many peripherals as possible into low-power mode and sets up the hardware so that an interrupt from any hard key or the real-time clock wakes up the system. When the system gets one of these interrupts while in sleep mode, it quickly checks that the battery is strong enough to complete the wake-up and then takes each of the peripherals, for example, the LCD, serial port, and timers, out of low-power mode.

  
  
• In doze mode, the main clock is running, the device appears to be turned on, the LCD is on, and the processor's clock is running but it's not executing instructions (that is, it's halted). When the processor receives an interrupt, it comes out of halt and starts processing the interrupt.
  

  The device enters this mode whenever it's on but has no user input to process.

  The system can come out of doze mode much faster than it can come out of sleep mode since none of the peripherals need to be woken up. In fact, it takes no longer to come out of doze mode than to process an interrupt. Usually, when the system appears on, it is actually in doze mode and goes into running mode only for short periods of time to process an interrupt or respond to user input like a pen tap or key press.

  
  
• In running mode, the processor is actually executing instructions.
  

  The device enters this mode when it detects user input (like a tap on the screen) while in doze mode or when it detects an interrupt while in doze or sleep mode. The device stays in running mode only as long as it takes to process the user input (most likely less than a second), then it immediately reenters doze mode. A typical application puts the system into running mode only about 5% of the time.

To maximize battery life, the processor on the Palm Computing platform device is kept out of running mode as much as possible. Any interrupt generated on the device must therefore be capable of "waking" up the processor. The processor can receive interrupts from the serial port, the hard buttons on the case, the button on the cradle, the programmable timer, the memory module slot, the real-time clock (for alarms), the low-battery detector, and any built-in peripherals such as a pager or modem.

Guidelines for Application Developers

Normally, applications don't need to be aware of power management except for a few simple guidelines. When an application calls EvtGetEvent to ask the system for the next event to process, the system automatically puts itself into doze mode until there is an event to process. As long as an application uses EvtGetEvent, power management occurs automatically. If there has been no user input for the amount of time determined by the current setting of the auto-off preference, the system automatically enters sleep mode without intervention from the application.

Applications should avoid providing their own delay loops. Instead, they should use SysTaskDelay, which puts the system into doze mode during the delay to conserve as much power as possible. If an application needs to perform periodic work, it can pass a time out to EvtGetEvent; this forces the unit to wake up out of doze mode and to return to the application when the time out expires, even if there is no event to process. Using these mechanisms provides the longest possible battery life.

Power Management Calls

The system calls SysSleep to put itself immediately into low-power sleep mode. Normally, the system puts itself to sleep when there has been no user activity for the minimum auto-off time or when the user presses the power key.

The SysSetAutoOffTime routine changes the auto-off time value. This routine is normally used by the system only during boot, and by the Preferences application. The Preferences application saves the user preference for the auto-off time in a preferences database, and the system initializes the auto-off time to the value saved in the preferences database during boot. While the auto-off feature can be disabled entirely by calling SysSetAutoOffTime with a time-out of 0, doing this depletes the battery.

The current battery level and other information can be obtained through the SysBatteryInfo routine. This call returns information about the battery, including the current battery voltage in hundredths of a volt, the warning thresholds for the low-battery alerts, the battery type, and whether external power is applied to the unit. This call can also change the battery warning thresholds and battery type.

The Microkernel

Palm OS has a preemptive multitasking kernel that provides basic task management.

Most applications don't need the microkernel services because they are handled automatically by the system. This functionality is provided mainly for internal use by the system software or for certain special purpose applications.

In this version of the Palm OS, there is only one user interface application running at a time. The User Interface Application Shell (UIAS) is responsible for managing the current user-interface application. The UIAS launches the current user-interface application as a subroutine and doesn't get control back until that application quits. When control returns to the UIAS, the UIAS immediately launches the next application as another subroutine. See "Power Management Calls" for more information.

Usually, the UIAS is the only task running. Occasionally though, an application launches another task as a part of its normal operation. One example of this is the Sync application, which launches a second task to handle the serial communication with the desktop. The Sync application creates a second task dedicated to the serial communication and gives this task a lower priority than the main user-interface task. The result is optimal performance over the serial port without a delay in response to the user-interface controls.

Normally, there is no user interaction during a sync, so that the serial communication task gets all of the processor's time. However, if the user does tap on the screen, for example, to cancel the sync, the user-interface task immediately processes the tap, since it has a higher priority. Alternatively, the Sync application could have been written to use just one task, but then it would have to periodically poll for user input during the serial communication, which would hamper performance and user-interface response time.

---

NOTE:  

Only system software can launch a separate task. The multi-tasking API is not available to developer applications.

---

Retrieving the ROM Serial Number

Some Palm devices, beginning with the Palm III product, hold a 12-digit serial number that identifies the device uniquely. (Earlier devices do not have this identifier.) The serial number is held in a displayable text buffer with no null terminator. The user can view the serial number in the Application Launcher application. (The pop-up version of the Launcher does not display the serial number.) The Application Launcher also displays to the user a checksum digit that you can use to validate user entry of the serial number.

To retrieve the ROM serial number programmatically, pass the sysROMTokenSnum selector to the SysGetROMToken function. If the SysGetROMToken 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.

The DrawSerialNumOrMessage function shown in Listing 8.8 retrieves the ROM serial number, calculates the checksum, and draws both on the screen at a specified location. If the device has no serial number, this function draws a message you specify. This function accepts as its input a pair of coordinates at which it draws output, and a pointer to the message it draws when a serial number is not available.

Listing 8.8 DrawSerialNumOrMessage

Time

The Palm Computing platform device has a real-time clock and programmable timer as part of the 68328 processor. The real-time clock maintains the current time even when the system is in sleep mode (turned off). It's capable of generating an interrupt to wake the device when an alarm is set by the user. The programmable timer is used to generate the system tick count interrupts (100 times/second) while the processor is in doze or running mode. The system tick interrupts are required for periodic activity such as polling the digitizer for user input, key debouncing, etc.

The date and time manager (called time manager in this chapter) provides access to both the 1-second and 0.01-second timing resources on the Palm OS device.

• The 1-second timer keeps track of the real-time clock (date and time), even when the unit is in sleep mode.
  
  
• The 0.01-second timer, also referred to as the system ticks, can be used for finer timing tasks. This timer is not updated when the unit is in sleep mode and is reset to 0 each time the unit resets.
  

The basic time-manager API provides support for setting and getting the real-time clock in seconds and for getting the current system ticks value (but not for setting it). The system manager provides more advanced functionality for setting up a timer task that executes periodically or in a given number of system ticks.

This section discusses the following topics:

• Using Real-Time Clock Functions
  
  
• Using System Ticks Functions
  

Using Real-Time Clock Functions

The real-time clock functions of the time manager include TimSetSeconds and TimGetSeconds. Real time on the Palm OS device is measured in seconds from midnight, Jan. 1, 1904. Call TimSecondsToDateTime and TimDateTimeToSeconds to convert between seconds and a structure specifying year, month, day, hour, minute, and second.

Using System Ticks Functions

The Palm OS device maintains a tick count that starts at 0 when the device is reset. This tick increments

• 100 times per second when running on the Palm OS device
  
  
• 60 times per second when running on the Macintosh under the Simulator
  

For tick-based timing purposes, applications should use the macro SysTicksPerSecond, which is conditionally compiled for different platforms. Use the function TimGetTicks to read the current tick count.

Although the TimGetTicks function could be used in a loop to implement a delay, it is recommended that applications use the SysTaskDelay function instead. The SysTaskDelay function automatically puts the unit into low-power mode during the delay. Using TimGetTicks in a loop consumes much more current.

Floating-Point

Palm OS 1.0 provided 16-bit floating point arithmetic. Instead of using standard mathematical symbols, you called functions like FplAdd, FplSub, and so on.

Palm OS 2.0 and later implements floating point arithmetic differently than Palm OS 1.0 did. The floating-point library in OS versions 2.0 and later provides 32-bit and 64-bit floating point arithmetic.

Using Floating Point Arithmetic

To take advantage of the floating-point library, applications can now use the mathematical symbols + - * /instead of using functions like FplAdd, FplSub, etc.

When compiling the application, you have to link in the floating point library under certain circumstances. Choose from one of these options:

• Simulator application or application for 1.0 device -- link in the floating point library explicitly.
  

  This library adds approximately 8KB to the size of your prc file. The library provides 32-bit and 64-bit floating-point arithmetic. The original Palm OS Fpl functions provided only 16-bit floating-point arithmetic. Linking in the library explicitly won't cause problems when you compile for a 2.0 or later device.

  
  
• 2.0 or later Palm OS device--It's not necessary to link in the library.
  

  The compiler generates trap calls to equivalent floating-point functionality in the system ROM.

There are control panel settings in the IDE which let you select the appropriate floating-point model.

Floating-point functionality is identical in either method.

Using 1.0 Floating-Point Functionality

The original Fpl calls (documented in the chapter "Float Manager" in the Palm OS SDK Reference) are still available. They may be useful for applications that don't need high precision, don't want to incur the size penalty of the float library, and want to run on 1.0 devices only. To get 1.0 behavior, use the 1.0 calls (FplAdd, etc.) and don't link in the library.

Summary of System Features