Launch Services

Launch and open documents in other apps from your current app process.

Overview

macOS Launch Services is an API that enables a running application to open other applications or their document files in a way similar to the Finder or the Dock. Using Launch Services, an application can perform such tasks as:

  • Open (launch or activate) another application

  • Open a document or a URL (uniform resource locator) in another application

  • Identify the preferred application for opening a given document or URL

  • Register information about the kinds of document files and URLs an application is capable of opening

  • Obtain appropriate information for displaying a file or URL on the screen, such as its icon, display name, and kind string

  • Maintain and update the contents of the Recent Items menu

Although most of these services are normally performed by the Finder, other applications may also find them useful for purposes such as opening email attachments, following URLs embedded in a document, running helper applications, or opening embedded document components that were created by another application or require it for viewing or editing.

Many of Launch Services’ capabilities were formerly provided by the Desktop Manager. With the advent of Mac app bundles, however, the Desktop Manager has lost its usefulness, since it is not knowledgeable about bundled applications and simply ignores them. Similarly, Launch Services’ facilities for dealing with URLs were formerly implemented through the Internet Config API. Launch Services replaces and supersedes the Desktop Manager and Internet Config with a new API providing similar functionality, but designed to operate properly in the macOS environment.

Launch Services was created specifically to avoid the common need for applications to ask the Finder to open an application, document, or URL for them. In the past, opening such items in a way similar to the Finder required knowledge of several APIs, including the Desktop Manager, File Manager, Translation Manager, Internet Config, Process Manager, and Apple Event Manager. The Finder also had implicit knowledge of the desktop database and other information not available elsewhere for determining the correct application with which to open a given document.

Launch Services removes this specialized knowledge from the Finder and isolates it in a single, straightforward API available to any application. The macOS Finder itself uses Launch Services to open applications, documents, and URLs at the user’s request. Since the Finder does no additional processing beyond calling Launch Services, any client using Launch Services for these purposes is guaranteed to behave identically to the Finder itself.

Before reading this document, you should be familiar with the related document, Launch Services Programming Guide, which presents a conceptual overview of Launch Services and its operations.

Topics

Locating an Application

The functions described in this section locate the preferred application for opening a given item or family of items or the application matching a given set of defining characteristics, or test whether an application can open a designated item.

LSCopyDefaultApplicationURLForURL

Returns the application used to open an item.

LSGetApplicationForItem

Locates the preferred application for opening an item designated by file-system reference.

Deprecated
LSGetApplicationForURL

Locates the preferred application for opening an item designated by URL.

Deprecated
LSCopyDefaultApplicationURLForContentType

Returns the application used to open a content type (UTI).

LSGetApplicationForInfo

Locates the preferred application for opening items with a specified file type, creator signature, filename extension, or any combination of these characteristics.

Deprecated
LSCopyApplicationForMIMEType

Locates the preferred application for opening items with a specified MIME type.

Deprecated
LSCopyApplicationURLsForURL

Locates all known applications suitable for opening an item designated by the specified URL.

LSCanURLAcceptURL

Tests whether an application can accept (open) an item designated by URL.

LSCanRefAcceptItem

Tests whether an application can accept (open) an item designated by file-system reference.

Deprecated
LSCopyApplicationURLsForBundleIdentifier

Locates all URLs for applications that correspond to the specified bundle identifier.

LSFindApplicationForInfo

Locates an application with a specified creator signature, bundle ID, filename, or any combination of these characteristics.

Deprecated

Opening Items

The functions described in this section open a designated item or collection of items, or launch or activate a designated application.

LSOpenApplication

Launches the specified application.

Deprecated
LSOpenItemsWithRole

Opens items specified as an array of values of type FSRef with a specified role.

Deprecated
LSOpenURLsWithRole

Opens one or more URLs with the specified roles.

Deprecated
LSOpenFSRef

Opens an item designated by file-system reference, in the default manner in its preferred application.

Deprecated
LSOpenFromRefSpec

Opens one or more items designated by file-system reference, in either their preferred applications or a designated application.

Deprecated
LSOpenCFURLRef

Opens an item designated by URL, in the default manner in its preferred application.

LSOpenFromURLSpec

Opens one or more items designated by URL, in either their preferred applications or a designated application.

Obtaining Information About an Item

The functions described in this section obtain requested information about an item.

LSCopyItemInfoForRef

Obtains requested information about an item designated by file-system reference.

Deprecated
LSCopyItemInfoForURL

Obtains requested information about an item designated by URL.

Deprecated
LSCopyDisplayNameForRef

Obtains the display name for an item designated by file-system reference.

Deprecated
LSCopyDisplayNameForURL

Obtains the display name for an item designated by URL.

Deprecated
LSCopyKindStringForRef

Obtains the kind string for an item designated by file-system reference.

Deprecated
LSCopyKindStringForURL

Obtains the kind string for an item designated by URL.

Deprecated
LSCopyKindStringForTypeInfo

Obtains a kind string for items with a specified file type, creator signature, filename extension, or any combination of these characteristics.

Deprecated
LSCopyKindStringForMIMEType

Obtains the kind string for a specified MIME type.

Deprecated
LSCopyItemAttribute

Obtains the value of an item’s attribute.

Deprecated
LSCopyItemAttributes

Obtains multiple item attribute values as a dictionary.

Deprecated

Getting and Setting Filename Extension Information

The functions described in this section obtain information about an item’s filename extension, or control whether the extension should be hidden or shown on the screen.

LSGetExtensionInfo

Obtains the starting index of the extension within a filename.

Deprecated
LSSetExtensionHiddenForRef

Specifies whether the filename extension for an item designated by file-system reference should be hidden or shown.

Deprecated
LSSetExtensionHiddenForURL

Specifies whether the filename extension for an item designated by URL should be hidden or shown.

Deprecated

Registering an Application

The functions described in this section register an application in the Launch Services database.

LSRegisterURL

Registers an application, designated by URL, in the Launch Services database.

LSRegisterFSRef

Registers an application, designated by file-system reference, in the Launch Services database.

Deprecated

Working With Role Handlers

The functions described in this section get and set application bundle identifiers for handlers of specified content types and URL schemes.

LSCopyAllRoleHandlersForContentType

Locates an array of application bundle identifiers for applications capable of handling a specified content type with the specified roles.

LSCopyDefaultRoleHandlerForContentType

Returns the application bundle identifier of the user’s preferred default handler for the specified content type with the specified role.

LSSetDefaultRoleHandlerForContentType

Sets the user’s preferred default handler for the specified content type in the specified roles.

LSGetHandlerOptionsForContentType

Gets the handler options for the specified content type.

Deprecated
LSSetHandlerOptionsForContentType

Sets the handler option for the specified content type.

Deprecated
LSCopyAllHandlersForURLScheme

Locates application bundle identifiers for applications capable of handling the specified URL scheme.

Deprecated
LSCopyDefaultHandlerForURLScheme

Returns the application bundle identifier of the user’s preferred default handler for the specified URL scheme.

Deprecated
LSSetDefaultHandlerForURLScheme

Sets the user’s preferred default handler for the specified URL scheme.

Data Types

This section describes the data types defined in the Launch Services API.

LSApplicationParameters

Specifies the application, launch flags, and additional parameters that control how an application is launched.

Deprecated
LSLaunchFSRefSpec

Specifies, by file-system reference, an application to launch, items to open, or both, along with related information.

Deprecated
LSLaunchURLSpec

Specifies, by URL, an application to launch, items to open, or both, along with related information.

LSItemInfoRecord

Contains requested information about an item.

Deprecated

Constants

This section describes the constants defined in the Launch Services API.

LSRolesMask

Specify the desired role or roles for an application to claim with respect to an item or family of items.

LSLaunchFlags

Specify how to launch an application.

LSRequestedInfo

Specify what information to obtain about an item.

Item Attribute Constants

Constants used to retrieve item attributes.

LSItemInfoFlags

Provide information about an item.

LSAcceptanceFlags

Specify behavior to observe when testing whether an application can accept (open) an item.

LSHandlerOptions

Specify the options for controlling how content handlers are selected.

Invalid Extension Index

Represents an invalid filename extension index.

Unknown Type or Creator

Represent an unknown file type or creator.

Constants No Longer Used

The following constants are no longer used.

Result Codes

The table below lists the most common result codes returned by Launch Services functions.

kLSAppInTrashErr

The application cannot be run because it is inside a Trash folder.

kLSUnknownErr

An unknown error has occurred.

kLSNotAnApplicationErr

The item to be registered is not an application.

kLSNotInitializedErr

Formerly returned by LSInit on initialization failure; no longer used.

kLSDataUnavailableErr

Data of the desired type is not available (for example, there is no kind string).

kLSApplicationNotFoundErr

No application in the Launch Services database matches the input criteria.

kLSUnknownTypeErr

Not currently used.

kLSDataTooOldErr

Not currently used.

kLSDataErr

Data is structured improperly (for example, an item’s information property list is malformed). Not used in macOS 10.4.

kLSLaunchInProgressErr

A launch of the application is already in progress.

kLSNotRegisteredErr

Not currently used.

kLSAppDoesNotClaimTypeErr

Not currently used.

kLSServerCommunicationErr

There is a problem communicating with the server process that maintains the Launch Services database.

kLSCannotSetInfoErr

The filename extension to be hidden cannot be hidden.

kLSNoRegistrationInfoErr

Not currently used.

kLSIncompatibleSystemVersionErr

The application to be launched cannot run on the current Mac OS version.

kLSNoLaunchPermissionErr

The user does not have permission to launch the application (on a managed network).

kLSNoExecutableErr

The executable file is missing or has an unusable format.

kLSNoClassicEnvironmentErr

The Classic emulation environment was required but is not available.

kLSMultipleSessionsNotSupportedErr

The application to be launched cannot run simultaneously in two different user sessions.

See Also