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
GoToParamsType Struct
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 fromFindParamsType
. 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
Launch Flags
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 bySysAppLaunch()
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
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
sysAppLaunchCmdAddRecord
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;
- A
true
value forsecret
means that the message should be marked secret. - A
true
value forsignature
indicates that the signature from the Mail application's preferences should be attached to the message. - A
true
value forconfirmRead
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 eitherhigh
,normal
, orlow
. -
subject
is a pointer to a null-terminated string containing the message's subject. Set this pointer toNULL
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
sysAppLaunchCmdAntennaUp
Purpose
Sent when the antenna is raised on devices that are appropriately equipped.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdAntennaUp 53
Parameters
Comments
This launch code is typically used to switch to the Launcher (or whichever application the user has specified for this action).
sysAppLaunchCmdCardLaunch
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
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
Comments
Applications should change the display of numbers to use the proper number separators. To do this, call LocGetNumberSeparators
, StrLocalizeNumber
, and StrDelocalizeNumber
.
sysAppLaunchCmdDeleteRecord
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
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
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
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
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
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
sysAppLaunchCmdFinalizeUI
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
See Also
sysAppLaunchCmdFind
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 FindParamsType
structure.
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
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.
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
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
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
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
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
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
See Also
sysAppLaunchCmdLookup
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
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
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
sysAppLaunchCmdMultimediaEvent
Purpose
Declared In
CmnLaunchCodes.h
Prototype
Parameters
sysAppLaunchCmdNormalLaunch
Purpose
Declared In
CmnLaunchCodes.h
Prototype
Parameters
See Also
sysAppLaunchCmdPinletLaunch
, sysAppLaunchCmdSlipLaunch
sysAppLaunchCmdNotify
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
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
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
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
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
See Also
sysAppLaunchCmdReturnFromPanel
Purpose
Informs an application that the user is done with a called preferences panel.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdReturnFromPanel 14
Parameters
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
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
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
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
Comments
Applications so launched can only draw during update events.
See Also
sysAppLaunchCmdNormalLaunch
, sysAppLaunchCmdPinletLaunch
sysAppLaunchCmdSyncCallApplicationV10
Purpose
Used by the Desktop Link Server's "call application" command.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdSyncCallApplicationV10 12
Parameters
sysAppLaunchCmdSyncNotify
Purpose
Sent to applications to inform them that a HotSync operation has occurred.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdSyncNotify 3
Parameters
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
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
sysAppLaunchCmdSyncRequestLocal
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
See Also
sysAppLaunchCmdSyncRequest
, sysAppLaunchCmdSyncRequestRemote
sysAppLaunchCmdSyncRequestRemote
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
See Also
sysAppLaunchCmdSyncRequest
, sysAppLaunchCmdSyncRequestLocal
sysAppLaunchCmdSystemLock
Purpose
Sent to the system-internal security application to lock the device.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdSystemLock 16
Parameters
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
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
Purpose
Respond to a time change initiated by the user.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdTimeChange 4
Parameters
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
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
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
Purpose
Send to a network panel plug-in to launch it with UI.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchNppiUI 56
Parameters
See Also
sysAppLaunchPnpsPreLaunch
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
Purpose
Sent to PalmSource-created applications before they're deleted.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchPreDelete 62
Parameters
sysCncPluginLaunchCmdGetPlugins
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
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
Purpose
Sent to Connection Manager plug-in modules when removing plug-ins
Declared In
CmnLaunchCodes.h
Prototype
#define sysCncPluginLaunchCmdUnregister 80
Parameters
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
sysCncWizardLaunchCmdEdit
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
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
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
sysIOSDriverInstall
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
Purpose
Sent to a code module in the I/O process when it is removed.
Declared In
CmnLaunchCodes.h
Prototype
#define sysIOSDriverRemove 75
Parameters
sysLaunchCmdAppExited
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
sysLaunchCmdBoot
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
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
See Also
sysLaunchCmdAppExited()
, sysLaunchCmdInitialize()
sysLaunchCmdGetGlobals
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
Purpose
Sent to an executable module to retrieve its module ID.
Declared In
CmnLaunchCodes.h
Prototype
#define sysLaunchCmdGetModuleID 0x7ff5
Parameters
sysLaunchCmdGraphicsAccelInit
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
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
sysLaunchCmdInitRuntime
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
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
Purpose
Declared In
CmnLaunchCodes.h
Prototype
#define sysLaunchCmdProcessDestroyed 0x7ff4
Parameters
sysPackageLaunchAttachImage
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
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
sysPinletLaunchCmdLoadProcPtrs
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
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
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
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
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
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.