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 LSGet​Application​For​Info(OSType, OSType, CFString!, LSRoles​Mask, Unsafe​Mutable​Pointer<FSRef>!, Unsafe​Mutable​Pointer<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 LSCopy​Application​For​MIMEType(CFString!, LSRoles​Mask, Unsafe​Mutable​Pointer<Unmanaged<CFURL>?>!)

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

Deprecated
func LSCopy​Application​URLs​For​URL(CFURL, LSRoles​Mask)

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

func LSFind​Application​For​Info(OSType, CFString!, CFString!, Unsafe​Mutable​Pointer<FSRef>!, Unsafe​Mutable​Pointer<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 LSOpen​FSRef(Unsafe​Pointer<FSRef>!, Unsafe​Mutable​Pointer<FSRef>!)

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

Deprecated
func LSOpen​From​Ref​Spec(Unsafe​Pointer<LSLaunch​FSRef​Spec>!, Unsafe​Mutable​Pointer<FSRef>!)

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

Deprecated
func LSOpen​CFURLRef(CFURL, Unsafe​Mutable​Pointer<Unmanaged<CFURL>?>?)

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

func LSOpen​From​URLSpec(Unsafe​Pointer<LSLaunch​URLSpec>, Unsafe​Mutable​Pointer<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 LSCopy​Display​Name​For​Ref(Unsafe​Pointer<FSRef>!, Unsafe​Mutable​Pointer<Unmanaged<CFString>?>!)

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

Deprecated
func LSCopy​Kind​String​For​Ref(Unsafe​Pointer<FSRef>!, Unsafe​Mutable​Pointer<Unmanaged<CFString>?>!)

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

Deprecated
func LSCopy​Kind​String​For​Type​Info(OSType, OSType, CFString!, Unsafe​Mutable​Pointer<Unmanaged<CFString>?>!)

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

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 LSGet​Extension​Info(Int, Unsafe​Pointer<Uni​Char>!, Unsafe​Mutable​Pointer<Int>!)

Obtains the starting index of the extension within a filename.

Deprecated
func LSSet​Extension​Hidden​For​Ref(Unsafe​Pointer<FSRef>!, Bool)

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

Deprecated
func LSSet​Extension​Hidden​For​URL(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 LSRegister​URL(CFURL, Bool)

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

func LSRegister​FSRef(Unsafe​Pointer<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 LSCopy​All​Role​Handlers​For​Content​Type(CFString, LSRoles​Mask)

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

func LSCopy​Default​Role​Handler​For​Content​Type(CFString, LSRoles​Mask)

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

func LSSet​Default​Role​Handler​For​Content​Type(CFString, LSRoles​Mask, CFString)

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

func LSGet​Handler​Options​For​Content​Type(CFString!)

Gets the handler options for the specified content type.

Deprecated
func LSSet​Handler​Options​For​Content​Type(CFString!, LSHandler​Options)

Sets the handler option for the specified content type.

Deprecated
func LSCopy​All​Handlers​For​URLScheme(CFString)

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

func LSCopy​Default​Handler​For​URLScheme(CFString)

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

func LSSet​Default​Handler​For​URLScheme(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.

LSApplication​Parameters

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

Deprecated
LSLaunch​FSRef​Spec

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

Deprecated
LSLaunch​URLSpec

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

LSItem​Info​Record

Contains requested information about an item.

Deprecated

Constants

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

LSRoles​Mask

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

LSLaunch​Flags

Specify how to launch an application.

LSRequested​Info

Specify what information to obtain about an item.

Item Attribute Constants

Constants used to retrieve item attributes.

LSItem​Info​Flags

Provide information about an item.

LSAcceptance​Flags

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

LSHandler​Options

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 k​LSApp​In​Trash​Err:​ OSStatus

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

var k​LSUnknown​Err:​ OSStatus

An unknown error has occurred.

var k​LSNot​An​Application​Err:​ OSStatus

The item to be registered is not an application.

var k​LSNot​Initialized​Err:​ OSStatus

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

var k​LSData​Unavailable​Err:​ OSStatus

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

var k​LSApplication​Not​Found​Err:​ OSStatus

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

var k​LSData​Err:​ OSStatus

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

var k​LSLaunch​In​Progress​Err:​ OSStatus

A launch of the application is already in progress.

var k​LSServer​Communication​Err:​ OSStatus

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

var k​LSCannot​Set​Info​Err:​ OSStatus

The filename extension to be hidden cannot be hidden.

var k​LSIncompatible​System​Version​Err:​ OSStatus

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

var k​LSNo​Launch​Permission​Err:​ OSStatus

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

var k​LSNo​Executable​Err:​ OSStatus

The executable file is missing or has an unusable format.

var k​LSNo​Classic​Environment​Err:​ OSStatus

The Classic emulation environment was required but is not available.

var k​LSMultiple​Sessions​Not​Supported​Err:​ OSStatus

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

See Also