Application Launch Codes
 

 < Home   < Developers   < Development Support   < Documentation

1 Application Launch Codes


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part I: User Interface

1 Application Launch Codes

Launch Codes

sysAppLaunchCmdAddRecord

sysAppLaunchCmdAlarmTriggered

sysAppLaunchCmdAttention

sysAppLaunchCmdCardLaunch

sysAppLaunchCmdCountryChange

sysAppLaunchCmdDisplayAlarm

sysAppLaunchCmdExgAskUser

sysAppLaunchCmdExgGetData

sysAppLaunchCmdExgPreview

sysAppLaunchCmdExgReceiveData

sysAppLaunchCmdFind

sysAppLaunchCmdGoto

sysAppLaunchCmdGoToURL

sysAppLaunchCmdInitDatabase

sysAppLaunchCmdLookup

sysAppLaunchCmdNotify

sysAppLaunchCmdOpenDB

sysAppLaunchCmdPanelCalledFromApp

sysAppLaunchCmdReturnFromPanel

sysAppLaunchCmdSaveData

sysAppLaunchCmdSyncNotify

sysAppLaunchCmdSystemLock

sysAppLaunchCmdSystemReset

sysAppLaunchCmdTimeChange

sysAppLaunchCmdURLParams

Launch Flags

       

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

Table 1.1 Palm OS Launch Codes 
Code
Request
Execute the specified Network login script plugin command.
Provide information about the commands that your Network script plugin executes.
Add a record to a database.
Schedule next alarm or perform quick actions such as sounding alarm tones.
Perform the action requested by the attention manager.
Launch the application. This launch code signifies that the application is being launched from an expansion card.
Respond to country change.
Display specified alarm dialog or perform time-consuming alarm-related actions.
Let application override display of dialog asking user if they want to receive incoming data via the Exchange Manager.
Notify application that it should send data using the Exchange Manager.
Notify application that it should display a preview using the Exchange Manager.
Notify application that it should receive incoming data using the Exchange Manager.
Find a text string.
Go to a particular record, display it, and optionally select the specified text.
Launch an application and open a URL.
Initialize database.
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.
Notify about an event.
Launch application and open a database.
Tell preferences panel that it was invoked from an application, not the Preferences application.
Tell an application that it's restarting after preferences panel had been called.
Save data. Often sent before find operations.
Notify applications that a HotSync® has been completed.
Sent to the Security application to request that the system be locked down.
Respond to system reset. No UI is allowed during this launch code.
Respond to system time change.
Launch an application with parameters from the Web Clipping Application Viewer.

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 iMessengerTM (on the Palm VIITM 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

secretTrue means that the message should be marked secret.
signatureTrue means that the signature from the Mail application's preferences should be attached to the message.
confirmReadTrue means that a confirmation should be sent when the message is read.
confirmDeliveryTrue means that a confirmation should be sent when the message is delivered.
priorityMessage priority. Specify one of the MailMsgPriorityType enumerated types.
paddingReserved for future use.
subjectMessage's subject, a null-terminated string (optional).
fromMessage's sender, a null-terminated string (not used on outgoing mail).
toAddress of the recipient, a null-terminated string (required).
ccAddresses of recipients to be copied, a null-terminated string (optional).
bccAddresses of recipients to be blind copied, a null-terminated string (optional).
replyToReply to address, a null-terminated string (optional).
bodyThe 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

categoryCategory in which to place the message. Specify one of the following categories:
MsgInboxCategory
MsgOutboxCategory
MsgDeletedCategory
MsgFiledCategory
MsgDraftCategory
editTrue 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.
signatureTrue means that the signature from the iMessenger application preferences should be attached to the message.
subjectMessage's subject, a null-terminated string (optional).
fromMessage's sender, a null-terminated string (not used on outgoing mail).
toAddress of the recipient, a null-terminated string (required).
replyToReply to address, a null-terminated string (optional).
bodyThe 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

-> refThe caller-defined value specified when the alarm was set with AlmSetAlarm.
-> alarmSecondsThe date/time specified when the alarm was set with AlmSetAlarm. The value is given as the number of seconds since 1/1/1904.
<- purgeAlarmUpon 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.
   paddingNot used.

New sysAppLaunchCmdAttention

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.

typedef UInt16 AttnCommand; 

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

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.

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

Field Descriptions

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.

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

Field Descriptions

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.

typedef struct { 
  Boolean dismissedByUser; 
} AttnCommandGotItArgsType; 

Field Descriptions

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

New sysAppLaunchCmdCardLaunch

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

<- errInitially 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.
-> volRefNumThe reference number of the volume from which the application is being launched.
-> pathThe complete path to the application being launched.
<-> startFlagsThis field is made up of a combination of the following flags.
sysAppLaunchStartFlagAutoStartIndicates that the application is being run automatically upon card insertion.
sysAppLaunchStartFlagNoUISwitchSet this bit to prevent a UI switch to the application.
sysAppLaunchStartFlagNoAutoDeleteSet this bit to prevent the VFS Manager from deleting the copy of the application in main memory when the associated volume is unmounted.

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

-> refThe caller-defined value specified when the alarm was set with AlmSetAlarm.
-> alarmSecondsThe date/time specified when the alarm was set with AlmSetAlarm. The value is given as the number of seconds since 1/1/1904.
-> soundAlarmtrue if the alarm should be sounded, false otherwise. This value is currently not used.
   paddingNot used.

sysAppLaunchCmdExgAskUser

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:

exgAskDialogDisplay the default exchange dialog provided by Exchange Manager.
exgAskOkAccept the incoming data.
exgAskCancelReject 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

<-> socketPSocket pointer (see ExgSocketType)
<- resultShow dialog, auto-confirm, or auto-cancel
-> reservedReserved for future use

New sysAppLaunchCmdExgGetData

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.

New sysAppLaunchCmdExgPreview

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:
exgPreviewDialogDisplay a form or modal dialog containing the preview. This constant is only used in situations where one application launches another to display data.
exgPreviewDrawDraw the preview as a graphic in the bounds rectangle.
exgPreviewLongStringReturn the preview as a long string in the string field.
exgPreviewQueryReturn the list of preview modes the application supports in the types field.
exgPreviewLongStringReturn the preview as a short string in the string field.
<- string A buffer into which the preview string is placed if one of the string preview operations is specified.
-> sizeThe allocated size of the string field.
-> boundsThe bounds of the rectangle in which to draw the graphic if the preview operation is exgPreviewDraw.
<- typesUpon return from exgPreviewQuery, a bit field identifying the types of previews the library supports (exgPreviewDraw, exgPreviewLongString, or exgPreviewShortString).
<- errorThe 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

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

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

dbAccesModeMode 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.)
recordNumIndex 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.
moreIf 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).
reserved1Reserved for future use.
numMatchesThe current number of matches. Do not set this field directly. Instead, call FindSaveMatch, which increments it for you.
lineNumberLine number of the next line that displays the results. Do not set this field directly. It is incremented by a call to FindDrawHeader.
continuationIf 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.
searchedCallerIf 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.
callerAppDbIDDatabase 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.
callerAppCardNoCard 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.
appDbIDThe 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.
appCardNoThe 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.
newSearchSystem use only.
reserved2Reserved for future use.
searchStateSystem use only.
matchSystem 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).

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

searchStrLenLength of normalized search string. This is not the length of the matching string. See below for a full explanation.
dbCardNoCard number of the database to open.
dbIDLocal ID of the database to open.
recordNumIndex of record containing a match.
matchPosPosition of the match within the field.
matchFieldNumField number string was found in.
matchCustomApplication-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

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.

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

dbPDatabase reference.
creatorDatabase creator.
typeDatabase type.
versionDatabase 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 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

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 PalmTM 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

cardNoCard number of database to open.
dbIDDatabase 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 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

uiComingtrue if the system dialog is displayed before launch code arrives.
reserved1Reserved 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, vol. I.

sysAppLaunchCmdSystemReset Parameter Block

Prototype


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

Fields

hardResettrue if system was hardReset. false if system was softReset.
createDefaultDBIf 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 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

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.