Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    Common Launch Codes

Programming Basics

Exploring Palm OS®

This chapter provides detailed descriptions of many of the Palm OS application launch codes and flags. Launch codes that are specific to a particular technology are documented with that technology. For instance, launch codes used exclusively with the Alarm Manager are documented in the Alarm Manager reference chapter within Exploring Palm OS: System Management.

This chapter is organized into the following sections:

Common Launch Codes Structures and Types
Common Launch Codes Constants
Common Launch Codes

The header file CmnLaunchCodes.h declares the API that this chapter describes.

Further information on working with launch codes and flags, plus a complete listing of all Palm OS launch codes, can be found in Chapter 2, "Application Start and Stop."

Common Launch Codes Structures and Types ^TOP^

GoToParamsType Struct ^TOP^

Purpose

Parameter block for the sysAppLaunchCmdGoTo launch code. An application receives this launch code if the user selects one of its matching records in the Find Results dialog or to display data that has just been received using the Exchange Manager.

Declared In

Find.h

Prototype

typedef struct {
   DatabaseID dbID;
   uint32_t recordNum;
   uint32_t recordID;
   size_t matchPos;
   size_t matchLen;
   uint32_t matchFieldNum;
   size_t searchStrLen;
   uint32_t matchCustom;
   char string[maxFindStrLen+1];
   uint8_t reserved1;
   uint8_t reserved2;
   uint8_t reserved3;
} GoToParamsType
typedef GoToParamsType *GoToParamsPtr

Fields

dbID
Database ID of the record database to open.
recordNum
Index of the database record to display.
recordID
Unique ID of the database record to display.
matchPos
Byte offset of the start of the matching text within the record. The Exchange Manager does not use this field.
matchLen
The number of bytes of matched text found in the record. The Exchange Manager does not use this field.
matchFieldNum
Index of the text field in which the matching text should be displayed.
If your application's database is a schema database, use this field to set the column ID that contains the matching text.
The Exchange Manager does not use this field.
searchStrLen
Length of normalized search string. This is not the length of the matching string. matchLen contains the length of the matching string.
The Exchange Manager does not use this field.
matchCustom
Application-specific information.
string
The strAsTyped field from FindParamsType. The Exchange Manager does not use this field.
reserved1
Reserved for future use.
reserved2
Reserved for future use.
reserved3
Reserved for future use.

Comments

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.

See Also

FindParamsType, FindSaveMatch()

Common Launch Codes Constants ^TOP^

Launch Flags ^TOP^

Purpose

Flags that compose the launchFlags argument of an application's PilotMain().

Declared In

CmnLaunchCodes.h

Constants

#define sysAppLaunchFlagDataRelocated 0x80
Indicates that global data (static pointers) have been relocated. Note: This flag is for internal use by SysAppLaunch() only. It should never be set by the caller.
#define sysAppLaunchFlagGlobalsAvailable 0x20
Indicates that the application can access globals. This flag is set whenever sysAppLaunchFlagNewGlobals is set, or when the application has an unique runtime ID. Note: This flag is for internal use by SysAppLaunch() only. It should never be set by the caller.
#define sysAppLaunchFlagNewGlobals 0x04
Set this flag to create a new globals environment for the application being launched. Note that a new globals environment implies a new owner ID for memory chunks.
#define sysAppLaunchFlagNewStack 0x02
Set this flag to have the launched application use its own, newly-created, stack.
#define sysAppLaunchFlagNewThread 0x01
Set this flag to have the application launched in a new thread. Applications launched with this flag set will also get a new stack, irrespective of the sysAppLaunchFlagNewStack flag.
#define sysAppLaunchFlagPrivateSet (sysAppLaunchFlagSubCall | sysAppLaunchFlagDataRelocated | sysAppLaunchFlagGlobalsAvailable)
The set of private, internal flags that should never be set by the caller.
#define sysAppLaunchFlagSubCall 0x10
Set this flag to indicate that the application is calling its own entry point as a subroutine call. When this flag is set, the A5 (globals) pointer remains valid through the call. Note: This flag is for internal use by SysAppLaunch() only. It should never be set by the caller.
#define sysAppLaunchFlagUIApp 0x08
Indicates to the application being launched that it is a UI application.

Miscellaneous Common Launch Codes Constants ^TOP^

Purpose

The header file CmnLaunchCodes.h also declares these constants.

Declared In

CmnLaunchCodes.h

Constants

#define sysAppLaunchCmdCustomBase 0x8000
Application-specific launch codes should be defined starting with this value.
#define sysDialLaunchCmdLast 39
The last of the standard dialer service launch codes.
#define sysSvcLaunchCmdLast 49
The last of the standard service panel launch codes.

Common Launch Codes ^TOP^

sysAppLaunchCmdAddRecord ^TOP^

Purpose

Add a record to an application's database.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdAddRecord 19


Parameters

The launch code's parameter block pointer references a MailAddRecordParamsType structure. This structure looks like this:

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;
typedef MailAddRecordParamsType
   *MailAddRecordParamsPtr;

where:

  • A true value for secret means that the message should be marked secret.
  • A true value for signature indicates that the signature from the Mail application's preferences should be attached to the message.
  • A true value for confirmRead means that a confirmation should be sent when the message is read.
  • A true value for confirmDelivery means that a confirmation should be sent when the message is delivered.
  • priority is either high, normal, or low.
  • subject is a pointer to a null-terminated string containing the message's subject. Set this pointer to NULL to omit the subject line.
  • from is a pointer to a null-terminated string containing the sender's address. This field is not currently used.
  • to is a pointer to a null-terminated string containing the email addresses to which the message is to be sent.
  • cc is a pointer to a null-terminated string containing any additional email address to which the message is to be sent. This pointer is required; if the message isn't to be sent to any additional addresses, cc should point to a NUL character.
  • bcc is a pointer to a null-terminated string containing any "blind carbon copy" email address to which the message is to be sent. This pointer is required; if the message isn't to be sent to any bcc addresses, bcc should point to a NUL character.
  • replyTo is a pointer to a null-terminated string containing the email address to which any replies should be sent.
  • body is a pointer to a null-terminated string containing the text of the email message.

Comments

This launch code is used to add a message to the Mail or iMessenger (on the Palm VII) 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.

See Also

sysAppLaunchCmdMoveRecord

sysAppLaunchCmdAntennaUp ^TOP^

Purpose

Sent when the antenna is raised on devices that are appropriately equipped.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdAntennaUp 53


Parameters

None.

Comments

This launch code is typically used to switch to the Launcher (or whichever application the user has specified for this action).

sysAppLaunchCmdCardLaunch ^TOP^

Purpose

Sent to an application that is being run from an expansion card, before the application is copied into the device's main memory.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdCardLaunch 58


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdCardType structure.

Comments

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 sysAppLaunchCmdNormalLaunch 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 sets the sysAppLaunchFlagNewStack, sysAppLaunchFlagNewGlobals, and sysAppLaunchFlagUIApp flags (see "Launch Flags" for documentation on these flags). These 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.

sysAppLaunchCmdCountryChange ^TOP^

Purpose

Sent when the user has changed their country preference. As a result, various locale-specific formats should change.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdCountryChange 8


Parameters

None.

Comments

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

sysAppLaunchCmdDeleteRecord ^TOP^

Purpose

Generally sent to the PIM applications, this launch code instructs the application to delete a specified database record.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdDeleteRecord 67


Parameters

The launch code's parameter block pointer references a ImportExportRecordParamsType structure.

Comments

Note that the record may be identified either by index or unique ID. See the ImportExportRecordParamsType structure documentation for details.

See Also

sysAppLaunchCmdExportRecord, sysAppLaunchCmdImportRecord

sysAppLaunchCmdEventHook ^TOP^

Purpose

Sent to an application to allow the application to process an event.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdEventHook 25


Parameters

The launch code's parameter block pointer references an EventType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

sysAppLaunchCmdExportRecord ^TOP^

Purpose

Generally sent to the PIM applications, this launch code instructs the application to export a specified database record.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExportRecord 65


Parameters

The launch code's parameter block pointer references a ImportExportRecordParamsType structure.

Comments

In response to this launch code, the application should place a copy of the specified database record, properly formatted for export, in the location specified by the vObjectH field of the ImportExportRecordParamsType structure. Note that the record may be identified either by index or unique ID. See the ImportExportRecordParamsType structure documentation for details.

See Also

sysAppLaunchCmdDeleteRecord, sysAppLaunchCmdExportRecordGetCount, sysAppLaunchCmdImportRecord

sysAppLaunchCmdExportRecordGetCount ^TOP^

Purpose

Generally sent to the PIM applications, this launch code instructs the application to return the number of records in the application's database.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExportRecordGetCount 64


Parameters

The launch code's parameter block pointer references a single 32-bit integer into which the record count is to be written.

sysAppLaunchCmdFailedAppNotify ^TOP^

Purpose

Indicates a failure in an application that was just switched to.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFailedAppNotify 24


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdFailedAppNotifyType structure. This structure identifies the failed application and contains the error code returned from that application.

sysAppLaunchCmdFepPanelAddWord ^TOP^

Purpose

Send this launch code to the FEP panel to add a word to the FEP user dictionary.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFepPanelAddWord 87


Parameters

The launch code's parameter block pointer references a structure that indicates the word to be added. This structure is simply a pointer to the word to be added, followed by a uint16_t containing the length of the word, like this:


typedef struct { 
   const char *wordP; 
   uint16_t wordLen; 
} SysAppLaunchCmdFepPanelAddWordType; 

See Also

sysAppLaunchCmdLookupWord

sysAppLaunchCmdFinalizeUI ^TOP^

Purpose

Sent only to the root application of the Application process, this launch code instructs the application's startup code to de-initialize the process's UI.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFinalizeUI 0x7ff7


Parameters

None.

See Also

sysAppLaunchCmdInitializeUI

sysAppLaunchCmdFind ^TOP^

Purpose

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

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdFind 1


Parameters

The launch code's parameter block pointer references a FindParamsTypestructure.

Comments

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.

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 also support sysAppLaunchCmdSaveData and sysAppLaunchCmdGoTo.

sysAppLaunchCmdGoTo ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdGoTo 2


Parameters

The launch code's parameter block pointer references a GoToParamsTypestructure.

Comments

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.

sysAppLaunchCmdGoToURL ^TOP^

Purpose

Retrieve and display the specified URL.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdGoToURL 54


Parameters

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

Comments

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.

sysAppLaunchCmdHandleSyncCallApp ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdHandleSyncCallApp 18


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdHandleSyncCallAppType structure.

Comments

The SysAppLaunchCmdHandleSyncCallApp structure 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 that function's documentation for an example of how to handle this launch code.

sysAppLaunchCmdImportRecord ^TOP^

Purpose

Generally sent to the PIM applications, this launch code presents the application with a record to be added to or updated in the application's database.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdImportRecord 66


Parameters

The launch code's parameter block pointer references a ImportExportRecordParamsType structure.

Comments

If the uniqueID field of the ImportExportRecordParamsType structure contains the ID of an existing record, the imported record should replace the specified existing record. Otherwise, the imported record should be added to the application's database.

See Also

sysAppLaunchCmdDeleteRecord, sysAppLaunchCmdExportRecord

sysAppLaunchCmdInitDatabase ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdInitDatabase 11


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdInitDatabaseType structure.

Comments

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.


IMPORTANT: The sysAppLaunchCmdInitDatabase launch code handler must leave the database handle (the dbP field in the SysAppLaunchCmdInitDatabaseType structure) open on return.

sysAppLaunchCmdInitializeUI ^TOP^

Purpose

Sent only to the root application of the Application process, this launch code instructs the application's startup code to initialize the process's UI.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdInitializeUI 0x7ff8


Parameters

None.

See Also

sysAppLaunchCmdFinalizeUI

sysAppLaunchCmdLookup ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdLookup 15


Parameters

The parameter block is defined by the application that supports this launch code. For an example, see the source code for the standard Palm OS Address Book.

Comments

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

Applications that decide to handle this launch code must search their databases for the supplied string 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.

sysAppLaunchCmdLookupWord ^TOP^

Purpose

Send to the dictionary application to look a word up in the FEP dictionaries.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdLookupWord 88


Parameters

The launch code's parameter block pointer references a structure that indicates the word to be added. This structure is simply a pointer to the word to be added, followed by a uint16_t containing the length of the word, like this:


typedef struct { 
   const char *wordP; 
   uint16_t wordLen; 
} SysAppLaunchCmdFepPanelAddWordType; 

Comments

The specified word is automatically entered into the word lookup form, and the results are displayed to the user.

See Also

sysAppLaunchCmdFepPanelAddWord

sysAppLaunchCmdMoveRecord ^TOP^

Purpose

Move a record from one position to another in an application's database.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdMoveRecord 68


Parameters

The launch code's parameter block pointer references an ImportExportRecordParamsType structure. Within this structure, the index field indicates the record to be moved, and the destIndex field indicates the new position for the record (both indexes are zero-based). The uniqueID field is updated if this launch code succeeds.

Comments

If the application doesn't support this launch code, dmErrInvalidParam is returned.

See Also

sysAppLaunchCmdAddRecord

sysAppLaunchCmdMultimediaEvent ^TOP^

Purpose

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdMultimediaEvent 63

Parameters

sysAppLaunchCmdNormalLaunch ^TOP^

Purpose

Launch an application.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdNormalLaunch 0

Parameters

None.

See Also

sysAppLaunchCmdPinletLaunch, sysAppLaunchCmdSlipLaunch

sysAppLaunchCmdNotify ^TOP^

Purpose

The system or an application sends this launch code to notify applications that an event has occurred.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdNotify 51


Parameters

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

Comments

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

sysAppLaunchCmdOpenDB ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdOpenDB 52


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdOpenDBType structure.

sysAppLaunchCmdPanelCalledFromApp ^TOP^

Purpose

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.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdPanelCalledFromApp 13


Parameters

None.

Comments

In conjunction with sysAppLaunchCmdReturnFromPanel, this launch code allows 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.

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.

sysAppLaunchCmdPinletLaunch ^TOP^

Purpose

Sent to an application that is launched as a pinlet instead of sysAppLaunchCmdNormalLaunch in order to launch the application.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdPinletLaunch 83


Parameters

None.

See Also

sysAppLaunchCmdSlipLaunch

sysAppLaunchCmdReturnFromPanel ^TOP^

Purpose

Informs an application that the user is done with a called preferences panel.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdReturnFromPanel 14


Parameters

None.

Comments

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

sysAppLaunchCmdRun68KApp ^TOP^

Purpose

Sent to PACE in order to launch a 68K-based application.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdRun68KApp 0x7ffc


Parameters

The launch code's parameter block pointer references a structure that specifies the application to be run. This structure looks something like this:


typedef struct AppSwitchInfoType { 
   DatabaseID dbID; 
   DatabaseID agent; 
   MemPtr cmdPBP; 
   uint32_t cmdPBSize; 
   uint16_t cmd;    // if (!dbID), doubles as error code 
   uint16_t flags;  // hold launch flags fo the app 
   uint16_t rsrcID; 
   uint8_t padding[2]; 
} AppSwitchInfoType; 

sysAppLaunchCmdSaveData ^TOP^

Purpose

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

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSaveData 10


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdSaveDataType structure.

Comments

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.

sysAppLaunchCmdSlipLaunch ^TOP^

Purpose

Sent to any application that is launched within a Slip at the time of launch.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSlipLaunch 82


Parameters

None.

Comments

Applications so launched can only draw during update events.

See Also

sysAppLaunchCmdNormalLaunch, sysAppLaunchCmdPinletLaunch

sysAppLaunchCmdSyncCallApplicationV10 ^TOP^

Purpose

Used by the Desktop Link Server's "call application" command.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSyncCallApplicationV10 12


Parameters

sysAppLaunchCmdSyncNotify ^TOP^

Purpose

Sent to applications to inform them that a HotSync operation has occurred.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSyncNotify 3


Parameters

None.

Comments

This launch code is sent only to applications whose databases were changed during the HotSync operation, including when the application itself has been installed by HotSync. 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 notification. 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.

sysAppLaunchCmdSyncRequest ^TOP^

Purpose

Sent to the HotSync application to request a HotSync. This launch code is equivalent to sysAppLaunchCmdSyncRequestLocal.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSyncRequest 

sysAppLaunchCmdSyncRequestLocal


Parameters

None.

sysAppLaunchCmdSyncRequestLocal ^TOP^

Purpose

Sent to the HotSync application to request a "local" HotSync. A local HotSync occurs when the HotSync button is pressed.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSyncRequestLocal 9


Parameters

None.

See Also

sysAppLaunchCmdSyncRequest, sysAppLaunchCmdSyncRequestRemote

sysAppLaunchCmdSyncRequestRemote ^TOP^

Purpose

Sent to the HotSync application to request a "remote" HotSync. A remote HotSync occurs when the "Remote HotSync" button (vchrHardCradle2) is pressed.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSyncRequestRemote 17


Parameters

None.

See Also

sysAppLaunchCmdSyncRequest, sysAppLaunchCmdSyncRequestLocal

sysAppLaunchCmdSystemLock ^TOP^

Purpose

Sent to the system-internal security application to lock the device.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSystemLock 16


Parameters

None.

Comments

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.

sysAppLaunchCmdSystemReset ^TOP^

Purpose

Respond to a soft or hard reset.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdSystemReset 5


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdSystemResetType structure.

Comments

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 Chapter 7, "System Reset," in Exploring Palm OS: System Management.


NOTE: Your application will not receive this launch code unless the the ARMAppLaunchPrefsResetNotification flag in the application's launch preferences resource is set to TRUE. See the description of the Application Launch Preferences Resource—in particular, the ALPF_FLAG_NOTIFY_RESET flag— in Palm OS Resource File Formats for more information on setting this flag.

sysAppLaunchCmdTimeChange ^TOP^

Purpose

Respond to a time change initiated by the user.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdTimeChange 4


Parameters

None.

Comments

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.

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^

Purpose

Sent from the Web Clipping Application Viewer application to launch another application.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdURLParams 50


Parameters

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.

Comments

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.

sysAppLaunchNppiNoUI ^TOP^

Purpose

Sent to a network panel plug-in to launch it without UI, and load NetLib.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchNppiNoUI 55


Parameters

The launch code's parameter block pointer references a uint16_t that contains the network library reference number.

See Also

sysAppLaunchNppiUI

sysAppLaunchNppiUI ^TOP^

Purpose

Send to a network panel plug-in to launch it with UI.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchNppiUI 56


Parameters

None.

See Also

sysAppLaunchNppiNoUI

sysAppLaunchPnpsPreLaunch ^TOP^

Purpose

Pre-launch code for "plug-and-play" devices.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchPnpsPreLaunch 61


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdPnpsType structure.

sysAppLaunchPreDelete ^TOP^

Purpose

Sent to PalmSource-created applications before they're deleted.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchPreDelete 62


Parameters

None.

sysCncPluginLaunchCmdGetPlugins ^TOP^

Purpose

Sent to Connection Manager plug-in modules to request plug-in descriptions.

Declared In

CmnLaunchCodes.h

Prototype

#define sysCncPluginLaunchCmdGetPlugins 81


Parameters

The launch code's parameter block pointer references a CncGetPluginsPBType structure.

Comments


NOTE: This launch code is intended for use by Connection Manager plug-ins only. Applications should not send nor respond to this launch code.

Upon receipt of this launch code, each plug-in should set the CncGetPluginsPBType structure's plugins field so that it points to one or more contiguous CncPlgDefinitionType structures, each containing details about a particular plug-in. Set the CncGetPluginsPBType structure's n field to the number of plug-ins structures being returned.

See Also

sysCncPluginLaunchCmdRegister

sysCncPluginLaunchCmdRegister ^TOP^

Purpose

The Connection Manager sends this launch code to each plug-in module after it has been registered with the Connection Manager. This launch code gives the plug-in a chance to initialize itself.

Declared In

CmnLaunchCodes.h

Prototype

#define sysCncPluginLaunchCmdRegister 79


Parameters

The launch code's parameter block pointer references a CncRegisterPBType structure.

Comments


NOTE: This launch code is intended for use by Connection Manager plug-ins only. Applications should not send nor respond to this launch code.

A Connection Manager plug-in must handle this launch code if it wants to define more objects than just plug-ins, such as interfaces, edges or profiles. Plug-ins have already been added to the Connection Manager database before this code is sent.

See Also

sysCncPluginLaunchCmdUnregister

sysCncPluginLaunchCmdUnregister ^TOP^

Purpose

Sent to Connection Manager plug-in modules when removing plug-ins

Declared In

CmnLaunchCodes.h

Prototype

#define sysCncPluginLaunchCmdUnregister 80


Parameters

None.

Comments


NOTE: This launch code is intended for use by Connection Manager plug-ins only. Applications should not send nor respond to this launch code.

A Connection Manager plug-in must handle this launch code to free any data Connection Manager related. The Connection Manager has the charge to delete any profiles and relations that reference a deleted plug-in.

See Also

sysCncPluginLaunchCmdRegister

sysCncWizardLaunchCmdEdit ^TOP^

Purpose

The CncProfileEdit() function sends this launch code to the Connection Manager's configuration application in order to edit a connection profile.

Declared In

CmnLaunchCodes.h

Prototype

#define sysCncWizardLaunchCmdEdit 84


Parameters


NOTE: This launch code is intended for use by Connection Manager plug-ins only. Applications should not send nor respond to this launch code.

The launch code's parameter block pointer references a CncWizardEditPBType structure.

sysDialLaunchCmdDial ^TOP^

Purpose

Dials the modem (optionally displaying the dial progress), given the service ID and serial library reference number.

Declared In

CmnLaunchCodes.h

Prototype

#define sysDialLaunchCmdDial 30


Parameters

See Also

sysDialLaunchCmdHangUp

sysDialLaunchCmdHangUp ^TOP^

Purpose

Hangs up the modem (optionally displaying the disconnect progress), given the service ID and serial library reference number.

Declared In

CmnLaunchCodes.h

Prototype

#define sysDialLaunchCmdHangUp 31


Parameters

See Also

sysDialLaunchCmdDial

sysIOSDriverInstall ^TOP^

Purpose

Sent to a code module in the I/O process when it is installed.

Declared In

CmnLaunchCodes.h

Prototype

#define sysIOSDriverInstall 74


Parameters

The launch code's parameter block pointer references an IOSDriverInstallType structure.

Comments

The code module typically initializes the driver in response to this launch code.

sysIOSDriverRemove ^TOP^

Purpose

Sent to a code module in the I/O process when it is removed.

Declared In

CmnLaunchCodes.h

Prototype

#define sysIOSDriverRemove 75


Parameters

None.

sysLaunchCmdAppExited ^TOP^

Purpose

Sent by the Application Manager to all loaded modules after an application exits from its PilotMain() function.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdAppExited 0x7ff9


Parameters

None.

sysLaunchCmdBoot ^TOP^

Purpose

Sent to operating system initialization procedures at boot time, upon receipt of this launch code those procedures do whatever is necessary to initialize their component.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdBoot 70


Parameters

The launch code's parameter block pointer references a AppInitProcParamsType structure. This structure is private.

Comments

The procedure receiving this launch code runs in the System process. Drivers typically install themselves at this time (using IOSInstallDriver()). Many other initialization procedures take this opportunity to register plug-ins (with CncRegisterPluginModule()).

sysLaunchCmdFinalize ^TOP^

Purpose

Sent to all kinds of executable modules right before a module gets unloaded, this launch code gives your executable a last chance to release resources or do any other needed "de-initialization."

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdFinalize 0x7fff


Parameters

None.

See Also

sysLaunchCmdAppExited(), sysLaunchCmdInitialize()

sysLaunchCmdGetGlobals ^TOP^

Purpose

Sent to an executable module to retrieve a pointer to its global structure.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdGetGlobals 0x7ffa


Parameters

The launch code's parameter block pointer references a location into which the executable module should write either the location of its globals structure, if there are globals to export, or NULL if the executable doesn't export any globals.

Comments

An executable module that wants to make all or part of its globals accessible by other modules can do this by putting those globals in a single C structure and returning the address of this global structure in the memory location pointed to by the launch code's parameter block pointer.

To prevent globals from being retrieved, simply return NULL in response to this launch code.

See Also

"Exporting Globals" of Exploring Palm OS: System Management.

sysLaunchCmdGetModuleID ^TOP^

Purpose

Sent to an executable module to retrieve its module ID.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdGetModuleID 0x7ff5


Parameters

None.

sysLaunchCmdGraphicsAccelInit ^TOP^

Purpose

Sent by mini-GL to the graphics accelerator, requesting that it initialize itself.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdGraphicsAccelInit 78


Parameters

The launch code's parameter block pointer references a private structure that contains the mini-GL context in which the graphics accelerator is running.

sysLaunchCmdInitialize ^TOP^

Purpose

Sent to an executable module right after the module is loaded, this launch code gives your executable a chance to allocate resources or do any other needed initialization.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdInitialize 0x7ffe


Parameters

In some cases the launch code's parameter block pointer references a private structure that contains information about the heap. Often the parameter block pointer is set to NULL.

See Also

sysLaunchCmdFinalize()

sysLaunchCmdInitRuntime ^TOP^

Purpose

Sent to an executable module when it is loaded to initialize its module ID and linker stub.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdInitRuntime 0x7ff6


Parameters

The launch code's parameter block pointer references a structure that contains the module ID and a pointer to the module's linker stub. This structure looks like this:

struct {
   uint32_t id; 
   void *linkerP;
} cmdPB

sysLibLaunchCmdGet68KSupportEntry ^TOP^

Purpose

Sent to a shared library to determine if it can be called from a 68K application.

Declared In

CmnLaunchCodes.h

Prototype

#define sysLibLaunchCmdGet68KSupportEntry 0x7ffd


Parameters

The launch code's parameter block pointer indicates the location to which the launch code handler should write the address of the shared library's main entry point.

Comments

Shared libraries that can be called from 68K applications (via PACE) should respond to this launch code by returning (using the parameter block pointer) the address of the shared library's main entry point.

sysLaunchCmdProcessDestroyed ^TOP^

Purpose

Declared In

CmnLaunchCodes.h

Prototype

#define sysLaunchCmdProcessDestroyed 0x7ff4


Parameters

sysPackageLaunchAttachImage ^TOP^

Purpose

Sent to a package when it is loaded in order to supply an image context used by the package to determine when the package should be unloaded.

Declared In

CmnLaunchCodes.h

Prototype

#define sysPackageLaunchAttachImage 71


Parameters

The launch code's parameter block pointer references a private structure that contains information about the image context.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

See Also

sysPackageLaunchGetInstantiate

sysPackageLaunchGetInstantiate ^TOP^

Purpose

Sent to a package when it is loaded in order to locate the function used to instantiate the package's components.

Declared In

CmnLaunchCodes.h

Prototype

#define sysPackageLaunchGetInstantiate 72


Parameters

The launch code's parameter block pointer indicates a private structure. One of this structure's fields is the location to which the launch code handler should write the component instantiation function's address.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

See Also

sysPackageLaunchAttachImage

sysPinletLaunchCmdLoadProcPtrs ^TOP^

Purpose

Sent to a PRC-style pinlet before the pinlet is displayed on the screen, requesting pointers to the functions used by the Pen Input Manager when interacting with this pinlet.

Declared In

CmnLaunchCodes.h

Prototype

#define sysPinletLaunchCmdLoadProcPtrs 85


Parameters

The launch code's parameter block pointer references an empty PinletAPIType structure. Pinlets should fill in the contents of this structure upon receipt of this launch code.

sysSvcLaunchCmdGetQuickEditLabel ^TOP^

Purpose

Get a "quick edit" label for one of the standard service panels. The standard service panels include the Network panel and the Dialer panel.

Declared In

CmnLaunchCodes.h

Prototype

#define sysSvcLaunchCmdGetQuickEditLabel 40


Parameters

The launch code's parameter block pointer references a private SvcQuickEditLabelInfoType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

sysSvcLaunchCmdGetServiceID ^TOP^

Purpose

Get a standard service panel's service ID. The standard service panels include the Network panel and the Dialer panel.

Declared In

CmnLaunchCodes.h

Prototype

#define sysSvcLaunchCmdGetServiceID 21


Parameters

The launch code's parameter block pointer references a PrvNetSvcServiceIDType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

See Also

sysSvcLaunchCmdGetServiceInfo, sysSvcLaunchCmdSetServiceID

sysSvcLaunchCmdGetServiceInfo ^TOP^

Purpose

Obtain the name and service ID for a given system service.

Declared In

CmnLaunchCodes.h

Prototype

#define sysSvcLaunchCmdGetServiceInfo 23


Parameters

The launch code's parameter block pointer references a ServiceInfo68KType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

sysSvcLaunchCmdGetServiceList ^TOP^

Purpose

Obtain a list of system services.

Declared In

CmnLaunchCodes.h

Prototype

#define sysSvcLaunchCmdGetServiceList 22


Parameters

The launch code's parameter block pointer references a ServiceList68KType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

sysSvcLaunchCmdSetServiceID ^TOP^

Purpose

Set a standard service panel's service ID. The standard service panels include the Network panel and the Dialer panel.

Declared In

CmnLaunchCodes.h

Prototype

#define sysSvcLaunchCmdSetServiceID 20


Parameters

The launch code's parameter block pointer references a PrvNetSvcServiceIDType structure.

Comments

This launch code is for internal use only. Applications should not send or respond to this launch code.

See Also

sysSvcLaunchCmdGetServiceID