Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Launch Services Reference

Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
LSInfo.h
LSOpen.h

Overview

Mac 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:

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

Opening Items

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

Obtaining Information About an Item

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

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.

Registering an Application

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

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.

Functions No Longer Used

The functions described in this section are no longer used.

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
);

Parameters
inItemFSRef

A pointer to a file-system reference designating the source item (the item to test for acceptance by the target application); see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

inTargetFSRef

A pointer to a file-system reference designating the target application; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

inRolesMask

A bit mask specifying the target application’s desired role or roles with respect to the source item; see “Roles Mask” for a description of this mask. If the role is unimportant, pass kLSRolesAll.

inFlags

Flags specifying behavior to observe during the acceptance test; see “Acceptance Flags” for a description of these flags.

outAcceptsItem

A pointer to a Boolean value that, on return, will indicate whether the target application can accept the source item with at least one of the specified roles.

Return Value

A result code; see “Launch Services Result Codes.”

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

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
);

Parameters
inItemURL

A Core Foundation URL reference designating the source item (the item to test for acceptance by the target application); see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type.

inTargetURL

A Core Foundation URL reference designating the target application; 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.

inRolesMask

A bit mask specifying the target application’s desired role or roles with respect to the source item; see “Roles Mask” for a description of this mask. This parameter applies only to URLs with a scheme component of file, and is ignored for all other schemes. If the role is unimportant, pass kLSRolesAll.

inFlags

Flags specifying behavior to observe during the acceptance test; see “Acceptance Flags” for a description of these flags.

outAcceptsItem

A pointer to a Boolean value that, on return, will indicate whether the target application can accept the source item with at least one of the specified roles.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

If the item URL’s scheme is file (designating either a file or a directory), the acceptance test is based on the designated item’s filename extension, file type, and creator signature, along with the role specified by the inRolesMask parameter; otherwise, it is based on the URL scheme (such as http, ftp, or mailto).

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyAllHandlersForURLScheme

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

CFArrayRef LSCopyAllHandlersForURLScheme (
   CFStringRef inURLScheme
);

Parameters
inURLScheme

The URL scheme for which the application bundle identifiers are to be returned.

Return Value

An array containing the application bundle identifiers for applications capable of handling the URL scheme specified by inURLScheme, or NULL if no handlers are available.

Discussion

This function returns all of the application bundle identifiers that are capable of handling the specified URL scheme.

URL handling capability is determined according to the value of the CFBundleURLTypes key in an application’s Info.plist. For information on the CFBundleURLTypes key, see the section “CFBundleURLTypes” in Mac OS X Runtime Configuration Guidelines.

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

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
);

Parameters
inContentType

The content type. The content type is a uniform type identifier (UTI).

inRole

The role. Pass kLSRolesAll if any role is acceptable. For additional possible values, see “Roles Mask.”

Return Value

The application bundle identifiers for applications capable of handling the specified content type in the specified roles, or NULL if no handlers are available.

Discussion

This function returns all of the application bundle identifiers that are capable of handling the specified content type in the specified roles.

The CFBundleDocumentTypes key in an application’s Info.plist can be used to set an application’s content handling capabilities. The LSItemContentTypes key is particularly useful because it supports the use of UTIs in document claims. For information on the CFBundleDocumentTypes key, see the section “CFBundleDocumentTypes” in Mac OS X Runtime Configuration Guidelines.

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

LSCopyApplicationForMIMEType

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

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

Parameters
inMIMEType

A Core Foundation string object specifying the MIME type to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. Comparison of MIME types is case-insensitive.

inRolesMask

A bit mask specifying the application’s desired role or roles with respect to items with the specified MIME type; see “Roles Mask” for a description of this mask. If the role is unimportant, pass kLSRolesAll.

outAppURL

A pointer to a Core Foundation URL reference that, on return, will identify the preferred application for items with the specified MIME type; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. You are responsible for releasing the URL reference object.

Return Value

A result code; see “Launch Services Result Codes.” If no application suitable for opening items with the specified MIME type is found in the Launch Services database, the function will return the result code kLSApplicationNotFoundErr.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyApplicationURLsForURL

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

CFArrayRef LSCopyApplicationURLsForURL (
   CFURLRef inURL,
   LSRolesMask inRoleMask
);

Parameters
inURL

A Core Foundation URL reference designating the item for which all suitable applications are requested; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type.

inRolesMask

A bit mask specifying the applications’ desired role or roles with respect to the designated item; see “Roles Mask” for a description of this mask. This parameter applies only to URLs with a scheme component of file, and is ignored for all other schemes. If the role is unimportant, pass kLSRolesAll.

Return Value

An array of Core Foundation URL references, one for each application that can open the designated item with at least one of the specified roles. You are responsible for releasing the array object. If no suitable applications are found in the Launch Services database, the function will return NULL

Discussion

If the item URL’s scheme is file (designating either a file or a directory), the selection of suitable applications is based on the designated item’s filename extension, file type, and creator signature, along with the role specified by the inRolesMask parameter; otherwise, it is based on the URL scheme (such as http, ftp, or mailto).

Version Notes

Thread-safe since Mac OS version 10.3.

Availability
Declared In
LSInfo.h

LSCopyDefaultHandlerForURLScheme

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

CFStringRef LSCopyDefaultHandlerForURLScheme (
   CFStringRef inURLScheme
);

Parameters
inURLScheme

The URL scheme for which the application bundle identifier is to be returned.

Return Value

The application bundle identifier of the specified URL scheme.

Discussion

This function returns the user’s currently preferred default handler for the specified URL scheme.

URL handling capability is determined according to the value of the CFBundleURLTypes key in an application’s Info.plist. For information on the CFBundleURLTypes key, see the section “CFBundleURLTypes” in Mac OS X Runtime Configuration Guidelines.

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

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
);

Parameters
inContentType

The content type. The content type is a uniform type identifier (UTI).

inRole

The role. Pass kLSRolesAll if any role is acceptable. For additional possible values, see “Roles Mask.”

Return Value

The application bundle identifier of the default handler for the specified content type in the specified roles, or NULL if no handler is available.

Discussion

This function returns the user’s currently preferred default handler for the specified content type. Say, for example, that LSSetDefaultRoleHandlerForContentType has been used to set “com.Apple.TextEdit” for the “public.xml” content type. When a file whose content type is “public.xml” is double-clicked, TextEdit will be launched to open the file. If you call LSCopyDefaultRoleHandlerForContentType (CFSTR("public.xml"), kLSRolesAll), the string com.apple.TextEdit is returned.

The CFBundleDocumentTypes key in an application’s Info.plist can be used to set an application’s content handling capabilities. The LSItemContentTypes key is particularly useful because it supports the use of UTIs in document claims. For information on the CFBundleDocumentTypes key, see the section “CFBundleDocumentTypes” in Mac OS X Runtime Configuration Guidelines.

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

LSCopyDisplayNameForRef

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

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

Parameters
inRef

A pointer to a file-system reference designating the item whose display name is requested; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

outDisplayName

A pointer to a Core Foundation string object that, on return, will contain the item’s display name; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The item’s display name is returned in the form in which it will appear on the user’s screen; it may be localized (for applications and folders), and it excludes the filename extension if the extension is set to be hidden and the Finder preference to always show extensions is not enabled.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyDisplayNameForURL

Obtains the display name for an item designated by URL.

OSStatus LSCopyDisplayNameForURL (
   CFURLRef inURL,
   CFStringRef *outDisplayName
);

Parameters
inFileURL

A Core Foundation URL reference designating the item whose display name is requested; 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 either a file or a directory.

outDisplayName

A pointer to a Core Foundation string object that, on return, will contain the item’s display name; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The item’s display name is returned in the form in which it will appear on the user’s screen; it may be localized (for applications and folders), and it excludes the filename extension if the extension is set to be hidden and the Finder preference to always show extensions is not enabled.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyItemAttribute

Obtains the value of an item’s attribute.

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

Parameters
inItem

The FSRef of the item to query.

inRoles

The roles. When obtaining attributes related to document binding (such as kLSItemRoleHandlerDisplayName), at least one of the roles must be provided by the application selected. Pass kLSRolesAll if any role is acceptable.

inAttributeName

The name of the attribute to copy. For possible values, see “Item Attribute Constants.”

outValue

A pointer to a CFTypeRef. On return, the CFTypeRef is set to the copied attribute value (a CF object), or is NULL if an error occurs. The type of the returned object varies depending on the attribute that is requested.

Return Value

A result code; see “Launch Services Result Codes.”

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

LSCopyItemAttributes

Obtains multiple item attribute values as a dictionary.

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

Parameters
inItem

The FSRef of the item to query.

inRoles

The roles. When obtaining attributes related to document binding (such as kLSItemRoleHandlerDisplayName), at least one of the roles must be provided by the application selected. Pass kLSRolesAll if any role is acceptable.

inAttributeNames

A CFArrayRef for an array containing the attribute names to copy. For possible values, see “Item Attribute Constants.”

outValues

On return, a pointer a CFDictionaryRef for a dictionary whose keys are the attribute names specified by the inAttributeNames parameter and whose values are the attribute’s values. The CFTypeID of each value in the dictionary varies by attribute. See “Item Attribute Constants” for the data type of each value. If the item does not have a specified attribute, the key for the attribute is not in the dictionary.

Return Value

A result code; see “Launch Services Result Codes.”

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

LSCopyItemInfoForRef

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

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

Parameters
inItemRef

A pointer to a file-system reference designating the item about which information is requested; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

inWhichInfo

Flags specifying what information to obtain; see “Requested-Information Flags” for a description of these flags.

outItemInfo

A pointer to an item-information record that, on return, will contain the requested information; see “LSItemInfoRecord” for a description of this structure.

If you request the item’s filename extension (field extension of the item-information record, requested by flag kLSRequestExtension), you are responsible for releasing the Core Foundation string object in which the extension is returned.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The information obtained about an item can include its filename extension, file type, creator signature, and various item-information flags (indicating, for example, whether the item is an application, or whether it has a hidden extension); see “Item-Information Flags” for a description of these flags.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyItemInfoForURL

Obtains requested information about an item designated by URL.

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

Parameters
inFileURL

A Core Foundation URL reference designating the item about which information is requested; 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 either a file or a directory.

inWhichInfo

Flags specifying what information to obtain; see “Requested-Information Flags” for a description of these flags.

outItemInfo

A pointer to an item-information record that, on return, will contain the requested information; see “LSItemInfoRecord” for a description of this structure.

If you request the item’s filename extension (field extension of the item-information record, requested by flag kLSRequestExtension), you are responsible for releasing the Core Foundation string object in which the extension is returned.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The information obtained about an item can include its filename extension, file type, creator signature, and various item-information flags (indicating, for example, whether the item is an application, or whether it has a hidden extension); see “Item-Information Flags” for a description of these flags.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyKindStringForMIMEType

Obtains the kind string for a specified MIME type.

OSStatus LSCopyKindStringForMIMEType (
   CFStringRef inMIMEType,
   CFStringRef *outKindString
);

Parameters
inMIMEType

A Core Foundation string object specifying the MIME type whose kind string is requested; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. Comparison of MIME types is case-insensitive.

outKindString

A pointer to a Core Foundation string object that, on return, will contain the kind string for the specified MIME type; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The kind string (which may be localized) is obtained from the preferred application for opening items of the specified the MIME type, if one is found in the Launch Services database; otherwise, a more generic kind string is chosen.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSCopyKindStringForRef

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

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

Parameters
inFSRef

A pointer to a file-system reference designating the item whose kind string is requested; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

outKindString

A pointer to a Core Foundation string object that, on return, will contain the item’s kind string; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The kind string (which may be localized) is obtained from the item’s preferred application, if one is found in the Launch Services database; otherwise, a more generic kind string is chosen. For example, the kind string might be FrameMaker Document, or just Document if the item is a document for which no application is found.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

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
);

Parameters
inType

The file type to consider. Comparison of file types is case-sensitive. Pass kLSUnknownType if the items’ file type is unimportant.

inCreator

The creator signature to consider. Comparison of creator signatures is case-sensitive. Pass kLSUnknownCreator if the items’ creator signature is unimportant.

inExtension

A Core Foundation string object specifying the filename extension to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. Comparison of filename extensions is case-insensitive. Pass NULL if the items’ filename extension is unimportant.

outKindString

A pointer to a Core Foundation string object that, on return, will contain the requested kind string; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

This function obtains the kind string that most closely describes items having the specified characteristics. It is useful when you want to display the kind string for a document you do not yet have (such as an email attachment).

You can request any combination of one, two, or all three of the characteristics specified by the inType, inCreator, and inExtension parameters; at least one of these characteristics must be supplied. The kind string (which may be localized) is obtained from the preferred application for opening such items, if one is found in the Launch Services database; otherwise, a more generic kind string is chosen. For example, the kind string might be FrameMaker Document, or just Document if no suitable application is found.

Note that since the choice of a preferred application is subject to any document binding preferences the user may have set, the kind string will not necessarily be obtained from the default application that matches the specified creator signature (if any), but may instead be taken from a user-specified application that overrides the default. For example, if the user has specified that files of type 'PDF ' and creator 'ACRO' should be opened in the Preview application rather than in Acrobat, the kind string for this combination of characteristics will be that defined for 'PDF ' files by Preview and not by Acrobat.

Version Notes

Thread-safe since Mac OS version 10.2

Availability
Declared In
LSInfo.h

LSCopyKindStringForURL

Obtains the kind string for an item designated by URL.

OSStatus LSCopyKindStringForURL (
   CFURLRef inURL,
   CFStringRef *outKindString
);

Parameters
inURL

A Core Foundation URL reference designating the item whose kind string is requested; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type.

outKindString

A pointer to a Core Foundation string object that, on return, will contain the item’s kind string; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. You are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The kind string (which may be localized) is obtained from the item’s preferred application, if one is found in the Launch Services database; otherwise, a more generic kind string is chosen. For example, the kind string might be FrameMaker Document, or just Document if the item is a document for which no application is found. If the item URL’s scheme is file (designating either a file or a directory), the selection of the preferred application is based on the designated item’s filename extension, file type, and creator signature; otherwise, it is based on the URL scheme (such as http, ftp, or mailto).

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

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
);

Parameters
inCreator

The creator signature to consider. Comparison of creator signatures is case-sensitive. Pass kLSUnknownCreator if the application’s creator signature is unimportant.

inBundleID

A Core Foundation string object specifying the bundle ID to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. Comparison of bundle IDs is case-insensitive. Pass NULL if the application’s bundle ID is unimportant.

inName

A Core Foundation string object specifying the filename to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. The string must include any extension (such as '.app') that is part of the filename. Comparison of filenames is case-insensitive. Pass NULL if the application’s filename is unimportant.

outAppRef

A pointer to a file-system reference that, on return, will identify the requested application; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Pass NULL if you are not interested in identifying the application in this form; however, this parameter and outAppURL cannot both be NULL.

outAppURL

A pointer to a Core Foundation URL reference that, on return, will identify the requested application; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. Pass NULL if you are not interested in identifying the application in this form; however, this parameter and outAppRef cannot both be NULL.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.” If no suitable application is found in the Launch Services database, the function will return the result code kLSApplicationNotFoundErr.

Discussion

You can request any combination of one, two, or all three of the characteristics specified by the inCreator, inBundleID, and inName parameters; at least one of these characteristics must be supplied. If more than one application is found matching the specified characteristics, Launch Services chooses one in the same manner as when locating the preferred application for opening an item.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

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
);

Parameters
inType

The file type to consider. Comparison of file types is case-sensitive. Pass kLSUnknownType if the items’ file type is unimportant.

inCreator

The creator signature to consider. Comparison of creator signatures is case-sensitive. Pass kLSUnknownCreator if the items’ creator signature is unimportant.

inExtension

A Core Foundation string object specifying the filename extension to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the CFStringRef data type. Comparison of filename extensions is case-insensitive. Pass NULL if the items’ filename extension is unimportant.

inRolesMask

A bit mask specifying the application’s desired role or roles with respect to items with the specified characteristics; see “Roles Mask” for a description of this mask. If the role is unimportant, pass kLSRolesAll.

outAppRef

A pointer to a file-system reference that, on return, will identify the preferred application for opening items with the specified characteristics; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppURL cannot both be NULL.

outAppURL

A pointer to a Core Foundation URL reference that, on return, will identify the preferred application for items with the specified characteristics; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppRef cannot both be NULL.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.” If no application suitable for opening items with the specified characteristics is found in the Launch Services database, the function will return the result code kLSApplicationNotFoundErr.

Discussion

You can request any combination of one, two, or all three of the characteristics specified by the inType, inCreator, and inExtension parameters; at least one of these characteristics must be supplied. Note that since the choice of a preferred application is subject to any document binding preferences the user may have set, the application chosen will not necessarily be the default application that matches the input characteristics, but may instead be a user-specified application that overrides the default.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

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
);

Parameters
inItemRef

A pointer to a file-system reference designating the item whose preferred application is requested; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

inRolesMask

A bit mask specifying the application’s desired role or roles with respect to the designated item; see “Roles Mask” for a description of this mask. If the role is unimportant, pass kLSRolesAll.

outAppRef

A pointer to a file-system reference that, on return, will identify the item’s preferred application; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppURL cannot both be NULL.

outAppURL

A pointer to a Core Foundation URL reference that, on return, will identify the item’s preferred application; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppRef cannot both be NULL.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.” If no application suitable for opening the item is found in the Launch Services database, the function will return the result code kLSApplicationNotFoundErr.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSGetApplicationForURL

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

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

Parameters
inURL

A Core Foundation URL reference designating the item whose preferred application is requested; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type.

inRolesMask

A bit mask specifying the application’s desired role or roles with respect to the designated item; see “Roles Mask” for a description of this mask. This parameter applies only to URLs with a scheme component of file, and is ignored for all other schemes. If the role is unimportant, pass kLSRolesAll.

outAppRef

A pointer to a file-system reference that, on return, will identify the item’s preferred application; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppURL cannot both be NULL.

outAppURL

A pointer to a Core Foundation URL reference that, on return, will identify the item’s preferred application; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. Pass NULL if you are not interested in identifying the preferred application in this form; however, this parameter and outAppRef cannot both be NULL.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.” If no application suitable for opening the item is found in the Launch Services database, the function will return the result code kLSApplicationNotFoundErr.

Discussion

If the item URL’s scheme is file (designating either a file or a directory), the selection of the preferred application is based on the designated item’s filename extension, file type, and creator signature, along with the role specified by the inRolesMask parameter; otherwise, it is based on the URL scheme (such as http, ftp, or mailto).

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSGetExtensionInfo

Obtains the starting index of the extension within a filename.

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

Parameters
inNameLen

The number of characters in the filename specified by the inNameBuffer parameter.

inNameBuffer

The buffer containing the filename’s Unicode characters.

outExtStartIndex

A pointer to a value of type UniCharCount that, on return, will give the starting index of the extension within the filename. If the name does not contain a valid extension (one with no spaces in it), the value on return will be kLSInvalidExtensionIndex.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The starting index is the number of Unicode characters from the start of the filename buffer to the first character of the extension (not including the period).

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSInfo.h

LSGetHandlerOptionsForContentType

Gets the handler options for the specified content type.

LSHandlerOptions LSGetHandlerOptionsForContentType (
   CFStringRef inContentType
);

Parameters
inContentType

The content type for which the handler options are to be obtained. The content type is a uniform type identifier (UTI).

Return Value

The handler option that is set for the specified content type. For possible values, see “Handler Option Constants.”

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSInfo.h

LSOpenApplication

Launches the specified application.

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

Parameters
inAppParams

A LSApplicationParameters structure specifying the application to launch and its launch parameters. This parameter cannot be NULL.

outPSN

On input, a pointer to a value of type ProcessSerialNumber that, on return, contains the process serial number (PSN) of the application specified by inAppParams, or NULL if you don’t want to receive the PSN.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The LSOpenApplication launches one application. This function is an updated alternative to the Process Manager's LaunchApplication function. Launch arguments are specified in the inAppParams argument, which must be supplied. If the application is already running in the current session, it is made the front process (unless the kLSLaunchNewInstance flag is used, which always causes a new process to be created).

If outPSN is not NULL, on return, the structure it points to contains the PSN of the launched (or activated) process. Note that for asynchronous launches, the application may not have finished launching when this function returns.

Version Notes

Thread-safe since Mac OS X v10.4.

Availability
Declared In
LSOpen.h

LSOpenCFURLRef

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

OSStatus LSOpenCFURLRef (
   CFURLRef inURL,
   CFURLRef *outLaunchedURL
);

Parameters
inURL

A Core Foundation URL reference designating the item to open; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type.

outLaunchedURL

A pointer to a Core Foundation URL reference that, on return, will identify the application launched. Pass NULL if this information is unimportant.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The designated item is opened in the default manner, as if it had been opened with the LSOpenFromURLSpec function with a launch specification specifying the launch flag kLSLaunchDefaults: that is, asynchronously, starting the Classic emulation environment if necessary, and with the remaining launch parameters taken from the application’s information property list. For greater control, call LSOpenFromURLSpec directly. See “Launch Flags” for more information about launch flags.

If the item URL’s scheme is file (designating either a file or a directory), the selection of the preferred application is based on the designated item’s filename extension, file type, and creator signature; otherwise, it is based on the URL scheme (such as http, ftp, or mailto). The application is launched or activated, as required, and sent an appropriate Apple event depending on the circumstances:

As of Mac OS X v10.4 and later, LSOpenURLsWithRole is the preferred way of opening a URL.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSOpen.h

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
);

Parameters
inLaunchSpec

A pointer to a file-based launch specification indicating what to open and how to launch the relevant application or applications; see “LSLaunchFSRefSpec” for a description of this structure.

outLaunchedRef

A pointer to a file-system reference that, on return, will identify the application launched; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type. Pass NULL if this information is unimportant. If more than one application is launched, the one identified will be the one corresponding to the first item designated in the launch specification.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

This function affords greater control of how items are opened or applications launched than is possible with the LSOpenFSRef function. For instance, you can use it to open multiple items in a single call, in either the same or different applications; open documents for printing rather than for simple viewing or editing; or force a document to open in an application other than its own preferred application.

The launch specification supplied for the inLaunchSpec parameter may designate an application to launch, items to open, or both. The relevant application or applications are launched or activated, as required, and sent an appropriate Apple event depending on the circumstances:

As of Mac OS X v10.4 and later, LSOpenItemsWithRole is the preferred way of opening items.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSOpen.h

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
);

Parameters
inLaunchSpec

A pointer to a URL-based launch specification indicating what to open and how to launch the relevant application or applications; see “LSLaunchURLSpec” for a description of this structure.

outLaunchedURL

A pointer to a Core Foundation URL reference that, on return, will identify the application launched; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the CFURLRef data type. Pass NULL if this information is unimportant. If more than one application is launched, the one identified will be the one corresponding to the first item designated in the launch specification.

Despite the absence of the word Copy in its name, this function retains the URL reference object on your behalf; you are responsible for releasing this object.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

This function affords greater control of how items are opened or applications launched than is possible with the LSOpenCFURLRef function. For instance, you can use it to open multiple items in a single call, in either the same or different applications; open documents for printing rather than for simple viewing or editing; or force a document to open in an application other than its own preferred application.

The launch specification supplied for the inLaunchSpec parameter may designate an application to launch, items to open, or both. The relevant application or applications are launched or activated, as required, and sent an appropriate Apple event depending on the circumstances:

As of Mac OS X v10.4 and later, LSOpenURLsWithRole is the preferred way of opening URLs.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSOpen.h

LSOpenFSRef

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

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

Parameters
inRef

A pointer to a file-system reference designating the item to open; see the File Manager Reference in the Carbon File Management Documentation for a description of the FSRef data type.

outLaunchedRef

A pointer to a file-system reference that, on return, will identify the application launched. Pass NULL if this information is unimportant.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

The designated item is opened in the default manner, as if it had been opened with the LSOpenFromRefSpec function with a launch specification specifying the launch flag kLSLaunchDefaults: that is, asynchronously, starting the Classic emulation environment if necessary, and with the remaining launch parameters taken from the application’s information property list. For greater control, call LSOpenFromRefSpec directly. See “Launch Flags” for more information about launch flags.

The application is launched or activated, as required, and sent an appropriate Apple event depending on the circumstances:

As of Mac OS X v10.4 and later, LSOpenItemsWithRole is the preferred way of opening an item.

Version Notes

Thread-safe since Mac OS version 10.2.

Availability
Declared In
LSOpen.h

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
);

Parameters
inItems

An array of values of type FSRef.

inItemCount

The number of items specified in inItems.

inRole

A value of type LSRolesMask specifying one or more roles. If the role doesn’t matter, use kLSRolesAll. For possible values, see “Roles Mask.” If the inAppParams parameter is not NULL, this parameter is ignored.

inAEParam

An AEKeyDesc that is to be attached to the Apple Event(s) generated by Launch Services with the specified AEKeyword. This parameter can be NULL.

inAppParams

An LSApplicationParameters structure specifying the application to launch and its launch parameters, in which case the inRole parameter is ignored. This parameter can be NULL, in which case an application is selected that can handle each input item in at least one of the roles specified by the inRole parameter.

outPSNs

On input, a pointer to a caller-allocated buffer or NULL if you don’t want to receive process serial number (PSN) information. If not NULL on input, on return, the buffer contains at each index the PSN that was used to open the item at the same index of the input item array (inItems).

inMaxPSNCount

The maximum number of PSNs that the buffer pointed to by outPSNs can hold.

Return Value

A result code; see “Launch Services Result Codes.”

Discussion

This function opens the specified items with the specified role. You can optionally specify the application and launch parameters in the inAppParams parameter. If an application is specified in the inAppParams parameter, the inRole parameter is ignored and the application is launched (if necessary).

Each application (regardless of whether it is launched or already running) receives an 'odoc' Apple Event specifying the items