Launch Services Reference

Overview

OS X 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 OS X 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 OS X 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.

Functions by Task

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

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.

• LSGetApplicationForItem
• LSGetApplicationForURL
• LSGetApplicationForInfo
• LSCopyApplicationForMIMEType
• LSCopyApplicationURLsForURL
• LSCanRefAcceptItem
• LSCanURLAcceptURL
• LSFindApplicationForInfo

Opening Items

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

• LSOpenApplication
• LSOpenItemsWithRole
• LSOpenURLsWithRole
• LSOpenFSRef
• LSOpenFromRefSpec
• LSOpenCFURLRef
• LSOpenFromURLSpec

Obtaining Information About an Item

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

• LSCopyItemInfoForRef
• LSCopyItemInfoForURL
• LSCopyDisplayNameForRef
• LSCopyDisplayNameForURL
• LSCopyKindStringForRef
• LSCopyKindStringForURL
• LSCopyKindStringForTypeInfo
• LSCopyKindStringForMIMEType
• LSCopyItemAttribute
• LSCopyItemAttributes

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
• LSSetExtensionHiddenForRef
• LSSetExtensionHiddenForURL

Registering an Application

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

• LSRegisterFSRef
• LSRegisterURL

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
• LSCopyDefaultRoleHandlerForContentType
• LSSetDefaultRoleHandlerForContentType
• LSGetHandlerOptionsForContentType
• LSSetHandlerOptionsForContentType
• LSCopyAllHandlersForURLScheme
• LSCopyDefaultHandlerForURLScheme
• LSSetDefaultHandlerForURLScheme

Functions No Longer Used

The functions described in this section are no longer used.

• LSInit Deprecated in OS X v10.3
• LSTerm Deprecated in OS X v10.3

Functions

LSCanRefAcceptItem

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

OSStatus LSCanRefAcceptItem (
   const FSRef *inItemFSRef,
   const FSRef *inTargetRef,
   LSRolesMask inRoleMask,
   LSAcceptanceFlags inFlags,
   Boolean *outAcceptsItem
);

LSCanURLAcceptURL

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

OSStatus LSCanURLAcceptURL (
   CFURLRef inItemURL,
   CFURLRef inTargetURL,
   LSRolesMask inRoleMask,
   LSAcceptanceFlags inFlags,
   Boolean *outAcceptsItem
);

LSCopyAllHandlersForURLScheme

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

CFArrayRef LSCopyAllHandlersForURLScheme (
   CFStringRef inURLScheme
);

LSCopyAllRoleHandlersForContentType

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

CFArrayRef LSCopyAllRoleHandlersForContentType (
   CFStringRef inContentType,
   LSRolesMask inRole
);

LSCopyApplicationForMIMEType

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

OSStatus LSCopyApplicationForMIMEType (
   CFStringRef inMIMEType,
   LSRolesMask inRoleMask,
   CFURLRef *outAppURL
);

LSCopyApplicationURLsForURL

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

CFArrayRef LSCopyApplicationURLsForURL (
   CFURLRef inURL,
   LSRolesMask inRoleMask
);

LSCopyDefaultHandlerForURLScheme

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

CFStringRef LSCopyDefaultHandlerForURLScheme (
   CFStringRef inURLScheme
);

LSCopyDefaultRoleHandlerForContentType

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

CFStringRef LSCopyDefaultRoleHandlerForContentType (
   CFStringRef inContentType,
   LSRolesMask inRole
);

LSCopyDisplayNameForRef

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

OSStatus LSCopyDisplayNameForRef (
   const FSRef *inRef,
   CFStringRef *outDisplayName
);

LSCopyDisplayNameForURL

Obtains the display name for an item designated by URL.

OSStatus LSCopyDisplayNameForURL (
   CFURLRef inURL,
   CFStringRef *outDisplayName
);

LSCopyItemAttribute

Obtains the value of an item’s attribute.

OSStatus LSCopyItemAttribute (
   const FSRef *inItem,
   LSRolesMask inRoles,
   CFStringRef inAttributeName,
   CFTypeRef *outValue
);

LSCopyItemAttributes

Obtains multiple item attribute values as a dictionary.

OSStatus LSCopyItemAttributes (
   const FSRef *inItem,
   LSRolesMask inRoles,
   CFArrayRef inAttributeNames,
   CFDictionaryRef *outValues
);

LSCopyItemInfoForRef

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

OSStatus LSCopyItemInfoForRef (
   const FSRef *inItemRef,
   LSRequestedInfo inWhichInfo,
   LSItemInfoRecord *outItemInfo
);

LSCopyItemInfoForURL

Obtains requested information about an item designated by URL.

OSStatus LSCopyItemInfoForURL (
   CFURLRef inURL,
   LSRequestedInfo inWhichInfo,
   LSItemInfoRecord *outItemInfo
);

LSCopyKindStringForMIMEType

Obtains the kind string for a specified MIME type.

OSStatus LSCopyKindStringForMIMEType (
   CFStringRef inMIMEType,
   CFStringRef *outKindString
);

LSCopyKindStringForRef

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

OSStatus LSCopyKindStringForRef (
   const FSRef *inFSRef,
   CFStringRef *outKindString
);

LSCopyKindStringForTypeInfo

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

OSStatus LSCopyKindStringForTypeInfo (
   OSType inType,
   OSType inCreator,
   CFStringRef inExtension,
   CFStringRef *outKindString
);

LSCopyKindStringForURL

Obtains the kind string for an item designated by URL.

OSStatus LSCopyKindStringForURL (
   CFURLRef inURL,
   CFStringRef *outKindString
);

LSFindApplicationForInfo

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

OSStatus LSFindApplicationForInfo (
   OSType inCreator,
   CFStringRef inBundleID,
   CFStringRef inName,
   FSRef *outAppRef,
   CFURLRef *outAppURL
);

LSGetApplicationForInfo

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

OSStatus LSGetApplicationForInfo (
   OSType inType,
   OSType inCreator,
   CFStringRef inExtension,
   LSRolesMask inRoleMask,
   FSRef *outAppRef,
   CFURLRef *outAppURL
);

LSGetApplicationForItem

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

OSStatus LSGetApplicationForItem (
   const FSRef *inItemRef,
   LSRolesMask inRoleMask,
   FSRef *outAppRef,
   CFURLRef *outAppURL
);

LSGetApplicationForURL

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

OSStatus LSGetApplicationForURL (
   CFURLRef inURL,
   LSRolesMask inRoleMask,
   FSRef *outAppRef,
   CFURLRef *outAppURL
);

LSGetExtensionInfo

Obtains the starting index of the extension within a filename.

OSStatus LSGetExtensionInfo (
   UniCharCount inNameLen,
   const UniChar inNameBuffer[],
   UniCharCount *outExtStartIndex
);

LSGetHandlerOptionsForContentType

Gets the handler options for the specified content type.

LSHandlerOptions LSGetHandlerOptionsForContentType (
   CFStringRef inContentType
);

LSOpenApplication

Launches the specified application.

OSStatus LSOpenApplication (
   const LSApplicationParameters *appParams,
   ProcessSerialNumber *outPSN
);

LSOpenCFURLRef

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

OSStatus LSOpenCFURLRef (
   CFURLRef inURL,
   CFURLRef *outLaunchedURL
);

LSOpenFromRefSpec

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

OSStatus LSOpenFromRefSpec (
   const LSLaunchFSRefSpec *inLaunchSpec,
   FSRef *outLaunchedRef
);

LSOpenFromURLSpec

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

OSStatus LSOpenFromURLSpec (
   const LSLaunchURLSpec *inLaunchSpec,
   CFURLRef *outLaunchedURL
);

LSOpenFSRef

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

OSStatus LSOpenFSRef (
   const FSRef *inRef,
   FSRef *outLaunchedRef
);

LSOpenItemsWithRole

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

OSStatus LSOpenItemsWithRole (
   const FSRef *inItems,
   CFIndex inItemCount,
   LSRolesMask inRole,
   const AEKeyDesc *inAEParam,
   const LSApplicationParameters *inAppParams,
   ProcessSerialNumber *outPSNs,
   CFIndex inMaxPSNCount
);

LSOpenURLsWithRole

Opens one or more URLs with the specified roles.

OSStatus LSOpenURLsWithRole (
   CFArrayRef inURLs,
   LSRolesMask inRole,
   const AEKeyDesc *inAEParam,
   const LSApplicationParameters *inAppParams,
   ProcessSerialNumber *outPSNs,
   CFIndex inMaxPSNCount
);

LSRegisterFSRef

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

OSStatus LSRegisterFSRef (
   const FSRef *inRef,
   Boolean inUpdate
);

LSRegisterURL

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

OSStatus LSRegisterURL (
   CFURLRef inURL,
   Boolean inUpdate
);

LSSetDefaultHandlerForURLScheme

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

OSStatus LSSetDefaultHandlerForURLScheme (
   CFStringRef inURLScheme,
   CFStringRef inHandlerBundleID
);

LSSetDefaultRoleHandlerForContentType

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

OSStatus LSSetDefaultRoleHandlerForContentType (
   CFStringRef inContentType,
   LSRolesMask inRole,
   CFStringRef inHandlerBundleID
);

LSSetExtensionHiddenForRef

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

OSStatus LSSetExtensionHiddenForRef (
   const FSRef *inRef,
   Boolean inHide
);

LSSetExtensionHiddenForURL

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

OSStatus LSSetExtensionHiddenForURL (
   CFURLRef inURL,
   Boolean inHide
);

LSSetHandlerOptionsForContentType

Sets the handler option for the specified content type.

OSStatus LSSetHandlerOptionsForContentType (
   CFStringRef inContentType,
   LSHandlerOptions inOptions
);

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.

struct LSApplicationParameters {
   CFIndex version;
   LSLaunchFlags flags;
   const FSRef * application;
   void * asyncLaunchRefCon;
   CFDictionaryRef environment;
   CFArrayRef argv;
   AppleEvent * initialEvent
};
typedef struct LSApplicationParameters LSApplicationParameters;

Fields

version

The version of the structure. The value of this field must be 0.

flags

Launch flags. For possible values, see “Launch Flags.”

application

The FSRef of the application to open.

asyncLaunchRefCon

The client refCon that is to appear in subsequent launch notifications.

environment

A dictionary of CFStringRef keys and values for environment variables to set in the launched process. The value of this field can be NULL.

argv

An array of values of type CFStringRef that specify the arguments that are to be passed to main() in the launched process. The value of this field can be NULL. This field is ignored in OS X v10.4.

initialEvent

The first Apple Event to send to the launched process. The value of this field can be NULL.

LSLaunchFSRefSpec

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

struct LSLaunchFSRefSpec {
   const FSRef *appRef;
   UInt32 numDocs;
   const FSRef *itemRefs;
   const AEDesc *passThruParams;
   LSLaunchFlags launchFlags;
   void *asyncRefCon;
};
typedef struct LSLaunchFSRefSpec LSLaunchFSRefSpec;

Fields

appRef

A pointer to a file-system reference designating the application to launch; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Set this field to NULL to request that each item in the itemRefs array be opened in its own preferred application.

numDocs

The number of elements in the array specified by the itemRefs field. The value of this field can be 0, in which case the application designated by appRef is launched without opening any items.

itemRefs

An array of file-system references designating the item or items to open. If the value of numDocs is 0, this field is ignored and can be set to NULL.

passThruParams

A pointer to an Apple event descriptor that is passed untouched as an optional parameter, with keyword keyAEPropData ('prdt'), in the Apple event sent to each application launched or activated (whether individual preferred applications or the application designated by appRef). See the Apple Event Manager Reference in the Carbon Interapplication Communication Documentation for a description of the AEDesc data type. The value of this field can be NULL.

launchFlags

Launch flags specifying how to launch each application (including whether to print or merely open documents); see “Launch Flags” for a description of these flags.

asyncRefCon

A pointer to an arbitrary application-defined value, passed in the Carbon event notifying you of an application’s launch or termination (if you have registered for such notification). The value of this field can be NULL.

LSLaunchURLSpec

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

struct LSLaunchURLSpec {
   CFURLRef appURL;
   CFArrayRef itemURLs;
   const AEDesc *passThruParams;
   LSLaunchFlags launchFlags;
   void *asyncRefCon;
};
typedef struct LSLaunchURLSpec LSLaunchURLSpec;

Fields

appURL

A Core Foundation URL reference designating the application to launch; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. The URL must have scheme file and contain a valid path to an application file or application bundle. Set this field to NULL to request that each item in the itemURLs array be opened in its own preferred application.

itemURLs

A reference to an array of Core Foundation URL references designating the item or items to open; see the CFArray Reference in the Core Foundation Reference Documentation for a description of the CFArrayRef data type. The value of this field can be NULL, in which case the application designated by appURL will be launched without opening any items.

passThruParams

A pointer to an Apple event descriptor that is passed untouched as an optional parameter, with keyword keyAEPropData ('prdt'), in the Apple event sent to each application launched or activated (whether individual preferred applications or the application designated by appURL). See the Apple Event Manager Reference in the Carbon Interapplication Communication Documentation for a description of the AEDesc data type. The value of this field can be NULL.

launchFlags

Launch flags specifying how to launch each application (including whether to print or merely open documents); see “Launch Flags” for a description of these flags.

asyncRefCon

A pointer to an arbitrary application-defined value, passed in the Carbon event notifying you of an application’s launch or termination (if you have registered for such notification). The value of this field can be NULL.

LSItemInfoRecord

Contains requested information about an item.

struct LSItemInfoRecord {
   LSItemInfoFlags flags;
   OSType filetype;
   OSType creator;
   CFStringRef extension;
   CFStringRef iconFileName;
   LSKindID kindID;
};
typedef struct LSItemInfoRecord LSItemInfoRecord;

Fields

flags

Item-information flags specifying information about the item; see “Item-Information Flags” for a description of these flags.

filetype

The item’s file type.

creator

The item’s creator signature.

extension

A Core Foundation string object specifying the item’s filename extension; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type.

iconFileName

No longer used.

kindID

No longer used.

LSKindID

Data type of the kindID field of an item-information record (LSItemInfoRecord); no longer used.

typedef UInt32 LSKindID;

Constants

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

Roles Mask

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

typedef OptionBits LSRolesMask;enum {
   kLSRolesNone = 0x00000001,
   kLSRolesViewer = 0x00000002,
   kLSRolesEditor = 0x00000004,
   kLSRolesShell = 0x00000008,
   kLSRolesAll = 0xFFFFFFFF
};

Constants

kLSRolesNone

Requests the role None (the application cannot open the item, but provides an icon and a kind string for it).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRolesViewer

Requests the role Viewer (the application can read and present the item, but cannot manipulate or save it).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRolesEditor

Requests the role Editor (the application can read, present, manipulate, and save the item).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRolesShell

Requests the role Shell (the application can execute the item).

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSRolesAll

Accepts any role with respect to the item.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

Launch Flags

Specify how to launch an application.

typedef OptionBits LSLaunchFlags;enum {
   kLSLaunchDefaults = 0x00000001,
   kLSLaunchAndPrint = 0x00000002,
   kLSLaunchReserved2 = 0x00000004,
   kLSLaunchReserved3 = 0x00000008,
   kLSLaunchReserved4 = 0x00000010,
   kLSLaunchReserved5 = 0x00000020,
   kLSLaunchAndDisplayErrors = 0x00000040,
   kLSLaunchInhibitBGOnly = 0x00000080,
   kLSLaunchDontAddToRecents = 0x00000100,
   kLSLaunchDontSwitch = 0x00000200,
   kLSLaunchNoParams = 0x00000800,
   kLSLaunchAsync = 0x00010000,
   kLSLaunchStartClassic = 0x00020000,
   kLSLaunchInClassic = 0x00040000,
   kLSLaunchNewInstance = 0x00080000,
   kLSLaunchAndHide = 0x00100000,
   kLSLaunchAndHideOthers = 0x00200000,
   kLSLaunchHasUntrustedContents = 0x00400000
};

Constants

kLSLaunchDefaults

Requests launching in the default manner (as if the only flags set were kLSLaunchNoParams, kLSLaunchAsync, and kLSLaunchStartClassic).

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchAndPrint

Requests that documents opened in the application be printed.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchReserved2

Reserved for future use.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchReserved3

Reserved for future use.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchReserved4

Reserved for future use.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchReserved5

Reserved for future use.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchAndDisplayErrors

Requests that launch and open failures be displayed in the UI.

Available in OS X v10.4 and later.

Declared in LSOpen.h.

kLSLaunchInhibitBGOnly

Requests that the launch be made to fail if the application is background-only.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchDontAddToRecents

Requests that the application or documents not be added to the Finder’s Recent Items menu.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchDontSwitch

Requests that the application be launched without being brought to the foreground.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchNoParams

Requests that the application’s information property list be used to determine the launch parameters.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchAsync

Requests that the application be launched asynchronously: that is, the Launch Services function launching it return control immediately, without waiting for it to complete its launch sequence (indicated visually to the user when the application’s icon stops “bouncing” in the Dock).

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchStartClassic

Requests that the Classic emulation environment be started up if the application requires it. If this flag is not set and the application requires the Classic environment, the launch will fail.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchInClassic

Requests that the application be forced to launch in the Classic emulation environment.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchNewInstance

Requests that a new instance of the application be started, even if one is already running.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchAndHide

Requests that the application be hidden as soon as it completes its launch sequence.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchAndHideOthers

Requests that other applications be hidden as soon as the opened application completes its launch sequence.

Available in OS X v10.0 and later.

Declared in LSOpen.h.

kLSLaunchHasUntrustedContents

Requests that the items to be launched should be marked as untrusted.

Available in OS X v10.4 and later.

Declared in LSOpen.h.

Requested-Information Flags

Specify what information to obtain about an item.

typedef OptionBits LSRequestedInfo;enum {
   kLSRequestExtension = 0x00000001,
   kLSRequestTypeCreator = 0x00000002,
   kLSRequestBasicFlagsOnly = 0x00000004,
   kLSRequestAppTypeFlags = 0x00000008,
   kLSRequestAllFlags = 0x00000010,
   kLSRequestIconAndKind = 0x00000020,
   kLSRequestExtensionFlagsOnly = 0x00000040,
   kLSRequestAllInfo = 0xFFFFFFFF
};

Constants

kLSRequestExtension

Requests the item’s filename extension.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestTypeCreator

Requests the item’s file type and creator signature.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestBasicFlagsOnly

Requests all item-information flags that are not application-specific: that is, all except kLSItemInfoIsNativeApp through kLSItemInfoAppIsScriptable.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestAppTypeFlags

Requests all application-specific item-information flags: that is, kLSItemInfoIsNativeApp through kLSItemInfoAppIsScriptable.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestAllFlags

Requests all item-information flags.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestIconAndKind

Not used.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSRequestExtensionFlagsOnly

Requests only the kLSItemInfoExtensionIsHidden item-information flag.

Available in OS X v10.1 and later.

Declared in LSInfo.h.

kLSRequestAllInfo

Requests all available item information.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

Item Attribute Constants

Constants used to retrieve item attributes.

const CFStringRef kLSItemContentType;
const CFStringRef kLSItemFileType;
const CFStringRef kLSItemFileCreator;
const CFStringRef kLSItemExtension;
const CFStringRef kLSItemDisplayName
const CFStringRef kLSItemDisplayKind;
const CFStringRef kLSItemRoleHandlerDisplayName;
const CFStringRef kLSItemIsInvisible;
const CFStringRef kLSItemExtensionIsHidden;

Constants

kLSItemContentType

The item’s content type identifier, which is a uniform type identifier string. The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemFileType

The item’s file type (OSType). The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemFileCreator

The item’s file creator (OSType). The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemExtension

The item’s filename extension. The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemDisplayName

The item’s name as displayed to the user. The display name reflects localization and extension hiding that may be in effect. The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemDisplayKind

The localized kind string describing the item’s type. The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemRoleHandlerDisplayName

The display name of the application that is set to handle this item, subject to the role mask. The value type of this attribute is CFStringRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemIsInvisible

A value of kCFBooleanTrue if the item is normally hidden from users; otherwise, kCFBooleanFalse. The value type of this attribute is CFBooleanRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSItemExtensionIsHidden

A value of kCFBooleanTrue if the item’s extension is set to be hidden; otherwise, kCFBooleanFalse. The value type of this attribute is CFBooleanRef.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

Item-Information Flags

Provide information about an item.

typedef OptionBits LSItemInfoFlags;enum {
   kLSItemInfoIsPlainFile = 0x00000001,
   kLSItemInfoIsPackage = 0x00000002,
   kLSItemInfoIsApplication = 0x00000004,
   kLSItemInfoIsContainer = 0x00000008,
   kLSItemInfoIsAliasFile = 0x00000010,
   kLSItemInfoIsSymlink = 0x00000020,
   kLSItemInfoIsInvisible = 0x00000040,
   kLSItemInfoIsNativeApp = 0x00000080,
   kLSItemInfoIsClassicApp = 0x00000100,
   kLSItemInfoAppPrefersNative = 0x00000200,
   kLSItemInfoAppPrefersClassic = 0x00000400,
   kLSItemInfoAppIsScriptable = 0x00000800,
   kLSItemInfoIsVolume = 0x00001000,
   kLSItemInfoExtensionIsHidden = 0x00100000
};

Constants

kLSItemInfoIsPlainFile

Item is a data file (and not, for example, a directory, volume, or UNIX symbolic link).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsPackage

Item is a packaged directory.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsApplication

Item is a single-file or packaged application.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsContainer

Item is a directory (includes packages) or volume.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsAliasFile

Item is an alias file (includes symbolic links).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsSymlink

Item is a UNIX symbolic link.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsInvisible

Item is invisible, because either its name begins with a period or its isInvisible Finder flag is set.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsNativeApp

Item is an application that can run natively in OS X.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsClassicApp

Item is an application that cannot run natively and must be launched in the Classic emulation environment.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoAppPrefersNative

Item is an application that can run either natively or in the Classic emulation environment, but prefers to be launched natively. This flag is valid only when kLSItemInfoIsNativeApp is set.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoAppPrefersClassic

Item is an application that can run either natively or in the Classic emulation environment, but prefers to be launched in the Classic environment. This flag is valid only when kLSItemInfoIsNativeApp is set.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoAppIsScriptable

Item is an application that can be scripted.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoIsVolume

Item is the root directory of a volume or mount point.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSItemInfoExtensionIsHidden

Item has a hidden filename extension.

Available in OS X v10.1 and later.

Declared in LSInfo.h.

Acceptance Flags

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

typedef OptionBits LSAcceptanceFlags;enum {
   kLSAcceptDefault = 0x00000001,
   kLSAcceptAllowLoginUI = 0x00000002
};

Constants

kLSAcceptDefault

Requests the default behavior (as opposed to the behavior specified by the kLSAcceptAllowLoginUI flag).

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSAcceptAllowLoginUI

Requests that the user interface to log in be presented if necessary. If LSCanRefAcceptItem or LSCanURLAcceptURL is called during a drag-and-drop operation, showing a server login dialog would be an inappropriate user experience. If the target designated in the function call is an alias to an application, Launch Services needs to resolve the alias to ascertain what file types the application can open; however, if the application is on a server that needs to be authenticated, Launch Services will by default fail to resolve the alias, to avoid having to present the login interface. To override this default behavior by allowing the server login interface, set the kLSAcceptAllowLoginUI flag.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

Handler Option Constants

Specify the options for controlling how content handlers are selected.

typedef OptionBits LSHandlerOptions;enum {
   kLSHandlerOptionsDefault = 0,
   kLSHandlerOptionsIgnoreCreator = 1
};

Constants

kLSHandlerOptionsDefault

When set, causes Launch Services to use a content item’s creator (when available) to select a handler. This is the default setting.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

kLSHandlerOptionsIgnoreCreator

When set, causes Launch Services to ignore the content item’s creator when selecting a role handler for the specified content type.

Available in OS X v10.4 and later.

Declared in LSInfo.h.

Invalid Extension Index

Represents an invalid filename extension index.

enum {
   kLSInvalidExtensionIndex = 0xFFFFFFFF
};

Constants

kLSInvalidExtensionIndex

The value obtained by the LSGetExtensionInfo function if the filename does not contain a valid extension.

Available in OS X v10.1 through OS X v10.4.

Declared in LSInfo.h.

Unknown Type or Creator

Represent an unknown file type or creator.

enum {
   kLSUnknownType = 0,
   kLSUnknownCreator = 0
};

Constants

kLSUnknownType

The value to supply as the file type (for example, to the LSGetApplicationForInfo function) if no file type information is available.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSUnknownCreator

The value to supply as the creator signature if no file creator information is available.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

Constants No Longer Used

The following constants are no longer used.

typedef OptionBits LSInitializeFlags;enum {
   kLSInitializeDefaults = 0x00000001
};enum {
   kLSUnknownKindID = 0
};enum {
   kLSMinCatInfoBitmap = (kFSCatInfoNodeFlags | kFSCatInfoParentDirID
| kFSCatInfoFinderInfo | kFSCatInfoFinderXInfo)
};

Constants

kLSInitializeDefaults

Formerly passed to the LSInit function, which is no longer used.

Available in OS X v10.0 and later.

Declared in LSInfo.h.

kLSUnknownKindID

A possible value of the kindID field of an item-information record, which is no longer used.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in LSInfo.h.

kLSMinCatInfoBitmap

A minimal catalog information bitmap; no longer used.

Available in OS X v10.1 and later.

Declared in LSInfo.h.

Result Codes

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