The LaunchReturn extension provides functions that help you restart your application after the user leaves your app to run another program. LaunchReturn can be instructed to 'listen' for the starting and stopping of another app, and can relaunch your app when the other app is closed.

LaunchReturn is only functional on PalmOS 5.x devices.  It will not work on older PalmOS devices because they do not broadcast the system notifications needed to make LaunchReturn work.  You must also install the LaunchReturnHelper.prc file on the device in addition to the SFE_LaunchReturn.prc file.

The Normal mode will listen for the starting of another app, then the closing of that app, and will then relaunch your app when the other app closes.  An example would be if the user switched over to the Calendar application.  When the user closed the Calendar app (perhaps by pressing the Home button to go to the App Launcher), your SatForms app would be relaunched instead.

A Special mode is also available, for use in the case where the Normal mode is not effective.  The Normal mode may not be effective when doing things like creating an outgoing email message in Versamail, or creating an outgoing text message, or answering an incoming phone call on a Treo, for example.  The Special mode relaunches your app after it detects that the second external app has been launched (after the first external app was started and then closed).

As well, for Treo smartphones there are some additional features that can help manage your application when there is an incoming phone call.  If you instruct LaunchReturn to listen for incoming phone calls, it will log the time when an incoming call was detected.  You can check for this incoming call log, and prepare LaunchReturn in Special mode if a call was detected.  That way, when the user closes the Phone application, your app will be automatically restarted.  Unfortunately, this incoming call detection is only effective on the Treo 650 and 700 devices, not on the Treo 600.

A function is also provided to detect whether the device is a Treo 600, 650, 700, or not.

For a demonstration of how to use LaunchReturn, see the LaunchReturnTest.sfa sample project.

Usage:

• PrepLaunchReturn - Prepare to return to our app after switching to other app.

       USAGE: PrepLaunchReturn( AppToReturnToCreatorID, AppReturnEventMode )

       AppToReturnToCreatorID is the four-character creatorID string of the app to relaunch.

       AppReturnEventMode should be 0 for Normal mode (AppStart-->AppStop--Relaunch) or 1 for Special mode (AppStart-->Relaunch)

• UnprepLaunchReturn - Cancel preparation to return to our app after switching to other app.

       USAGE: UnprepLaunchReturn()

• LaunchApp - Launch app via specified creatorID.

       

       USAGE: LaunchApp( AppToLaunchCreatorID )

NOTE: You do not have to use this function to launch another app; you can use any other means to launch another app.  This function is here for convenience.

• PrepIncomingCall - Prepare to listen for incoming call notifications.

       USAGE: PrepIncomingCall()

NOTE: This listening will remain in effect even after your app is closed, unless you call UnprepIncomingCall when your app closes (which is recommended).

• UnprepIncomingCall - Cancel preparation to listen for incoming call notifications.

       USAGE: UnprepIncomingCall()\nStops listening for incoming phone calls.

• CheckIncomingCall - Check to see if there is an incoming phone call.

       USAGE: result = CheckIncomingCall()

Returns 0 if no incoming call, or a non-zero number if there is an incoming call.  This non-zero number is the time in system time format that the incoming call was received (may or may not have been answered). The stored call time is cleared when you call this function.

• IsTreoPhone - Check if device is a Treo 600, 650, or 700, or not.

       USAGE: IsTreoPhone()

       Returns 0 if not a Treo, 600 if Treo 600, 650 if Treo 650, or 700 if Treo 700.

DocID: 10166  DocDate: 2006-10-02