Launch Services

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

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.

Symbols

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.

func LSGetApplicationForItem(UnsafePointer<FSRef>!, LSRolesMask, UnsafeMutablePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFURL>?>!)

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

Deprecated
func LSGetApplicationForURL(CFURL!, LSRolesMask, UnsafeMutablePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFURL>?>!)

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

Deprecated
func LSGetApplicationForInfo(OSType, OSType, CFString!, LSRolesMask, UnsafeMutablePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFURL>?>!)

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

Deprecated
func LSCopyApplicationForMIMEType(CFString!, LSRolesMask, UnsafeMutablePointer<Unmanaged<CFURL>?>!)

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

Deprecated
func LSCopyApplicationURLsForURL(CFURL, LSRolesMask)

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

func LSCanURLAcceptURL(CFURL, CFURL, LSRolesMask, LSAcceptanceFlags, UnsafeMutablePointer<DarwinBoolean>)

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

func LSCanRefAcceptItem(UnsafePointer<FSRef>!, UnsafePointer<FSRef>!, LSRolesMask, LSAcceptanceFlags, UnsafeMutablePointer<DarwinBoolean>!)

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

Deprecated
func LSCopyApplicationURLsForBundleIdentifier(CFString, UnsafeMutablePointer<Unmanaged<CFError>?>?)

Returns all URLs for the application that corresponds to a bundle identifier.

func LSFindApplicationForInfo(OSType, CFString!, CFString!, UnsafeMutablePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFURL>?>!)

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.

func LSOpenFSRef(UnsafePointer<FSRef>!, UnsafeMutablePointer<FSRef>!)

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

Deprecated
func LSOpenFromRefSpec(UnsafePointer<LSLaunchFSRefSpec>!, UnsafeMutablePointer<FSRef>!)

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

Deprecated
func LSOpenCFURLRef(CFURL, UnsafeMutablePointer<Unmanaged<CFURL>?>?)

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

func LSOpenFromURLSpec(UnsafePointer<LSLaunchURLSpec>, UnsafeMutablePointer<Unmanaged<CFURL>?>?)

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.

func LSCopyItemInfoForRef(UnsafePointer<FSRef>!, LSRequestedInfo, UnsafeMutablePointer<LSItemInfoRecord>!)

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

Deprecated
func LSCopyItemInfoForURL(CFURL!, LSRequestedInfo, UnsafeMutablePointer<LSItemInfoRecord>!)

Obtains requested information about an item designated by URL.

Deprecated
func LSCopyDisplayNameForRef(UnsafePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

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

Deprecated
func LSCopyDisplayNameForURL(CFURL!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

Obtains the display name for an item designated by URL.

Deprecated
func LSCopyKindStringForRef(UnsafePointer<FSRef>!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

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

Deprecated
func LSCopyKindStringForURL(CFURL!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

Obtains the kind string for an item designated by URL.

Deprecated
func LSCopyKindStringForTypeInfo(OSType, OSType, CFString!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

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

Deprecated
func LSCopyKindStringForMIMEType(CFString!, UnsafeMutablePointer<Unmanaged<CFString>?>!)

Obtains the kind string for a specified MIME type.

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.

func LSGetExtensionInfo(Int, UnsafePointer<UniChar>!, UnsafeMutablePointer<Int>!)

Obtains the starting index of the extension within a filename.

Deprecated
func LSSetExtensionHiddenForRef(UnsafePointer<FSRef>!, Bool)

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

Deprecated
func LSSetExtensionHiddenForURL(CFURL!, Bool)

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.

func LSRegisterURL(CFURL, Bool)

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

func LSRegisterFSRef(UnsafePointer<FSRef>!, Bool)

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.

func LSCopyAllRoleHandlersForContentType(CFString, LSRolesMask)

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

func LSCopyDefaultRoleHandlerForContentType(CFString, LSRolesMask)

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

func LSSetDefaultRoleHandlerForContentType(CFString, LSRolesMask, CFString)

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

func LSGetHandlerOptionsForContentType(CFString!)

Gets the handler options for the specified content type.

Deprecated
func LSSetHandlerOptionsForContentType(CFString!, LSHandlerOptions)

Sets the handler option for the specified content type.

Deprecated
func LSCopyAllHandlersForURLScheme(CFString)

Returns an array of application bundle identifiers for applications capable of handling the specified URL scheme.

func LSCopyDefaultHandlerForURLScheme(CFString)

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

func LSSetDefaultHandlerForURLScheme(CFString, CFString)

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.

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.

var kLSAppInTrashErr: OSStatus

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

var kLSUnknownErr: OSStatus

An unknown error has occurred.

var kLSNotAnApplicationErr: OSStatus

The item to be registered is not an application.

var kLSNotInitializedErr: OSStatus

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

var kLSDataUnavailableErr: OSStatus

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

var kLSApplicationNotFoundErr: OSStatus

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

var kLSDataErr: OSStatus

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

var kLSLaunchInProgressErr: OSStatus

A launch of the application is already in progress.

var kLSServerCommunicationErr: OSStatus

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

var kLSCannotSetInfoErr: OSStatus

The filename extension to be hidden cannot be hidden.

var kLSIncompatibleSystemVersionErr: OSStatus

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

var kLSNoLaunchPermissionErr: OSStatus

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

var kLSNoExecutableErr: OSStatus

The executable file is missing or has an unusable format.

var kLSNoClassicEnvironmentErr: OSStatus

The Classic emulation environment was required but is not available.

var kLSMultipleSessionsNotSupportedErr: OSStatus

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