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