(68K) Application Launch Codes | Palm OS® Programmer's API Reference

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:

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, vol. I.

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.
`sysAppLaunchCmdAttention`	Perform the action requested by the attention manager.
`sysAppLaunchCmdCardLaunch`	Launch the application. This launch code signifies that the application is being launched from an expansion card.
`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.
`sysAppLaunchCmdExgGetData`	Notify application that it should send data using the Exchange Manager.
`sysAppLaunchCmdExgPreview`	Notify application that it should display a preview using the Exchange Manager.
`sysAppLaunchCmdExgReceiveData`	Notify application that it should receive incoming data using the Exchange Manager.
`sysAppLaunchCmdFind`	Find a text string.
`sysAppLaunchCmdGoTo`	Go to a particular record, display it, and optionally select the specified text.
`sysAppLaunchCmdGoToURL`	Launch an application and open a URL.
`sysAppLaunchCmdHandleSyncCallApp`	Perform some application-specific operation at the behest of the application's conduit.
`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 the Web Clipping Application Viewer.

Launch Codes ^TOP^

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 ^TOP^

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 Email Messages" in the Palm OS Programmer's Companion, vol. II, Communications.

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 ^TOP^

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.

sysAppLaunchCmdAttention ^TOP^

Purpose

Perform the action requested by the attention manager. This launch code is accompanied by a value of the AttnCommand type; this type specifies the set of possible commands that can be sent to the application that requested the alarm.

Prototype

typedef UInt16 AttnCommand;

Comments

The following table lists the values that AttnCommand can assume.

Table 1.2 sysAppLaunchCmdAttention Commands

Constant	Value	Description
`AttnCommand_drawDetail`	`((AttnCommand)1)`	Indicates that the application needs to draw the detailed contents of the attention dialog. The command arguments parameter points to a structure of type `AttnCommandDrawDetailArgsType`.
`AttnCommand_drawList`	`((AttnCommand)2)`	Indicates that the application needs to draw the appropriate list item in the attention dialog. The command arguments parameter points to a structure of type `AttnCommandDrawListArgsType`.
`AttnCommand_customEffect`	`((AttnCommand)3)`	Indicates that the Attention Manager is doing something to get the user's attention, and any application-specific special effect should be done. This command is only sent to attention items that set the `AttnFlags_CustomEffectBit` when they call `AttnGetAttention()`, which most applications won't do.
`AttnCommand_goThere`	`((AttnCommand)4)`	Tells the application to navigate to the item. The command arguments parameter is `NULL`. An application commonly calls `SysAppLaunch()` upon receipt of this command to have itself launched.
`AttnCommand_gotIt`	`((AttnCommand)5)`	Tells the application that the user is dismissing the item. The command arguments parameter is `NULL`. The application may choose to clean up memory at this point.
`AttnCommand_snooze`	`((AttnCommand)6)`	Indicates to the application that the user is snoozing. The command arguments parameter is `NULL`. Most applications do nothing upon receipt of this command. This command is passed to each and every item currently pending, insistent or subtle. Applications with more than one attention item pending are called more than once.
`AttnCommand_iterate`	`((AttnCommand)7)`	This command is passed to the application during the enumeration of attention items. This command is particularly useful after HotSync operations, as it allows the application to examine each item, updating or removing those that are stale or invalid.

AttnCommandDrawDetailArgsType

Purpose

When AttnCommand_drawDetail is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application needs to draw the detailed contents of the attention dialog. The AttnCommandDrawDetailArgsType structure accompanies the AttnCommand_drawDetail command, and provides the information needed to draw the contents of that dialog.

Prototype

typedef struct {
  RectangleType bounds;
  Boolean firstTime;
  AttnFlagsType flags;
} AttnCommandDrawDetailArgsType;

Fields

bounds: Contains the window-relative bounding box for the area to draw. The clipping region is also set to the dimensions of this box to prevent accidental drawing outside.
firstTime: Set to true if the user has not yet seen this item. The value of this field could be used, for example, to display attentions that the user hasn't seen before in some special way.
flags: The global user preferences for this attention attempt combined with the custom flags passed in by the developer. For example, if the global preference is to mute sounds, and the developer flags are both zero, then the AttnFlags_NoSound flag is on and the AttnFlags_AlwaysSound flag is off.

AttnCommandDrawListArgsType

When AttnCommand_drawList is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application is to draw the appropriate list item in the attention dialog. The AttnCommandDrawListArgsType structure accompanies the AttnCommand_drawList command, and provides the information needed to draw the contents of that dialog.

Prototype

typedef struct {
  RectangleType bounds;
  Boolean firstTime;
  AttnFlagsType flags;
} AttnCommandDrawListArgsType;

Fields

bounds: Contains the window-relative bounding box for the area to draw. The clipping region is also set to the dimensions of this box to prevent accidental drawing outside.
firstTime: Set to true if the user has not yet seen this item. The value of this field could be used, for example, to trigger a custom sound the first time this attention item is presented to the user.
flags: The global user preferences for this attention attempt combined with the custom flags passed in by the developer. For example, if the global preference is to mute sounds, and the developer flags were both zero, then the AttnFlags_NoSound flag is on and the AttnFlags_AlwaysSound flag is off.

AttnCommandGotItArgsType

When AttnCommand_gotIt is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, it is accompanied by an AttnCommandGotItArgsType structure. This structure indicates whether the AttnCommand_gotIt command was generated because the user dismissed the attention, or whether the system is simply informing your application that AttnForgetIt() was called. Your application normally ignores the latter case if your application made the call to AttnForgetIt.

Prototype

typedef struct {
  Boolean dismissedByUser;
} AttnCommandGotItArgsType;

Fields

dismissedByUser: true indicates that the user dismissed the attention. false indicates that the AttnCommand_gotIt command was generated by a call to AttnForgetIt.

sysAppLaunchCmdCardLaunch ^TOP^

This launch code is sent to applications that are being run from an expansion card. The application is copied into the device's main memory prior to being sent this launch code. If the application doesn't respond to sysAppLaunchCmdCardLaunch, it is then sent a sysAppLaunchNormalLaunch launch code. Applications that can profit from the knowledge that they are being launched from an expansion card may want to consult the fields in the parameter block that accompanies sysAppLaunchCmdCardLaunch.

When the Launcher sends sysAppLaunchCmdCardLaunch to an application, it also sends sysAppLaunchFlagNewGlobals, and sysAppLaunchFlagUIApp flags. These two flags are not sent to start.prc, however. Applications should never interact with the user upon receiving this launch code, and should not depend on globals being available. This launch code is intended to notify the application that it is being launched from a card. Applications typically save some state information upon receiving this launch code and do the bulk of their processing when they receive sysAppLaunchNormalLaunch.

sysAppLaunchCmdCardLaunch Parameter Block

Prototype

typedef struct {
   Err err;
   UInt16 volRefNum;
   const Char *path;
   UInt16 startFlags;
} SysAppLaunchCmdCardType;

Fields

← err: Initially set to expErrUnsupportedOperation, applications that recognize sysAppLaunchCmdCardLaunch and that don't want to receive the subsequent sysAppLaunchNormalLaunch launch code should set this field to errNone.
→ volRefNum: The reference number of the volume from which the application is being launched.
→ path: The complete path to the application being launched.
↔ startFlags: This field is made up of a combination of the following flags.

sysAppLaunchCmdCountryChange ^TOP^

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 ^TOP^

Performs full, possibly blocking, handling of alarm.

This is the application's opportunity to handle an alarm in a lengthy or blocking fashion. Alert 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 ^TOP^

The Exchange Manager sends the sysAppLaunchCmdExgAskUser launch code to the application when data has arrived for that application. This launch code allows the application to tell the Exchange Manager not to display the exchange dialog, which it uses to have the user confirm the receipt of data. If the application does not handle this launch code, the default course of action is that the Exchange Manager displays the exchange dialog.

Applications may want to respond to this launch code under these circumstances:

To reject all incoming data or to reject data under certain circumstances without first prompting the user. To reject incoming data, set the result field of the parameter block to exgAskCancel and then return.
To receive incoming data without confirmation. To automatically receive incoming data, set the result field to exgAskOk.
To provide a user confirmation dialog with extra functionality. This is described in more detail below.

Starting with Palm OS 3.5, the Exchange Manager allows applications to provide extra functionality in the exchange dialog. You can have the dialog include a category pop-up list from which the user chooses a category in which to file the incoming data. If you want to provide a category pop-up list, call the ExgDoDialog() function in response to this launch code and pass it a database that contains the categories to be listed. See the description of that function for more information.

Applications may also bypass the call to ExgDoDialog altogether and provide their own dialogs.

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

exgAskDialog: Display the default exchange dialog provided by Exchange Manager.
exgAskOk: Accept the incoming data.
exgAskCancel: Reject the incoming data.

On Palm OS 3.5 or higher if you don't use the default version of the dialog, return exgAskOk if the user confirmed or exgAskCancel if the user canceled. If you don't set the result field properly, two dialogs are displayed.

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 (see ExgSocketType)
← result: Show dialog, auto-confirm, or auto-cancel
→ reserved: Reserved for future use

sysAppLaunchCmdExgGetData ^TOP^

The Exchange Manager sends the sysAppLaunchCmdExgGetData launch code when the exchange library requests data to be sent to a remote device. That is, an application on a remote device has performed an ExgGet() function to request data, and the Exchange Manager has determined that the launched application should handle the request.

To respond to this launch code, applications should initiate a connection with ExgPut(), use ExgSend() to send the data, and call ExgDisconnect() when finished.

The parameter block sent with this launch code is a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is to be sent. You pass this socket pointer to ExgPut. For more details, see the "Exchange Manager" chapter.

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

sysAppLaunchCmdExgPreview ^TOP^

Following the launch code sysAppLaunchCmdExgAskUser, the Exchange Manager sends the sysAppLaunchCmdExgPreview launch code to have the application display the preview in the exchange dialog.

sysAppLaunchCmdExgPreview Parameter Block

Prototype

typedef struct {
   UInt16 version;
   ExgSocketType *socketP;
   UInt16 op;
   Char *string;
   UInt32 size;
   RectangleType bounds;
   UInt16 types;
   Err error;
} ExgPreviewInfoType;

Fields

→ version: Set this field to 0 to specify version 0 of this structure.
→ socketP: A pointer to the socket structure (see ExgSocketType). The libraryRef field must point to the exchange library from which preview data should be received.
→ op: A constant that identifies the operation. This can be one of the following:
← string: A buffer into which the preview string is placed if one of the string preview operations is specified.
→ size: The allocated size of the string field.
→ bounds: The bounds of the rectangle in which to draw the graphic if the preview operation is exgPreviewDraw.
← types: Upon return from exgPreviewQuery, a bit field identifying the types of previews the library supports (exgPreviewDraw, exgPreviewLongString, or exgPreviewShortString).
← error: The error code returned from the library. If this is errNone, the preview operation was successful.

Applications that respond to this launch code should check the parameter block's op field and respond as described above.

Applications can define and use their own constants for the preview operation. Operations specific to an application are numbered starting at exgPreviewFirstUser and should be no greater than exgPreviewLastUser.

Applications respond to this launch in much the same way they respond to sysAppLaunchCmdExgReceiveData. Use ExgAccept() to accept the preview connection, ExgReceive() to receive the data, and then ExgDisconnect() to end the connection. The only difference is what is done with the data when it is received. With this launch code, the application should return the data in the string field or draw it in the bounds rectangle. With the sysAppLaunchCmdExgReceiveData launch code, the application stores the received data.

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

sysAppLaunchCmdExgReceiveData ^TOP^

The Exchange Manager sends the sysAppLaunchCmdExgReceiveData launch code following the sysAppLaunchCmdExgAskUser and sysAppLaunchCmdExgPreview launch codes to notify the application 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. Specifically, most applications should respond to this launch code by calling ExgAccept() to accept the connection and then ExgReceive() to receive 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:

Boolean appIsActive = launchFlags & sysAppLaunchFlagSubCall;

The appIsActive value is 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 a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is arriving. 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 ^TOP^

This launch code is used to implement the global find. When the user enters a text string in the Find dialog, the system sends this launch code with the FindParamsType parameter block to each application. The application should search for the string that the user entered and return any records matching the find request.

The system displays the results of the query in the Find results dialog. The system continues the search with each application until it has a full screen of matching records or until all of the applications on the device have had a chance to respond. If the screen is full, a Find More button appears at the bottom of the dialog. If the user clicks the Find More button, the search resumes. Applications can test whether the current find is a continuation of a previous one by checking the continuation field in the parameter block.

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. Functions that you can use to respond to this launch code are described in Chapter 10, "Find."

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 {
   UInt16 dbAccesMode;
   UInt16 recordNum;
   Boolean more;
   Char strAsTyped [maxFindStrLen+1];
   Char strToFind [maxFindStrLen+1];
   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: Mode in which to open the application's database. Pass this directly to DmOpenDatabase() as the mode parameter. Its value is either dmModeReadOnly or dmModeReadOnly | dmModeShowSecret. (See "Open Mode Constants" for more information.)
recordNum: Index of last record that contained a match. Start the search from this location. Do not set this value directly. Instead, call FindSaveMatch() when you have a matching record.
more: If true, the Find results dialog displays the Find More button indicating that there may be more results to display.; Typically FindSaveMatch() handles setting the more field. Applications with large databases to search may want to periodically check for and stop the search if an event is pending. If so, they should set this field to true before stopping.
strAsTyped: Search string as the user entered it.
strToFind: Normalized version of the search string. The method by which a search string is normalized varies depending on the version of Palm OS and the character encoding supported by the device. You pass strToFind directly to the search function (either FindStrInStr(), TxtFindString(), or TxtGlueFindString).
reserved1: Reserved for future use.
numMatches: The current number of matches. Do not set this field directly. Instead, call FindSaveMatch(), which increments it for you.
lineNumber: Line number of the next line that displays the results. Do not set this field directly. It is incremented by a call to FindDrawHeader().
continuation: If true, the launch code is being sent as part of a continuation of a previous Find. If false, this is a new Find. Do not set this field directly; the system sets it when the Find results dialog is full.
searchedCaller: If true, the application that was active at the time the user tapped the Find button has responded to this launch code. This application is always searched before any others.
callerAppDbID: Database ID of the application that was active when the user tapped the Find button. Do not change the value of this field; the system sets it and uses it when searching for application databases.
callerAppCardNo: Card number of the application that was active when the user tapped the Find button. Do not change the value of this field; the system sets it and uses it when searching for application databases.
appDbID: The ID of your application's resource database. Do not set this field directly; the system sets it and uses it when searching for application databases.
appCardNo: The card number of your application's resource database. Do not set this field directly; the system sets it and uses it when searching for application databases.
newSearch: System use only.
reserved2: Reserved for future use.
searchState: System use only.
match: System use only.

sysAppLaunchCmdGoTo ^TOP^

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).

Applications that receive this launch code should test the sysAppLaunchFlagNewGlobals launch flag to see if they need to initialize global variables. sysAppLaunchFlagNewGlobals indicates that the system has just allocated your global variables.

For example:

case sysAppLaunchCmdGoTo: 
  if (launchFlags & sysAppLaunchFlagNewGlobals)
    StartApplication();

Note that you shouldn't automatically initialize the global variables in response to this launch code. Test the launch flag first. Your application receives this launch code when the user selects a record in the global find results. If your application was the current application before the user selected the Find command, the launch flag is clear to indicate that your globals should not be re-initialized.

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 normalized search string. This is not the length of the matching string. See below for a full explanation.
dbCardNo: Card number of the database to open.
dbID: Local ID of the database to open.
recordNum: Index of record containing a match.
matchPos: Position of the match within the field.
matchFieldNum: Field number string was found in.
matchCustom: Application-specific information.

Often, applications highlight the search string when displaying the resulting record. Localizable applications commonly store the length of the string to select in the matchCustom field for this purpose. Some multi-byte character encodings represent certain characters both as a single-byte character and a multi-byte character. When the search is performed, the single-byte character is accurately matched against its multi-byte equivalent. For this reason, the length of the string searched for does not always equal the length of the matching string. Applications that support being localized to multi-byte character sets often set the matchCustom field to the length of the matching string in the call to FindSaveMatch() so that they know the length of the string to select.

sysAppLaunchCmdGoToURL ^TOP^

Applications can respond to this launch code to retrieve and display the specified URL.

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

This launch code may be sent in the following instances:

If the Wireless Internet Feature Set is, applications can send this launch code directly to the Web Clipping Application Viewer application.
If 4.0 New Feature Set is present, the ExgRequest() function launches an application with this launch code if it cannot find an exchange library that is registered for the URL it has received. To receive the launch code, the application must first use ExgRegisterDatatype() to register for a URL scheme.

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

sysAppLaunchCmdHandleSyncCallApp ^TOP^

This launch command is sent by the Desktop Link server when SyncCallRemoteModule is called from a conduit to request that the handheld application do some processing on the conduit's behalf.

Along with this launch code you receive a sysAppLaunchCmdHandleSyncCallApp parameter block which contains all of the information passed to SyncCallRemoteModule on the desktop plus the fields needed to pass the result back to the desktop. Pass the results back to the conduit by calling DlkControl(). See the comments section for DlkControl in the Palm OS Programmer's API Reference for an example of how to handle this launch code.

sysAppLaunchCmdHandleSyncCallApp Parameter Block

Prototype

typedef struct 
SysAppLaunchCmdHandleSyncCallAppType {
   UInt16 pbSize;
   UInt16 action;
   void *paramP;
   UInt32 dwParamSize;
   void *dlRefP;
   Boolean handled;
   UInt8 reserved1;
   Err replyErr;
   UInt32 dwReserved1;
   UInt32 dwReserved2;
} SysAppLaunchCmdHandleSyncCallAppType;

Fields

pbSize: Size, in bytes, of this parameter block. Set to sizeof(SysAppLaunchCmdHandle SyncCallAppType).
action: Call action ID (application-specific).
paramP: Pointer to parameter block (call action ID specific).
dwParamSize: Parameter block size, in bytes.
dlRefP: DesktopLink reference pointer. Supply this value in the DlkCallAppReplyParamType structure when calling DlkControl() with the dlkCtlSendCallAppReply control code.
handled: Initialized to false by DLServer; if handled, your application must set it to true (and your handler the handler must call DlkControl with the dlkCtlSendCallAppReplycontrol code). If your handler is not going to send a reply back to the conduit, leave this field set to false, in which case the DesktopLink Server will send the default "unknown request" reply.
reserved1: Reserved. Set to NULL.
replyErr: Error code returned from the call to DlkControl() with the dlkCtlSendCallAppReply control code.
dwReserved1: Reserved. Set to NULL.
dwReserved2: Reserved. Set to NULL.

sysAppLaunchCmdInitDatabase ^TOP^

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 ^TOP^

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.

sysAppLaunchCmdNormalLaunch ^TOP^

The system or an application sends this launch code to launch an application. Upon receiving this launch code the application should perform a full launch and display its user interface. See "Responding to Normal Launch" for details on launching your application in response to this launch code.

Global variables are available upon receipt of this launch code.

sysAppLaunchCmdNotify ^TOP^

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 the chapter titled "Notifications" in this book.

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 "Notifications" chapter.

sysAppLaunchCmdOpenDB ^TOP^

You can send this launch code to the Web Clipping Application Viewer 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 ^TOP^

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 ^TOP^

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 ^TOP^

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

Any application that supports the Find command and that can have buffered data should support this launch code. The system sends this launch code to the currently active application before it begins the search. The application receiving this launch code should respond by saving all buffered data so that the search is able to find matches in the text just entered.

sysAppLaunchCmdSaveData Parameter Block

Prototype

typedef struct {
   Boolean uiComing;
   UInt8 reserved1;
} SysAppLaunchCmdSaveDataType;

Fields

uiComing: true if the system dialog is displayed before launch code arrives.
reserved1: Reserved for future use.

sysAppLaunchCmdSyncNotify ^TOP^

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 ^TOP^

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 ^TOP^

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, vol. I.

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 ^TOP^

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 ^TOP^

This launch code is sent from the Web Clipping Application Viewer 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.

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 the Web Clipping Application Viewer 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 ^TOP^

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

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

Table 1.3 Launch Flags

Flag	Functionality
`sysAppLaunchFlagNewGlobals`	Set when the system has created and initialized a new globals world for the application. Implies new owner ID for memory chunks.
`sysAppLaunchFlagUIApp`	Set when a UI application is being launched.
`sysAppLaunchFlagSubCall`	Set when 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.

IMPORTANT: Applications should never set launch flags when sending a launch code to another application. They should only be set by the system. In particular, note that you should never pass sysAppLaunchFlagNewGlobals as a launch flag for SysAppLaunch. If you do and you make repeated calls to SysAppLaunch, the system eventually runs out of owner IDs, and the new application fails to launch.

1 Application Launch Codes

Launch Codes ^TOP^

sysAppLaunchCmdAddRecord ^TOP^

sysAppLaunchCmdAddRecord Parameter Block for Mail Application

Prototype

Fields

sysAppLaunchCmdAddRecord Parameter Block for iMessenger Application

Prototype

Fields

sysAppLaunchCmdAlarmTriggered ^TOP^

sysAppLaunchCmdAlarmTriggered Parameter Block

Prototype

Fields

sysAppLaunchCmdAttention ^TOP^

Purpose

Prototype

Comments

AttnCommandDrawDetailArgsType

Purpose

Prototype

Fields

AttnCommandDrawListArgsType

Prototype

Fields

AttnCommandGotItArgsType

Prototype

Fields

sysAppLaunchCmdCardLaunch ^TOP^

sysAppLaunchCmdCardLaunch Parameter Block

Prototype

Fields

sysAppLaunchCmdCountryChange ^TOP^

sysAppLaunchCmdDisplayAlarm ^TOP^

sysAppLaunchCmdDisplayAlarm Parameter Block

Prototype

Fields

sysAppLaunchCmdExgAskUser ^TOP^

sysAppLaunchCmdExgAskUser Parameter Block

Prototype

Fields

sysAppLaunchCmdExgGetData ^TOP^

sysAppLaunchCmdExgPreview ^TOP^

sysAppLaunchCmdExgPreview Parameter Block

Prototype

Fields

sysAppLaunchCmdExgReceiveData ^TOP^

sysAppLaunchCmdFind ^TOP^

sysAppLaunchCmdFind Parameter Block

Prototype

Fields

sysAppLaunchCmdGoTo ^TOP^

sysAppLaunchCmdGoTo Parameter Block

Prototype

Fields

sysAppLaunchCmdGoToURL ^TOP^

sysAppLaunchCmdHandleSyncCallApp ^TOP^

sysAppLaunchCmdHandleSyncCallApp Parameter Block

Prototype

Fields

sysAppLaunchCmdInitDatabase ^TOP^

sysAppLaunchCmdInitDatabase Parameter Block

Prototype

Fields

sysAppLaunchCmdLookup ^TOP^

sysAppLaunchCmdLookup Parameter Block

sysAppLaunchCmdNormalLaunch ^TOP^

See Also

sysAppLaunchCmdNotify ^TOP^

sysAppLaunchCmdNotify Parameter Block

sysAppLaunchCmdOpenDB ^TOP^

sysAppLaunchCmdOpenDB Parameter Block

Prototype

Fields

sysAppLaunchCmdPanelCalledFromApp ^TOP^

sysAppLaunchCmdReturnFromPanel ^TOP^

sysAppLaunchCmdSaveData ^TOP^

sysAppLaunchCmdSaveData Parameter Block

Prototype

Fields

sysAppLaunchCmdSyncNotify ^TOP^