1 Application Launch Codes

This chapter provides detailed information about the predefined application launch codes. Launch codes are declared in the header file SystemMgr.h. The associated parameter blocks are declared in AppLaunchCmd.h, AlarmMgr.h, ExgMgr.h, and Find.h.

Table 1.1 lists all Palm OS^® standard launch codes. More detailed information is provided immediately after the table:

• Launch Codes
  
  
• Launch Flags
  

To learn what a launch code is and how to use it, see the chapter titled "Application Startup and Stop" in the Palm OS Programmer's Companion.

Table 1.1 Palm OS Launch Codes 

Code	Request
scptLaunchCmdExecuteCmd	Execute the specified Network login script plugin command.
scptLaunchCmdListCmds	Provide information about the commands that your Network script plugin executes.
sysAppLaunchCmdAddRecord	Add a record to a database.
sysAppLaunchCmdAlarmTriggered	Schedule next alarm or perform quick actions such as sounding alarm tones.
sysAppLaunchCmdCountryChange	Respond to country change.
sysAppLaunchCmdDisplayAlarm	Display specified alarm dialog or perform time-consuming alarm-related actions.
sysAppLaunchCmdExgAskUser	Let application override display of dialog asking user if they want to receive incoming data via the exchange manager.
sysAppLaunchCmdExgReceiveData	Notify application that it should receive incoming data via the exchange manager.
sysAppLaunchCmdFind	Find a text string.
sysAppLaunchCmdGoto	Go to a particular record, display it, and optionally select the specified text.
sysAppLaunchCmdGoToURL	Launch Clipper application and open a URL.
sysAppLaunchCmdInitDatabase	Initialize database.
sysAppLaunchCmdLookup	Look up data. In contrast to sysAppLaunchCmdFind, a level of indirection is implied. For example, look up a phone number associated with a name.
sysAppLaunchCmdNormalLaunch	Launch normally.
sysAppLaunchCmdNotify	Notify about an event.
sysAppLaunchCmdOpenDB	Launch application and open a database.
sysAppLaunchCmdPanelCalledFromApp	Tell preferences panel that it was invoked from an application, not the Preferences application.
sysAppLaunchCmdReturnFromPanel	Tell an application that it's restarting after preferences panel had been called.
sysAppLaunchCmdSaveData	Save data. Often sent before find operations.
sysAppLaunchCmdSyncNotify	Notify applications that a HotSync has been completed.
sysAppLaunchCmdSystemLock	Sent to the Security application to request that the system be locked down.
sysAppLaunchCmdSystemReset	Respond to system reset. No UI is allowed during this launch code.
sysAppLaunchCmdTimeChange	Respond to system time change.
sysAppLaunchCmdURLParams	Launch an application with parameters from Clipper.

Launch Codes

This section provides supplemental information about launch codes. For some launch codes, it lists the parameter block, which in some cases provides additional information about the launch code.

sysAppLaunchCmdAddRecord

Add a record to an application's database.

This launch code is used to add a message to the Mail or iMessenger^™ (on the Palm VII^™ organizer) application's outbox. You pass information about the message such as address, body text, etc. in the parameter block. For iMessenger, you can set the edit field of the parameter block to control whether or not the iMessenger editor is displayed. Set it to true to display the editor or false not to display it.

For more information on sending messages via iMessenger, see "Sending Messages" in the Palm OS Programmer's Companion.

---

IMPORTANT: Implemented for iMessenger only if Wireless Internet Feature Set is present. Implemented for Mail only on OS version 3.0 or later.

---

sysAppLaunchCmdAddRecord Parameter Block for Mail Application

Prototype

typedef enum {

    mailPriorityHigh,
    mailPriorityNormal,
    mailPriorityLow
} MailMsgPriorityType;

typedef struct {
    Boolean secret;
    Boolean signature;
    Boolean confirmRead;
    Boolean confirmDelivery;
    MailMsgPriorityType priority;
    UInt8 padding
    Char* subject;
    Char* from;
    Char* to;
    Char* cc;
    Char* bcc;
    Char* replyTo;
    Char* body;
} MailAddRecordParamsType;

Fields

secret

True means that the message should be marked secret.

signature

True means that the signature from the Mail application's preferences should be attached to the message.

confirmRead

True means that a confirmation should be sent when the message is read.

confirmDelivery

True means that a confirmation should be sent when the message is delivered.

priority

Message priority. Specify one of the MailMsgPriorityType enumerated types.

padding

Reserved for future use.

subject

Message's subject, a null-terminated string (optional).

from

Message's sender, a null-terminated string (not used on outgoing mail).

to

Address of the recipient, a null-terminated string (required).

cc

Addresses of recipients to be copied, a null-terminated string (optional).

bcc

Addresses of recipients to be blind copied, a null-terminated string (optional).

replyTo

Reply to address, a null-terminated string (optional).

body

The text of the message, a null-terminated string (required).

sysAppLaunchCmdAddRecord Parameter Block for iMessenger Application

Prototype

typedef struct {

    UInt16 category;
    Boolean edit;
    Boolean signature;
    Char *subject;
    Char *from;
    Char *to;
    Char *replyTo;
    Char *body;
} MsgAddRecordParamsType;

Fields

category

Category in which to place the message. Specify one of the following categories:

edit

True means that the message should be opened in the editor. False means that the message should simply be placed into the outbox and the editor not opened. You can specify true only if the category is set to MsgOutboxCategory.

signature

True means that the signature from the iMessenger application preferences should be attached to the message.

subject

Message's subject, a null-terminated string (optional).

from

Message's sender, a null-terminated string (not used on outgoing mail).

to

Address of the recipient, a null-terminated string (required).

replyTo

Reply to address, a null-terminated string (optional).

body

The text of the message, a null-terminated string (required).

sysAppLaunchCmdAlarmTriggered

Performs quick action such as scheduling next alarm or sounding alarm.

This launch code is sent as close to the actual alarm time as possible. An application may perform any quick, non-blocking action at this time. Multiple alarms may be pending at the same time for multiple applications, and one alarm display shouldn't block the system and prevent other applications from receiving their alarms in a timely fashion. An opportunity to perform more time-consuming actions will come when sysAppLaunchCmdDisplayAlarm is sent.

sysAppLaunchCmdAlarmTriggered Parameter Block

Prototype

typedef struct SysAlarmTriggeredParamType {

    UInt32 ref;
    UInt32 alarmSeconds;
    Boolean purgeAlarm;
    UInt8 padding;
} SysAlarmTriggeredParamType;

Fields

-> ref

The caller-defined value specified when the alarm was set with AlmSetAlarm.

-> alarmSeconds

The date/time specified when the alarm was set with AlmSetAlarm. The value is given as the number of seconds since 1/1/1904.

<- purgeAlarm

Upon return, set to true if the alarm should be removed from the alarm table. Use this as an optimization to prevent the application from receiving sysAppLaunchCmdDisplayAlarm if you don't wish to perform any other processing for this alarm. If you do want to receive the launch code, set this field to false.

padding

Not used.

sysAppLaunchCmdCountryChange

Responds to country change.

Applications should change the display of numbers to use the proper number separators. To do this, call LocGetNumberSeparators, StrLocalizeNumber, and StrDelocalizeNumber.

sysAppLaunchCmdDisplayAlarm

Performs full, possibly blocking, handling of alarm.

This is the application's opportunity to handle an alarm in a lengthy or blocking fashion. Notification dialogs are usually displayed when this launch code is received. This work should be done here, not when sysAppLaunchCmdAlarmTriggered is received. Multiple alarms may be pending at the same time for multiple applications, and one alarm display shouldn't block the system and prevent other applications from receiving their alarms in a timely fashion.

sysAppLaunchCmdDisplayAlarm Parameter Block

Prototype

typedef struct SysDisplayAlarmParamType {
    UInt32 ref;
    UInt32 alarmSeconds;
    Boolean soundAlarm;
    UInt8 padding;
    } SysDisplayAlarmParamType;

Fields

-> ref

The caller-defined value specified when the alarm was set with AlmSetAlarm.

-> alarmSeconds

The date/time specified when the alarm was set with AlmSetAlarm. The value is given as the number of seconds since 1/1/1904.

-> soundAlarm

true if the alarm should be sounded, false otherwise. This value is currently not used.

padding

Not used.

sysAppLaunchCmdExgAskUser

Exchange manager sends this launch code to the application when data has arrived for that application. This launch code lets the application tell the exchange manager whether or not to display a dialog asking the user if they want to accept the data. If the application chooses not to handle this launch code, the default course of action is that the exchange manager displays a dialog asking the user if they want to accept the incoming data.

Prior to Palm OS release 3.5, most applications didn't need to handle this launch code, since the default action was the preferred alternative. On Palm OS 3.5, you can have the dialog display a category pop-up list from which the user can choose a category in which to file the incoming data. To do so, you must handle sysAppLaunchCmdExgAskUser to call the ExgDoDialog function. See the description of that function for more information. If you don't handle the launch code, the exchange manager displays the dialog without the category pop-up list.

If an application responds to this launch code, it must set the result field in the parameter to the appropriate value. Possible values are:

exgAskDialog

Display the dialog without the category pop-up list (the default).

exgAskOk

Accept the incoming data.

exgAskCancel

Reject the incoming data.

For example, if your entire response to this launch code is to set the result field to exgAskCancel, your application always rejects all incoming data without displaying the dialog. If it is to set the result field to exgAskOk, it always accepts all incoming data without displaying the dialog.

On Palm OS 3.5 or higher if you are calling ExgDoDialog in your handler, return exgAskOk if ExgDoDialog was successful, or exgAskCancel if it failed. If you don't set the result field on Palm OS 3.5, the dialog is displayed twice.

If the application sets the result field to exgAskOk, or the dialog is displayed and the user presses the OK button, then the exchange manager sends the application the next launch code, sysAppLaunchCmdExgReceiveData, so that it can actually receive the data.

---

IMPORTANT: Implemented only if 3.0 New Feature Set is present.

---

sysAppLaunchCmdExgAskUser Parameter Block

Prototype

typedef struct {

    ExgSocketPtr socketP;
    ExgAskResultType result;
    UInt8 reserved;
    } ExgAskParamType;

Fields

<-> socketP

Socket pointer

<- result

Show dialog, auto-confirm, or auto-cancel

-> reserved

Reserved for future use

sysAppLaunchCmdExgReceiveData

Following the launch code sysAppLaunchCmdExgAskUser, the exchange manager sends this launch code to the application to notify it that it should receive the data (assuming that the application and/or the user has indicated the data should be received).

The application should use exchange manager functions to receive the data and store it or do whatever it needs to with the data.

Note that the application may not be the active application, and thus may not have globals available when it is launched with this launch code. You can check if you have globals by using this code in the PilotMain routine:

The appIsActive value will be true if your application is active and globals are available; otherwise, you won't be able to access any of your global variables during the receive operation.

The parameter block sent with this launch code is of the ExgSocketPtr data type. It is a pointer to the ExgSocketType structure corresponding to the exchange manager connection via which the data is arriving. You will need to pass this pointer to the ExgAccept function to begin receiving the data. For more details, refer to the "Exchange Manager" chapter.

---

IMPORTANT: Implemented only if 3.0 New Feature Set is present.

---

sysAppLaunchCmdFind

This launch command is used to implement the global find. It is sent by the system whenever the user enters a text string in a Find dialog. At that time, the system queries each application whether it handles this launch code and returns any records matching the find request.

The system sends this launch code with the FindParamsType parameter block to each application. The system displays the results of the query in the Find dialog.

Most applications that use text records should support this launch code. When they receive it, they should search all records for matches to the find string and return all matches.

An application can also integrate the find operation in its own user interface and send the launch code to a particular application.

Applications that support this launch code should support sysAppLaunchCmdSaveData and sysAppLaunchCmdGoto as well.

sysAppLaunchCmdFind Parameter Block

Prototype

typedef struct {

// These fields are used by the applications.
    UInt16 dbAccesMode;
    UInt16 recordNum;
    Boolean more;
    Char strAsTyped [maxFindStrLen+1];
    Char strToFind [maxFindStrLen+1];
// These fields are private to the Find routine
//and should NOT be accessed by applications.
    UInt8 reserved1;
    UInt16 numMatches;
    UInt16 lineNumber;
    Boolean continuation;
    Boolean searchedCaller;
    LocalID callerAppDbID;
    UInt16 callerAppCardNo;
    LocalID appDbID;
    UInt16 appCardNo;
    Boolean newSearch;
    UInt8 reserved2;
    DmSearchStateType searchState;
    FindMatchType match [maxFinds];
} FindParamsType;

Fields

dbAccesMode

Read mode. May be "show secret."

recordNum

Index of last record that contained a match.

more

true if more matches to display.

strAsTyped [maxFindStrLen+1]

Search string as entered.

strToFind [maxFindStrLen+1]

Search string in lower case.

reserved1

Reserved for future use.

numMatches

System use only.

lineNumber

System use only.

continuation

System use only.

searchedCaller

System use only.

callerAppDbID

System use only.

callerAppCardNo

System use only.

appDbID

System use only.

appCardNo

System use only.

newSearch

System use only.

reserved2

Reserved for future use.

searchState

System use only.

match [maxFinds]

System use only.

sysAppLaunchCmdGoto

Sent in conjunction with sysAppLaunchCmdFind or sysAppLaunchCmdExgReceiveData to allow users to actually inspect the record that the global find returned or that was received by the exchange manager.

Applications should do most of the normal launch actions, then display the requested item. The application should continue running unless explicitly closed.

An application launched with this code does have access to global variables, static local variables, and code segments other than segment 0 (in multi-segment applications).

sysAppLaunchCmdGoto Parameter Block

Prototype

typedef struct {

    Int16 searchStrLen;
    UInt16 dbCardNo;
    LocalID dbID;
    UInt16 recordNum;
    UInt16 matchPos;
    UInt16 matchFieldNum;
    UInt32 matchCustom;
    } GoToParamsType;

Fields

searchStrLen

Length of search string.

dbCardNo

Card number of the database.

dbID

Local ID of the database.

recordNum

Index of record containing a match.

matchPos

Position of the match.

matchFieldNum

Field number string was found in.

matchCustom

Application-specific information.

sysAppLaunchCmdGoToURL

You can send this launch code to the Clipper application to launch the application and cause it to retrieve and display the specified URL.

The parameter block for this launch command is simply a pointer to a string containing the URL.

For more information and an example of how to use this launch code, see "Using Clipper to Display Information" in the Palm OS Programmer's Companion.

---

IMPORTANT: Implemented only if Wireless Internet Feature Set is present.

---

sysAppLaunchCmdInitDatabase

This launch code is sent by the Desktop Link server in response to a request to create a database. It is sent to the application whose creator ID matches that of the requested database.

The most frequent occurrence of this is when a 'data' database is being installed or restored from the desktop. In this case, HotSync^® creates a new database on the device and passes it to the application via a sysAppLaunchCmdInitDatabase command, so that the application can perform any required initialization. HotSync will then transfer the records from the desktop database to the device database.

When a Palm OS application crashes while a database is installed using HotSync, the reason may be that the application is not handling the sysAppLaunchCmdInitDatabase command properly. Be especially careful not to access global variables.

The system will create a database and pass it to the application for initialization. The application must perform any initialization required, then pass the database back to the system, unclosed.

sysAppLaunchCmdInitDatabase Parameter Block

Prototype

typedef struct {

    DmOpenRef dbP;
    UInt32 creator;
    UInt32 type;
    UInt16 version;
} SysAppLaunchCmdInitDatabaseType;

Fields

dbP

Database reference.

creator

Database creator.

type

Database type.

version

Database version.

sysAppLaunchCmdLookup

The system or an application sends this launch command to retrieve information from another application. In contrast to Find, there is a level of indirection; for example, this launch code could be used to retrieve the phone number based on input of a name.

This functionality is currently supported by the standard Palm OS Address Book.

Applications that decide to handle this launch code must search their database for the string the user entered and perform the match operation specified in the launch code's parameter block.

If an application wants to allow its users to perform lookup in other applications, it has to send it properly, including all information necessary to perform the match. An example for this is in Address.c and AppLaunchCmd.h, which are included in your SDK.

sysAppLaunchCmdLookup Parameter Block

The parameter block is defined by the application that supports this launch code. See AppLaunchCmd.h for an example.

---

IMPORTANT: Implemented only if 2.0 New Feature Set is present.

---

sysAppLaunchCmdNotify

The system or an application sends this launch code to notify applications that an event has occurred. The parameter block specifies the type of event that occurred, as well as other pertinent information. To learn which notifications are broadcast by the system, see "Notification Manager Event Constants" in the "Notification Manager" chapter.

---

IMPORTANT: Implemented only if Notification Feature Set is present.

---

sysAppLaunchCmdNotify Parameter Block

The SysNotifyParamType structure declared in NotifyMgr.h defines the format of this launch code's parameter block. See its description in the "Notification Manager" chapter.

sysAppLaunchCmdOpenDB

You can send this launch code to the Clipper application to launch the application and cause it to open and display a Palm query application stored on the device. This is the same mechanism that the Launcher uses to launch query applications.

---

IMPORTANT: Implemented only if Wireless Internet Feature Set is present.

---

sysAppLaunchCmdOpenDB Parameter Block

Prototype

typedef struct {

    UInt16 cardNo;
    LocalID dbID;
    } SysAppLaunchCmdOpenDBType;

Fields

cardNo

Card number of database to open.

dbID

Database id of database to open.

sysAppLaunchCmdPanelCalledFromApp

sysAppLaunchCmdPanelCalledFromApp and sysAppLaunchCmdReturnFromPanel allow an application to let users change preferences without switching to the Preferences application. For example, for the calculator, you may launch the Formats preferences panel, set up a number format preference, then directly return to the calculator that then uses the new format.

sysAppLaunchCmdPanelCalledFromApp lets a preferences panel know whether it was switched to from the Preferences application or whether an application invoked it to make a change. The panel may be a preference panel owned by the application or a system preferences panel.

Examples of these system panels that may handle this launch code are:

• Network panel (called from network applications)
  
  
• Modem panel (called if modem selection is necessary)
  

All preferences panels must handle this launch code. If a panel is launched with this command, it should:

• Display a Done button.
  
  
• Not display the panel-switching pop-up trigger used for navigation within the preferences application.
  

  
  

  ---

  
  IMPORTANT: Implemented only if 2.0 New Feature Set is present.
  

  ---

  
  

sysAppLaunchCmdReturnFromPanel

This launch code is used in conjunction with sysAppLaunchCmdPanelCalledFromApp. It informs an application that the user is done with a called preferences panel. The system passes this launch code to the application when a previously-called preferences panel exists.

---

IMPORTANT: Implemented only if 2.0 New Feature Set is present.

---

sysAppLaunchCmdSaveData

Instructs the application to save all current data. For example, before the system performs a Find operation, an application should save all data.

Any application that supports the Find command and that can have buffered data should support this launch code. Generally, an application only has to respond if it's the currently running application. In that case, all buffered data should be saved when the launch code is received.

sysAppLaunchCmdSaveData Parameter Block

Prototype

typedef struct {

    Boolean uiComing;
    UInt8 reserved1;
} SysAppLaunchCmdSaveDataType;

Fields

uiComing

true if system dialog is displayed before launch code arrives.

reserved1

Reserved for future use.

sysAppLaunchCmdSyncNotify

This launch code is sent to applications to inform them that a HotSync operation has occurred.

This launch code is sent only to applications whose databases were changed during the HotSync operation. (Installing the application database itself is considered a change.) The record database(s) must have the same creator ID as the application in order for the system to know which application to send the launch code to.

This launch code provides a good opportunity to update, initialize, or validate the application's new data, such as resorting records, setting alarms, and so on.

Because applications only receive sysAppLaunchCmdSyncNotify when their databases are updated, this launch code is not a good place to perform any operation that must occur after every HotSync operation. Instead, you may register to receive the sysNotifySyncFinishEvent on systems that have the Notification Feature Set. This notification is sent at the end of a HotSync operation, and it is sent to all applications registered to receive it, whether the application's data changed or not. Note that there is also a sysNotifySyncStartEvent notification.

sysAppLaunchCmdSystemLock

Launch code sent to the system-internal security application to lock the device.

As a rule, applications don't need to do respond to this launch code. If an application replaces the system-internal security application, it must handle this launch code.

---

IMPORTANT: Implemented only if 2.0 New Feature Set is present.

---

sysAppLaunchCmdSystemReset

Launch code to respond to system soft or hard reset.

Applications can respond to this launch code by performing initialization, indexing, or other setup that they need to do when the system is reset. For more information about resetting the device, see "System Boot and Reset" in the Palm OS Programmer's Companion.

sysAppLaunchCmdSystemReset Parameter Block

Prototype

typedef struct {
    Boolean hardReset;
    Boolean createDefaultDB;
} SysAppLaunchCmdSystemResetType;

Fields

hardReset

true if system was hardReset. false if system was softReset.

createDefaultDB

If true, application has to create default database.

sysAppLaunchCmdTimeChange

Launch code to respond to a time change initiated by the user.

Applications that are dependent on the current time or date need to respond to this launch code. For example, an application that sets alarms may want to cancel an alarm or set a different one if the system time changes.

On systems that have the Notification Feature Set, applications should register to receive the sysNotifyTimeChangeEvent notification instead of responding to this launch code. The sysAppLaunchCmdTimeChange launch code is sent to all applications. The sysNotifyTimeChangeEvent notification is sent only to applications that have specifically registered to receive it, making it more efficient than sysAppLaunchCmdTimeChange.

sysAppLaunchCmdURLParams

This launch code is sent from the Clipper application to launch another application.

The parameter block consists of a pointer to a special URL string, which the application must know how to parse. The string is the URL used to launch the application and may contain encoded parameters. For more information, see "Launching Other Applications from Clipper" in the Palm OS Programmer's Companion.

An application launched with this code may or may not have access to global variables, static local variables, and code segments other than segment 0 (in multi-segment applications). It depends on the URL that caused Clipper to send this launch code. If this launch code results from a palm URL, then globals are available. If the launch code results from a palmcall URL, then globals are not available.

The best way to test if you have global variable access is to test the sysAppLaunchFlagNewGlobals launch flag sent with this launch code. If this is flag is set, then you have global variable access.

---

IMPORTANT: Implemented only if Wireless Internet Feature Set is present.

---

Launch Flags

When an application is launched with any launch command, it also is passed a set of launch flags.

An application may decide not to handle the flags even if it handles the launch code itself. For applications that decide to include this launch code, the following table provides additional information:

Table 1.2 Launch Flags

Flag	Functionality
sysAppLaunchFlagNewThread	Creates a new thread for the application. Implies sysAppLaunchFlagNewStack.
sysAppLaunchFlagNewStack	Creates a separate stack for the application.
sysAppLaunchFlagNewGlobals	Creates and initializes a new globals world for the application. Implies new owner ID for memory chunks.
sysAppLaunchFlagUIApp	Notifies launch routine that this is a UI application being launched.
sysAppLaunchFlagSubCall	Notifies launch routine that the application is calling its entry point as a subroutine call. This tells the launch code that it's OK to keep the A5 (globals) pointer valid through the call. If this flag is set, it indicates that the application is already running as the current application.

Generally, the system sends launch flags along with all launch codes. Applications should just pass 0 (zero) when sending a launch code to another application.