IAppManager.LaunchApp()

Description:

The LaunchApp method launches an application based on a unique ID for the application (UID). It also provides a way to open a specific document (by specifying a document path), even if it is not the default file type for the application being launched. For example, you can specify a path to a document with a .txt extension to open in WordPad, even though Notepad is the default application for .txt files.

The application can be launched as chained (embedded) or stand-alone. For more information about embedded and stand-alone applications, see section Accessing and launching installed applications.

This method can be called both synchronously and asynchronously.

Syntax:

For synchronous calls:

result = so.IAppManager.LaunchApp(criteria);

For asynchronous calls:

result = so.IAppManager.LaunchApp(criteria, callback);

Arguments:

criteria:

This is an object that specifies which application to launch. For more information about the object properties and how to define them, see section Criteria for launching an application.
callback:

The callback argument is the name of the method that is executed when an asynchronous LaunchApp call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.

This argument is used only with an asynchronous LaunchApp call.

Return value:

If synchronous, the LaunchApp method returns an object that contains an error code and an error message.

**Table:** Return value properties for a synchronous LaunchApp
Property	Description	Value
`result.ErrorCode`	This is a number that specifies a predefined error code.	See Service API error codes.
`result.ErrorMessage`	This is a text string that describes the error.	See AppManager Service API error messages.

If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).

Note: If Cancel is called on an ongoing asynchronous request, LaunchApp will not return a notification when the launched application terminates.

**Table:** Return value properties for an asynchronous LaunchApp
Property	Description	Value
`result.TransactionID`	This is a number used as an identification to match transactions started with the asynchronous `LaunchApp` call to one or more calls it generates to `callback`.
`result.ErrorCode`	This is a number that specifies a predefined error code.	See Service API error codes.
`result.ErrorMessage`	This is a text string that describes the error.	See AppManager Service API error messages.

Remarks:

Use the GetList method to retrieve the unique ID of the application to launch.

Example code:

For the complete source of a sample widget that demonstrates how to use this Service API, see the full example.