|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AttnCommandDrawDetailArgsTypeWhen AttnCommand_drawDetail is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application needs to draw the detailed contents of the attention dialog. The AttnCommandDrawDetailArgsType structure accompanies the AttnCommand_drawDetail command, and provides the information needed to draw the contents of that dialog. typedef struct { RectangleType bounds; Boolean firstTime; AttnFlagsType flags; } AttnCommandDrawDetailArgsType; Field DescriptionsAttnCommandDrawListArgsTypeWhen AttnCommand_drawList is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application is to draw the appropriate list item in the attention dialog. The AttnCommandDrawListArgsType structure accompanies the AttnCommand_drawList command, and provides the information needed to draw the contents of that dialog. typedef struct { RectangleType bounds; Boolean firstTime; AttnFlagsType flags; } AttnCommandDrawListArgsType; Field DescriptionsAttnCommandGotItArgsTypeWhen AttnCommand_gotIt is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, it is accompanied by an AttnCommandGotItArgsType structure. This structure indicates whether the AttnCommand_gotIt command was generated because the user dismissed the attention, or whether the system is simply informing your application that AttnForgetIt was called. Your application normally ignores the latter case if your application made the call to AttnForgetIt. typedef struct { Boolean dismissedByUser; } AttnCommandGotItArgsType; Field Descriptions
|
<- err | Initially set to expErrUnsupportedOperation, applications that recognize sysAppLaunchCmdCardLaunch and that don't want to receive the subsequent sysAppLaunchNormalLaunch launch code should set this field to errNone. |
-> volRefNum | The reference number of the volume from which the application is being launched. |
-> path | The complete path to the application being launched. |
<-> startFlags | This field is made up of a combination of the following flags. |
sysAppLaunchStartFlagAutoStart | Indicates that the application is being run automatically upon card insertion. |
sysAppLaunchStartFlagNoUISwitch | Set this bit to prevent a UI switch to the application. |
sysAppLaunchStartFlagNoAutoDelete | Set this bit to prevent the VFS Manager from deleting the copy of the application in main memory when the associated volume is unmounted. |
Applications should change the display of numbers to use the proper number separators. To do this, call LocGetNumberSeparators, StrLocalizeNumber, and StrDelocalizeNumber.
Performs full, possibly blocking, handling of alarm.
This is the application's opportunity to handle an alarm in a lengthy or blocking fashion. Alert dialogs are usually displayed when this launch code is received. This work should be done here, not when sysAppLaunchCmdAlarmTriggered is received. Multiple alarms may be pending at the same time for multiple applications, and one alarm display shouldn't block the system and prevent other applications from receiving their alarms in a timely fashion.
typedef struct SysDisplayAlarmParamType { UInt32 ref; UInt32 alarmSeconds; Boolean soundAlarm; UInt8 padding; } SysDisplayAlarmParamType;
-> ref | The caller-defined value specified when the alarm was set with AlmSetAlarm. |
-> alarmSeconds | The date/time specified when the alarm was set with AlmSetAlarm. The value is given as the number of seconds since 1/1/1904. |
-> soundAlarm | true if the alarm should be sounded, false otherwise. This value is currently not used. |
padding | Not used. |
The Exchange Manager sends the sysAppLaunchCmdExgAskUser launch code to the application when data has arrived for that application. This launch code allows the application to tell the Exchange Manager not to display the exchange dialog, which it uses to have the user confirm the receipt of data. If the application does not handle this launch code, the default course of action is that the Exchange Manager displays the exchange dialog.
Applications may want to respond to this launch code under these circumstances:
To reject all incoming data or to reject data under certain circumstances without first prompting the user. To reject incoming data, set the result field of the parameter block to exgAskCancel and then return.
To receive incoming data without confirmation. To automatically receive incoming data, set the result field to exgAskOk.
To provide a user confirmation dialog with extra functionality. This is described in more detail below.
Starting with Palm OS 3.5, the Exchange Manager allows applications to provide extra functionality in the exchange dialog. You can have the dialog include a category pop-up list from which the user chooses a category in which to file the incoming data. If you want to provide a category pop-up list, call the ExgDoDialog function in response to this launch code and pass it a database that contains the categories to be listed. See the description of that function for more information.
Applications may also bypass the call to ExgDoDialog altogether and provide their own dialogs.
If an application responds to this launch code, it must set the result field in the parameter block to the appropriate value. Possible values are:
exgAskDialog | Display the default exchange dialog provided by Exchange Manager. |
exgAskOk | Accept the incoming data. |
exgAskCancel | Reject the incoming data. |
On Palm OS 3.5 or higher if you don't use the default version of the dialog, return exgAskOk if the user confirmed or exgAskCancel if the user canceled. If you don't set the result field properly, two dialogs are displayed.
typedef struct { ExgSocketPtr socketP; ExgAskResultType result; UInt8 reserved; } ExgAskParamType;
<-> socketP | Socket pointer (see ExgSocketType) |
<- result | Show dialog, auto-confirm, or auto-cancel |
-> reserved | Reserved for future use |
The Exchange Manager sends the sysAppLaunchCmdExgGetData launch code when the exchange library requests data to be sent to a remote device. That is, an application on a remote device has performed an ExgGet function to request data, and the Exchange Manager has determined that the launched application should handle the request.
To respond to this launch code, applications should initiate a connection with ExgPut, use ExgSend to send the data, and call ExgDisconnect when finished.
The parameter block sent with this launch code is a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is to be sent. You pass this socket pointer to ExgPut. For more details, see the "Exchange Manager" chapter.
Following the launch code sysAppLaunchCmdExgAskUser, the Exchange Manager sends the sysAppLaunchCmdExgPreview launch code to have the application display the preview in the exchange dialog.
typedef struct { UInt16 version; ExgSocketType *socketP; UInt16 op; Char *string; UInt32 size; RectangleType bounds; UInt16 types; Err error; } ExgPreviewInfoType;
-> version | Set this field to 0 to specify version 0 of this structure. |
-> socketP | A pointer to the socket structure (see ExgSocketType). The libraryRef field must point to the exchange library from which preview data should be received. |
-> op | A constant that identifies the operation. This can be one of the following: |
exgPreviewDialog | Display a form or modal dialog containing the preview. This constant is only used in situations where one application launches another to display data. |
exgPreviewDraw | Draw the preview as a graphic in the bounds rectangle. |
exgPreviewLongString | Return the preview as a long string in the string field. |
exgPreviewQuery | Return the list of preview modes the application supports in the types field. |
exgPreviewLongString | Return the preview as a short string in the string field. |
<- string | A buffer into which the preview string is placed if one of the string preview operations is specified. |
-> size | The allocated size of the string field. |
-> bounds | The bounds of the rectangle in which to draw the graphic if the preview operation is exgPreviewDraw. |
<- types | Upon return from exgPreviewQuery, a bit field identifying the types of previews the library supports (exgPreviewDraw, exgPreviewLongString, or exgPreviewShortString). |
<- error | The error code returned from the library. If this is errNone, the preview operation was successful. |
Applications that respond to this launch code should check the parameter block's op field and respond as described above.
Applications can define and use their own constants for the preview operation. Operations specific to an application are numbered starting at exgPreviewFirstUser and should be no greater than exgPreviewLastUser.
Applications respond to this launch in much the same way they respond to sysAppLaunchCmdExgReceiveData. Use ExgAccept to accept the preview connection, ExgReceive to receive the data, and then ExgDisconnect to end the connection. The only difference is what is done with the data when it is received. With this launch code, the application should return the data in the string field or draw it in the bounds rectangle. With the sysAppLaunchCmdExgReceiveData launch code, the application stores the received data.
The Exchange Manager sends the sysAppLaunchCmdExgReceiveData launch code following the sysAppLaunchCmdExgAskUser and sysAppLaunchCmdExgPreview launch codes to notify the application that it should receive the data (assuming that the application and/or the user has indicated the data should be received).
The application should use Exchange Manager functions to receive the data and store it or do whatever it needs to with the data. Specifically, most applications should respond to this launch code by calling ExgAccept to accept the connection and then ExgReceive to receive the data.
Note that the application may not be the active application, and thus may not have globals available when it is launched with this launch code. You can check if you have globals by using this code in the PilotMain routine:
Boolean appIsActive = launchFlags & sysAppLaunchFlagSubCall;
The appIsActive value is true if your application is active and globals are available; otherwise, you won't be able to access any of your global variables during the receive operation.
The parameter block sent with this launch code is a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is arriving. Pass this pointer to the ExgAccept function to begin receiving the data. For more details, refer to the "Exchange Manager" chapter.
This launch code is used to implement the global find. When the user enters a text string in the Find dialog, the system sends this launch code with the FindParamsType parameter block to each application. The application should search for the string that the user entered and return any records matching the find request.
The system displays the results of the query in the Find results dialog. The system continues the search with each application until it has a full screen of matching records or until all of the applications on the device have had a chance to respond. If the screen is full, a Find More button appears at the bottom of the dialog. If the user clicks the Find More button, the search resumes. Applications can test whether the current find is a continuation of a previous one by checking the continuation field in the parameter block.
Most applications that use text records should support this launch code. When they receive it, they should search all records for matches to the find string and return all matches. Functions that you can use to respond to this launch code are described in Chapter 10, "Find."
An application can also integrate the find operation in its own user interface and send the launch code to a particular application.
Applications that support this launch code should support sysAppLaunchCmdSaveData and sysAppLaunchCmdGoto as well.
typedef struct { UInt16 dbAccesMode; UInt16 recordNum; Boolean more; Char strAsTyped [maxFindStrLen+1]; Char strToFind [maxFindStrLen+1]; UInt8 reserved1; UInt16 numMatches; UInt16 lineNumber; Boolean continuation; Boolean searchedCaller; LocalID callerAppDbID; UInt16 callerAppCardNo; LocalID appDbID; UInt16 appCardNo; Boolean newSearch; UInt8 reserved2; DmSearchStateType searchState; FindMatchType match [maxFinds]; } FindParamsType;
dbAccesMode | Mode in which to open the application's database. Pass this directly to DmOpenDatabase as the mode parameter. Its value is either dmModeReadOnly or dmModeReadOnly | dmModeShowSecret. (See "Open Mode Constants" for more information.) |
recordNum | Index of last record that contained a match. Start the search from this location. Do not set this value directly. Instead, call FindSaveMatch when you have a matching record. |
more | If true, the Find results dialog displays the Find More button indicating that there may be more results to display. |
Typically FindSaveMatch handles setting the more field. Applications with large databases to search may want to periodically check for and stop the search if an event is pending. If so, they should set this field to true before stopping. |
strAsTyped | Search string as the user entered it. |
strToFind | Normalized version of the search string. The method by which a search string is normalized varies depending on the version of Palm OS and the character encoding supported by the device. You pass strToFind directly to the search function (either FindStrInStr, TxtFindString, or TxtGlueFindString). |
reserved1 | Reserved for future use. |
numMatches | The current number of matches. Do not set this field directly. Instead, call FindSaveMatch, which increments it for you. |
lineNumber | Line number of the next line that displays the results. Do not set this field directly. It is incremented by a call to FindDrawHeader. |
continuation | If true, the launch code is being sent as part of a continuation of a previous Find. If false, this is a new Find. Do not set this field directly; the system sets it when the Find results dialog is full. |
searchedCaller | If true, the application that was active at the time the user tapped the Find button has responded to this launch code. This application is always searched before any others. |
callerAppDbID | Database ID of the application that was active when the user tapped the Find button. Do not change the value of this field; the system sets it and uses it when searching for application databases. |
callerAppCardNo | Card number of the application that was active when the user tapped the Find button. Do not change the value of this field; the system sets it and uses it when searching for application databases. |
appDbID | The ID of your application's resource database. Do not set this field directly; the system sets it and uses it when searching for application databases. |
appCardNo | The card number of your application's resource database. Do not set this field directly; the system sets it and uses it when searching for application databases. |
newSearch | System use only. |
reserved2 | Reserved for future use. |
searchState | System use only. |
match | System use only. |
Sent in conjunction with sysAppLaunchCmdFind or sysAppLaunchCmdExgReceiveData to allow users to actually inspect the record that the global find returned or that was received by the Exchange Manager.
Applications should do most of the normal launch actions, then display the requested item. The application should continue running unless explicitly closed.
An application launched with this code does have access to global variables, static local variables, and code segments other than segment 0 (in multi-segment applications).
Applications that receive this launch code should test the sysAppLaunchFlagNewGlobals launch flag to see if they need to initialize global variables. sysAppLaunchFlagNewGlobals indicates that the system has just allocated your global variables.
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.
typedef struct { Int16 searchStrLen; UInt16 dbCardNo; LocalID dbID; UInt16 recordNum; UInt16 matchPos; UInt16 matchFieldNum; UInt32 matchCustom; } GoToParamsType;
searchStrLen | Length of normalized search string. This is not the length of the matching string. See below for a full explanation. |
dbCardNo | Card number of the database to open. |
dbID | Local ID of the database to open. |
recordNum | Index of record containing a match. |
matchPos | Position of the match within the field. |
matchFieldNum | Field number string was found in. |
matchCustom | Application-specific information. |
Often, applications highlight the search string when displaying the resulting record. Localizable applications commonly store the length of the string to select in the matchCustom field for this purpose. Some multi-byte character encodings represent certain characters both as a single-byte character and a multi-byte character. When the search is performed, the single-byte character is accurately matched against its multi-byte equivalent. For this reason, the length of the string searched for does not always equal the length of the matching string. Applications that support being localized to multi-byte character sets often set the matchCustom field to the length of the matching string in the call to FindSaveMatch so that they know the length of the string to select.
Applications can respond to this launch code to retrieve and display the specified URL.
The parameter block for this launch command is simply a pointer to a string containing the URL.
This launch code may be sent in the following instances:
If the Wireless Internet Feature Set is, applications can send this launch code directly to the Web Clipping Application Viewer application.
If 4.0 New Feature Set is present, the ExgRequest function launches an application with this launch code if it cannot find an exchange library that is registered for the URL it has received. To receive the launch code, the application must first use ExgRegisterDatatype to register for a URL scheme.
This launch code is sent by the Desktop Link server in response to a request to create a database. It is sent to the application whose creator ID matches that of the requested database.
The most frequent occurrence of this is when a 'data' database is being installed or restored from the desktop. In this case, HotSync creates a new database on the device and passes it to the application via a sysAppLaunchCmdInitDatabase command, so that the application can perform any required initialization. HotSync will then transfer the records from the desktop database to the device database.
When a Palm OS application crashes while a database is installed using HotSync, the reason may be that the application is not handling the sysAppLaunchCmdInitDatabase command properly. Be especially careful not to access global variables.
The system will create a database and pass it to the application for initialization. The application must perform any initialization required, then pass the database back to the system, unclosed.
typedef struct { DmOpenRef dbP; UInt32 creator; UInt32 type; UInt16 version; } SysAppLaunchCmdInitDatabaseType;
dbP | Database reference. |
creator | Database creator. |
type | Database type. |
version | Database version. |
The system or an application sends this launch command to retrieve information from another application. In contrast to Find, there is a level of indirection; for example, this launch code could be used to retrieve the phone number based on input of a name.
This functionality is currently supported by the standard Palm OS Address Book.
Applications that decide to handle this launch code must search their database for the string the user entered and perform the match operation specified in the launch code's parameter block.
If an application wants to allow its users to perform lookup in other applications, it has to send it properly, including all information necessary to perform the match. An example for this is in Address.c and AppLaunchCmd.h, which are included in your SDK.
The parameter block is defined by the application that supports this launch code. See AppLaunchCmd.h for an example.
The system or an application sends this launch code to notify applications that an event has occurred. The parameter block specifies the type of event that occurred, as well as other pertinent information. To learn which notifications are broadcast by the system, see the chapter titled "Notifications" in this book.
The SysNotifyParamType structure declared in NotifyMgr.h defines the format of this launch code's parameter block. See its description in the "Notifications" chapter.
You can send this launch code to the Web Clipping Application Viewer application to launch the application and cause it to open and display a PalmTM query application stored on the device. This is the same mechanism that the Launcher uses to launch query applications.
typedef struct { UInt16 cardNo; LocalID dbID; } SysAppLaunchCmdOpenDBType;
cardNo | Card number of database to open. |
dbID | Database id of database to open. |
sysAppLaunchCmdPanelCalledFromApp and sysAppLaunchCmdReturnFromPanel allow an application to let users change preferences without switching to the Preferences application. For example, for the calculator, you may launch the Formats preferences panel, set up a number format preference, then directly return to the calculator that then uses the new format.
sysAppLaunchCmdPanelCalledFromApp lets a preferences panel know whether it was switched to from the Preferences application or whether an application invoked it to make a change. The panel may be a preference panel owned by the application or a system preferences panel.
Examples of these system panels that may handle this launch code are:
Network panel (called from network applications)
Modem panel (called if modem selection is necessary)
All preferences panels must handle this launch code. If a panel is launched with this command, it should:
Display a Done button.
Not display the panel-switching pop-up trigger used for navigation within the preferences application.
This launch code is used in conjunction with sysAppLaunchCmdPanelCalledFromApp. It informs an application that the user is done with a called preferences panel. The system passes this launch code to the application when a previously-called preferences panel exists.
Instructs the application to save all current data. For example, before the system performs a global find, an application should save all data.
Any application that supports the Find command and that can have buffered data should support this launch code. The system sends this launch code to the currently active application before it begins the search. The application receiving this launch code should respond by saving all buffered data so that the search is able to find matches in the text just entered.
typedef struct { Boolean uiComing; UInt8 reserved1; } SysAppLaunchCmdSaveDataType;
uiComing | true if the system dialog is displayed before launch code arrives. |
reserved1 | Reserved for future use. |
This launch code is sent to applications to inform them that a HotSync operation has occurred.
This launch code is sent only to applications whose databases were changed during the HotSync operation. (Installing the application database itself is considered a change.) The record database(s) must have the same creator ID as the application in order for the system to know which application to send the launch code to.
This launch code provides a good opportunity to update, initialize, or validate the application's new data, such as resorting records, setting alarms, and so on.
Because applications only receive sysAppLaunchCmdSyncNotify when their databases are updated, this launch code is not a good place to perform any operation that must occur after every HotSync operation. Instead, you may register to receive the sysNotifySyncFinishEvent on systems that have the Notification Feature Set. This notification is sent at the end of a HotSync operation, and it is sent to all applications registered to receive it, whether the application's data changed or not. Note that there is also a sysNotifySyncStartEvent notification.
Launch code sent to the system-internal security application to lock the device.
As a rule, applications don't need to do respond to this launch code. If an application replaces the system-internal security application, it must handle this launch code.
Launch code to respond to system soft or hard reset.
Applications can respond to this launch code by performing initialization, indexing, or other setup that they need to do when the system is reset. For more information about resetting the device, see "System Boot and Reset" in the Palm OS Programmer's Companion, vol. I.
typedef struct { Boolean hardReset; Boolean createDefaultDB; } SysAppLaunchCmdSystemResetType;
hardReset | true if system was hardReset. false if system was softReset. |
createDefaultDB | If true, application has to create default database. |
Launch code to respond to a time change initiated by the user.
Applications that are dependent on the current time or date need to respond to this launch code. For example, an application that sets alarms may want to cancel an alarm or set a different one if the system time changes.
On systems that have the Notification Feature Set, applications should register to receive the sysNotifyTimeChangeEvent notification instead of responding to this launch code. The sysAppLaunchCmdTimeChange launch code is sent to all applications. The sysNotifyTimeChangeEvent notification is sent only to applications that have specifically registered to receive it, making it more efficient than sysAppLaunchCmdTimeChange.
This launch code is sent from the Web Clipping Application Viewer application to launch another application.
The parameter block consists of a pointer to a special URL string, which the application must know how to parse. The string is the URL used to launch the application and may contain encoded parameters.
An application launched with this code may or may not have access to global variables, static local variables, and code segments other than segment 0 (in multi-segment applications). It depends on the URL that caused the Web Clipping Application Viewer to send this launch code. If this launch code results from a palm URL, then globals are available. If the launch code results from a palmcall URL, then globals are not available.
The best way to test if you have global variable access is to test the sysAppLaunchFlagNewGlobals launch flag sent with this launch code. If this is flag is set, then you have global variable access.
When an application is launched with any launch command, it also is passed a set of launch flags.
An application may decide to ignore the flags even if it handles the launch code itself. For applications that decide to use the launch flags, the following table provides additional information:
|