Print
O'Reilly Book Excerpts: Palm OS Programming, 2nd Edition

Structure of a Palm Application, Part 3

by Neil Rhodes and Julie McKeehan

Related Reading

Palm OS Programming
The Developer's Guide
By Neil Rhodes, Julie McKeehan

Editors Note: In this third and final excerpt from "Palm OS Programming, 2nd Edition," Neil Rhodes and Julie McKeehan discuss how the operating system communicates with an application when it's not running.

Other Times Your Application is Called

You know how an application works within the OS and now you know about the organizational structure and content of the various source files used to create an application. The last remaining piece of the puzzle is other times the OS communicates with an application. Let's turn to the details of this.

The Palm OS makes a distinction between communicating with the active application and communicating with a possibly nonactive application. In this first case, the active application is busy executing an event loop, and can be communicated with by posting events to the event queue. As shown earlier in our example, this was how our application got closed; the appStopEvent was posted to the event queue. When the active application gets that event, it quits.

Because there are other times that your application gets called by the Palm OS, there needs to be a way to communicate with it in those instances as well. First, let's look at a partial list of the circumstances under which the system might want to talk to your application:

  • When the user does a Find, the system must ask each installed application to look for any records that match the Find request.
  • When beamed data is received, the system must ask the appropriate application (the one that is registered to receive the data) to handle the incoming item.
  • When a HotSync occurs, each application is notified after its data has been synced.
  • After a reset, each application is notified that a reset has occurred.
  • If the system time or date changes, each application is notified.
  • If the country changes, each application is notified.

In all these cases, a communication must take place to a nonactive or closed application. The question is: how does the system do this? The answer: its PilotMain routine is called with different launch codes.

Launch Codes

Within the Palm OS, it is the launch code that specifies to the application which of the previously mentioned circumstances exists and what the application needs to do. These codes arrive at the application's PilotMain routine by way of its launchCode parameter. Here are some common launch codes:

sysAppLaunchCmdFind
This code tells the application to look up a particular text string and return information about any matching data. Called by the system when the user does a Find.

sysAppLaunchCmdGoTo
This code tells the application to open if it isn't already open and then to go to the specified piece of data. Called by the system when the user taps on a found item.

sysAppLaunchCmdNormalLaunch
As we have already seen, this code opens the application normally.

sysAppLaunchCmdSystemReset
Sent after a reset occurs.

TIP:   In the 4.0 OS and prior ones, some launch codes are sent to every installed application (for example, after a sync, a reset, or a time change). When a user has many applications installed, this broadcast can be slow. In the future, they may only be sent to those applications that have registered for that particular notification. This registration is available with a Palm OS 3.5 call SysNotifyRegister.

Launch Flags

In This Series

Structure of a Palm Application, Part 2
In this second excerpt from "Palm OS Programming, 2nd Edition," Neil Rhodes and Julie McKeehan build on the terminology and conventions they introduced in the first excerpt and walk us through a sample application. This is the second in a series of three excerpts designed to familiarize developers with the structure of Palm apps.

Structure of a Palm Application, Part 1
In this excerpt from "Palm OS Programming, 2nd Edition," Neil Rhodes and Julie McKeehan introduce the terminology and conventions of a Palm application. This is the first in a series of three excerpts designed to familiarize developers with the structure of Palm apps.

The launch flags specify important information about how the application is being executed. Here are some examples:

  • They may specify whether the application's global variables are available. For performance reasons, globals are not available on many launch codes (this can make the call to PilotMain very fast, as the app's global variables don't need to be allocated or initialized). If globals aren't available, it only makes sense that you can't read from or write to any global.
  • They may specify whether the application is now the active application.
  • They may specify whether it had already been open as the active application.
  • They may specify whether some other application is active.

Scenarios

To help clarify the relationship between the application and the times when the system calls it, let's look at examples of when this happens and the flow of code.

Normal launch

Your application gets a launch code of sysAppLaunchCmdNormalLaunch when it's opened, and launch flags of hexadecimal 0x8e, specifying the following, OR-ed together:

sysAppLaunchFlagDataRelocated
This is a private Palm OS flag.

sysAppLaunchFlagUIApp
The application should show a UI.

sysAppLaunchFlagNewGlobals
The application has just been allocated global variables.

sysAppLaunchFlagNewStack
The application has been allocated a new stack.

Find when another application is active

When the Memo Pad is the active application, and the user does a Find, the Find Manager calls the PilotMain of every installed application. When our application is called, the launch code is 1 (sysAppCmdFind), and the launch flag is 0 (no globals, no UI).

Find when your application is active

Things happen differently when we do a Find with our application already open. In this case, PilotMain is still called with the same launch code: sysAppLaunchCmdFind, but now the launch flag is different. It is 0x10 (sysAppLaunchFlagSubCall), specifying that the OReilly Starter application is already open and running. This means that global variables have been allocated and initialized, and we are running as an indirect subroutine call from the application.

Figure 5-4 shows the stack trace when the Find is done in this case. The stack trace shows that PilotMain is called (indirectly) from our AppEventLoop (which itself is called from our original PilotMain).

Figure 5-4.The stack trace when doing a Find from within our own application
 

Pages: 1, 2

Next Pagearrow