Palm OS Programming, 2nd Edition

The Palm OS and an Application

When the Palm OS wants to communicate with an application that may not be running, it calls the application’s

PilotMain

routine.

The Main Routine: PilotMain

This is the main entry point into a Palm OS application; it is always a function named PilotMain . Given its responsibilities, it is worth looking at this routine in some detail. First, we’ll start with the parameters, and then we’ll show you the code. Following the code is a walk-through discussion of what is happening.

A quick look at PilotMain

The first parameter is the launch code, which specifies why the function is being called. Whenever your application is being opened normally, this parameter will be the constant sysAppLaunchCmdNormalLaunch. The second and third parameters are used when the application is opened at other times (see Example 5-1).

Example 5-1. Typical PilotMain (app-specific portions are emphasized)

UInt32 PilotMain(UInt16 launchCode, MemPtr launchParameters, 
  UInt16 launchFlags)
{
#pragma unused(launchParameters)
  Err error;

  switch (launchCode) {
  case sysAppLaunchCmdNormalLaunch:
    error = RomVersionCompatible(kOurMinVersion, launchFlags);
    if (error != errNone) 
      return error;
    error = AppStart(  );
    if (error != errNone) 
      return error;
      
    FrmGotoForm(MainForm);
    AppEventLoop(  );
    AppStop(  );
    break;

  default:
    break;
  }
  
  return errNone;
}

If the launch code is sysAppLaunchCmdNormalLaunch, we first check to make sure that the version of the device we are running on is one that we support (you’ll ...