Launch Services Reference
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.
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.
-
Returns the application used to open an item.
Declaration
Swift
func LSCopyDefaultApplicationURLForURL(_inURL: CFURL!, _inRoleMask: LSRolesMask, _outError: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFURL>!Objective-C
CFURLRef LSCopyDefaultApplicationURLForURL ( CFURLRef inURL, LSRolesMask inRoleMask, CFErrorRef *outError );Parameters
inURLThe URL of the item for which the application is requested.
inRoleMaskWhether to return the editor or viewer for
inURL. If you don't care which, usekLSRolesAll.outErrorOn failure, set to a
CFErrorRefdescribing the problem. If you are not interested in this information, passNULL. The caller is responsible for releasing this object.Return Value
If an acceptable application is found, its URL is returned. If the URL is a
file://URL, the application bound to the specified file or directory's type is returned. If the URL's scheme is something else, its default scheme handler is returned. If no application could be found,NULLis returned and outError (if notNULL) is populated withkLSApplicationNotFoundErr.The caller is responsible for releasing this URL.
Discussion
Consults the binding tables to return the application that would be used to open inURL if it were double-clicked in the Finder. This application will be the user-specified override if appropriate or the default otherwise.
Import Statement
import CoreServicesAvailability
Available in OS X v10.10 and later.
-
LSGetApplicationForItem(_:_:_:_:) LSGetApplicationForItem(OS X v10.10)Locates the preferred application for opening an item designated by file-system reference.
Deprecation Statement
Use
LSCopyDefaultApplicationURLForURLinstead.Declaration
Swift
func LSGetApplicationForItem(_inItemRef: UnsafePointer<FSRef>, _inRolesMask: LSRolesMask, _outAppRef: UnsafeMutablePointer<FSRef>, _outAppURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSGetApplicationForItem ( const FSRef *inItemRef, LSRolesMask inRoleMask, FSRef *outAppRef, CFURLRef *outAppURL );Parameters
inItemRefA 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
FSRefdata type.inRolesMaskA 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.outAppRefA 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
FSRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppURLcannot both beNULL.outAppURLA 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
CFURLRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppRefcannot both beNULL.Despite the absence of the word
Copyin 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
LSGetApplicationForURL(_:_:_:_:) LSGetApplicationForURL(OS X v10.10)Locates the preferred application for opening an item designated by URL.
Deprecation Statement
Use
LSCopyDefaultApplicationURLForURLinstead.Declaration
Swift
func LSGetApplicationForURL(_inURL: CFURL!, _inRolesMask: LSRolesMask, _outAppRef: UnsafeMutablePointer<FSRef>, _outAppURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSGetApplicationForURL ( CFURLRef inURL, LSRolesMask inRoleMask, FSRef *outAppRef, CFURLRef *outAppURL );Parameters
inURLA 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
CFURLRefdata type.inRolesMaskA 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, passkLSRolesAll.outAppRefA 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
FSRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppURLcannot both beNULL.outAppURLA 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
CFURLRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppRefcannot both beNULL.Despite the absence of the word
Copyin 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 theinRolesMaskparameter; otherwise, it is based on the URL scheme (such ashttp,ftp, ormailto).Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Returns the application used to open a content type (UTI).
Declaration
Swift
func LSCopyDefaultApplicationURLForContentType(_inContentType: CFString!, _inRoleMask: LSRolesMask, _outError: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFURL>!Objective-C
CFURLRef LSCopyDefaultApplicationURLForContentType ( CFStringRef inContentType, LSRolesMask inRoleMask, CFErrorRef *outError );Parameters
inContentTypeThe Uniform Type Identifier (UTI) of the item for which the application is requested.
inRoleMaskWhether to return the editor or viewer for
inContentType. If you don't care which, usekLSRolesAll.outErrorOn failure, set to a
CFErrorRefdescribing the problem. If you are not interested in this information, passNULL. The caller is responsible for releasing this object.Return Value
If an acceptable application is found, its URL is returned. If no application could be found,
NULLis returned andoutError(if notNULL) is populated withkLSApplicationNotFoundErr. The caller is responsible for releasing this URL.Discussion
Consults the binding tables to return the application that would be used to open a file of type
inContentTypeif it were double-clicked in the Finder. This application will be the user-specified override if appropriate or the default otherwise.Import Statement
import CoreServicesAvailability
Available in OS X v10.10 and later.
-
LSGetApplicationForInfo(_:_:_:_:_:_:) LSGetApplicationForInfo(OS X v10.10)Locates the preferred application for opening items with a specified file type, creator signature, filename extension, or any combination of these characteristics.
Deprecation Statement
Use
LSCopyDefaultApplicationURLForContentTypeinstead.Declaration
Swift
func LSGetApplicationForInfo(_inType: OSType, _inCreator: OSType, _inExtension: CFString!, _inRolesMask: LSRolesMask, _outAppRef: UnsafeMutablePointer<FSRef>, _outAppURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSGetApplicationForInfo ( OSType inType, OSType inCreator, CFStringRef inExtension, LSRolesMask inRoleMask, FSRef *outAppRef, CFURLRef *outAppURL );Parameters
inTypeThe file type to consider. Comparison of file types is case-sensitive. Pass
kLSUnknownTypeif the items’ file type is unimportant.inCreatorinExtensionA 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
CFStringRefdata type. Comparison of filename extensions is case-insensitive. PassNULLif the items’ filename extension is unimportant.inRolesMaskA 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.outAppRefA 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
FSRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppURLcannot both beNULL.outAppURLA 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
CFURLRefdata type. PassNULLif you are not interested in identifying the preferred application in this form; however, this parameter andoutAppRefcannot both beNULL.Despite the absence of the word
Copyin 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, andinExtensionparameters; 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Locates the preferred application for opening items with a specified MIME type.
Deprecation Statement
Use
LSCopyDefaultApplicationURLForContentTypeinstead.Declaration
Swift
func LSCopyApplicationForMIMEType(_inMIMEType: CFString!, _inRolesMask: LSRolesMask, _outAppURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSCopyApplicationForMIMEType ( CFStringRef inMIMEType, LSRolesMask inRoleMask, CFURLRef *outAppURL );Parameters
inMIMETypeA 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
CFStringRefdata type. Comparison of MIME types is case-insensitive.inRolesMaskA 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.outAppURLA 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
CFURLRefdata 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.2 and later.
Deprecated in OS X v10.10.
-
Locates all known applications suitable for opening an item designated by URL.
Declaration
Swift
func LSCopyApplicationURLsForURL(_inURL: CFURL!, _inRolesMask: LSRolesMask) -> Unmanaged<CFArray>!Objective-C
CFArrayRef LSCopyApplicationURLsForURL ( CFURLRef inURL, LSRolesMask inRoleMask );Parameters
inURLA 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
CFURLRefdata type.inRolesMaskA 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, passkLSRolesAll.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
NULLDiscussion
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 theinRolesMaskparameter; otherwise, it is based on the URL scheme (such ashttp,ftp, ormailto).Import Statement
import CoreServicesAvailability
Available in OS X v10.3 and later.
-
Tests whether an application can accept (open) an item designated by URL.
Declaration
Swift
func LSCanURLAcceptURL(_inItemURL: CFURL!, _inTargetURL: CFURL!, _inRolesMask: LSRolesMask, _inFlags: LSAcceptanceFlags, _outAcceptsItem: UnsafeMutablePointer<Boolean>) -> OSStatusObjective-C
OSStatus LSCanURLAcceptURL ( CFURLRef inItemURL, CFURLRef inTargetURL, LSRolesMask inRoleMask, LSAcceptanceFlags inFlags, Boolean *outAcceptsItem );Parameters
inItemURLA 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
CFURLRefdata type.inTargetURLA Core Foundation URL reference designating the target application; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the
CFURLRefdata type. The URL must have schemefileand contain a valid path to an application file or application bundle.inRolesMaskA 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, passkLSRolesAll.inFlagsFlags specifying behavior to observe during the acceptance test; see Acceptance Flags for a description of these flags.
outAcceptsItemA 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 theinRolesMaskparameter; otherwise, it is based on the URL scheme (such ashttp,ftp, ormailto).Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
LSCanRefAcceptItem(_:_:_:_:_:) LSCanRefAcceptItem(OS X v10.10)Tests whether an application can accept (open) an item designated by file-system reference.
Deprecation Statement
Use
LSCanURLAcceptURLinstead.Declaration
Swift
func LSCanRefAcceptItem(_inItemFSRef: UnsafePointer<FSRef>, _inTargetFSRef: UnsafePointer<FSRef>, _inRolesMask: LSRolesMask, _inFlags: LSAcceptanceFlags, _outAcceptsItem: UnsafeMutablePointer<Boolean>) -> OSStatusObjective-C
OSStatus LSCanRefAcceptItem ( const FSRef *inItemFSRef, const FSRef *inTargetRef, LSRolesMask inRoleMask, LSAcceptanceFlags inFlags, Boolean *outAcceptsItem );Parameters
inItemFSRefA 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
FSRefdata type.inTargetFSRefA 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
FSRefdata type.inRolesMaskA 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.inFlagsFlags specifying behavior to observe during the acceptance test; see Acceptance Flags for a description of these flags.
outAcceptsItemA 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Returns all URLs for the application that corresponds to a bundle identifier.
Declaration
Swift
func LSCopyApplicationURLsForBundleIdentifier(_inBundleIdentifier: CFString!, _outError: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<CFArray>!Objective-C
CFArrayRef LSCopyApplicationURLsForBundleIdentifier ( CFStringRef inBundleIdentifier, CFErrorRef *outError );Parameters
inBundleIdentifierThe bundle identifier of interest, such as "com.apple.finder". Must not be
NULL.outErrorOn failure, set to a
CFErrorRefdescribing the problem. If you are not interested in this information, passNULL. The caller is responsible for releasing this object.Return Value
If any applications with the specified bundle identifier are found, their URLs are returned in a
CFArrayRef. If no application could be found,NULLis returned andoutError(if notNULL) is populated withkLSApplicationNotFoundErr.The order of elements in the array is undefined.
The caller is responsible for releasing this array.
Import Statement
import CoreServicesAvailability
Available in OS X v10.10 and later.
-
LSFindApplicationForInfo(_:_:_:_:_:) LSFindApplicationForInfo(OS X v10.10)Locates an application with a specified creator signature, bundle ID, filename, or any combination of these characteristics.
Deprecation Statement
Use
LSCopyApplicationURLsForBundleIdentifierinstead.Declaration
Swift
func LSFindApplicationForInfo(_inCreator: OSType, _inBundleID: CFString!, _inName: CFString!, _outAppRef: UnsafeMutablePointer<FSRef>, _outAppURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSFindApplicationForInfo ( OSType inCreator, CFStringRef inBundleID, CFStringRef inName, FSRef *outAppRef, CFURLRef *outAppURL );Parameters
inCreatorThe creator signature to consider. Comparison of creator signatures is case-sensitive. Pass
kLSUnknownCreatorif the application’s creator signature is unimportant.inBundleIDA 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
CFStringRefdata type. Comparison of bundle IDs is case-insensitive. PassNULLif the application’s bundle ID is unimportant.inNameA Core Foundation string object specifying the filename to consider; see the CFString Reference in the Core Foundation Reference Documentation for a description of the
CFStringRefdata type. The string must include any extension (such as'.app') that is part of the filename. Comparison of filenames is case-insensitive. PassNULLif the application’s filename is unimportant.outAppRefA 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
FSRefdata type. PassNULLif you are not interested in identifying the application in this form; however, this parameter andoutAppURLcannot both beNULL.outAppURLA 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
CFURLRefdata type. PassNULLif you are not interested in identifying the application in this form; however, this parameter andoutAppRefcannot both beNULL.Despite the absence of the word
Copyin 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, andinNameparameters; 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
The functions described in this section open a designated item or collection of items, or launch or activate a designated application.
-
LSOpenApplication(_:_:) LSOpenApplication(OS X v10.10)Launches the specified application.
Declaration
Swift
func LSOpenApplication(_inAppParams: UnsafePointer<LSApplicationParameters>, _outPSN: UnsafeMutablePointer<ProcessSerialNumber>) -> OSStatusObjective-C
OSStatus LSOpenApplication ( const LSApplicationParameters *appParams, ProcessSerialNumber *outPSN );Parameters
inAppParamsA
LSApplicationParametersstructure specifying the application to launch and its launch parameters. This parameter cannot beNULL.outPSNOn input, a pointer to a value of type
ProcessSerialNumberthat, on return, contains the process serial number (PSN) of the application specified byinAppParams, orNULLif you don’t want to receive the PSN.Return Value
A result code; see Launch Services Result Codes.
Discussion
The
LSOpenApplicationlaunches one application. This function is an updated alternative to the Process Manager'sLaunchApplicationfunction. Launch arguments are specified in theinAppParamsargument, which must be supplied. If the application is already running in the current session, it is made the front process (unless thekLSLaunchNewInstanceflag is used, which always causes a new process to be created).If
outPSNis notNULL, 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
LSOpenItemsWithRole(_:_:_:_:_:_:_:) LSOpenItemsWithRole(OS X v10.10)Opens items specified as an array of values of type
FSRefwith a specified role.Declaration
Swift
func LSOpenItemsWithRole(_inItems: UnsafePointer<FSRef>, _inItemCount: CFIndex, _inRole: LSRolesMask, _inAEParam: UnsafePointer<AEKeyDesc>, _inAppParams: UnsafePointer<LSApplicationParameters>, _outPSNs: UnsafeMutablePointer<ProcessSerialNumber>, _inMaxPSNCount: CFIndex) -> OSStatusObjective-C
OSStatus LSOpenItemsWithRole ( const FSRef *inItems, CFIndex inItemCount, LSRolesMask inRole, const AEKeyDesc *inAEParam, const LSApplicationParameters *inAppParams, ProcessSerialNumber *outPSNs, CFIndex inMaxPSNCount );Parameters
inItemsAn array of values of type
FSRef.inItemCountThe number of items specified in
inItems.inRoleA value of type
LSRolesMaskspecifying one or more roles. If the role doesn’t matter, usekLSRolesAll. For possible values, see Roles Mask. If theinAppParamsparameter is notNULL, this parameter is ignored.inAEParamAn
AEKeyDescthat is to be attached to the Apple Event(s) generated by Launch Services with the specifiedAEKeyword. This parameter can beNULL.inAppParamsAn
LSApplicationParametersstructure specifying the application to launch and its launch parameters, in which case theinRoleparameter is ignored. This parameter can beNULL, in which case an application is selected that can handle each input item in at least one of the roles specified by theinRoleparameter.outPSNsOn input, a pointer to a caller-allocated buffer or
NULLif you don’t want to receive process serial number (PSN) information. If notNULLon 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).inMaxPSNCountThe maximum number of PSNs that the buffer pointed to by
outPSNscan 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
inAppParamsparameter. If an application is specified in theinAppParamsparameter, theinRoleparameter 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 that are to be opened.If the
inItemsarray contains any applications, this function launches them only if thekLSRolesShellbit is set in theinRolesparameter to indicate that the operating system should use the application itself as the execution shell of the new process.If not
NULL, theoutPSNsbuffer is filled with the PSN that was used to open each item at the same index of theinItemsarray. The PSN capacity of the output buffer is specified byinMaxPSNCount.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
LSOpenURLsWithRole(_:_:_:_:_:_:) LSOpenURLsWithRole(OS X v10.10)Opens one or more URLs with the specified roles.
Declaration
Swift
func LSOpenURLsWithRole(_inURLs: CFArray!, _inRole: LSRolesMask, _inAEParam: UnsafePointer<AEKeyDesc>, _inAppParams: UnsafePointer<LSApplicationParameters>, _outPSNs: UnsafeMutablePointer<ProcessSerialNumber>, _inMaxPSNCount: CFIndex) -> OSStatusObjective-C
OSStatus LSOpenURLsWithRole ( CFArrayRef inURLs, LSRolesMask inRole, const AEKeyDesc *inAEParam, const LSApplicationParameters *inAppParams, ProcessSerialNumber *outPSNs, CFIndex inMaxPSNCount );Parameters
inURLsAn array of values of type
CFURLRef.inRoleA value of type
LSRolesMaskspecifying one or more roles. If the role doesn’t matter, usekLSRolesAll. For possible values, see Roles Mask. This parameter is ignored if theinAppParamsparameter is notNULL.inAEParamA value of type
AEKeyDescthat is to be attached to the Apple Event(s) generated by Launch Services with the specifiedAEKeyword. This parameter can beNULL.inAppParamsAn
LSApplicationParametersstructure specifying the application to launch and its launch parameters, in which case theinRoleparameter is ignored. This parameter can beNULL, in which case an application is selected that can handle each input URL in at least one of the roles specified by theinRoleparameter.outPSNsOn input, a pointer to a caller-allocated buffer or
NULLif you don’t want to receive process serial number (PSN) information. If notNULLon input, on return, the buffer contains at each index the PSN that was used to open the URL at the same index of the input URL array (inURLs).inMaxPSNCountThe maximum number of PSNs that the buffer pointed to by
outPSNscan hold.Return Value
A result code; see Launch Services Result Codes.
Discussion
This function opens the URLs specified by
inURLswith the roles specified byinRole.Each launched application receives one or more
'GURL'Apple Events specifying the URLs to be opened. You can also pass file URLs, which are interpreted as file system items and opened in the manner ofLSOpenItemsWithRole(that is, a handler is selected based on the item’s filesystem metadata).IfinURLscontains any application URLs, this function launches them only if thekLSRolesShellbit is set in theinRolesparameter, in which case the application is its own shell.If notNULL, theoutPSNsbuffer is filled with the process serial numbers that were used to open each URL at the same index of the input URL array specified by theinURLsparameter. The PSN capacity of the output buffer is specified byinMaxPSNCount.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
LSOpenFSRef(_:_:) LSOpenFSRef(OS X v10.10)Opens an item designated by file-system reference, in the default manner in its preferred application.
Declaration
Swift
func LSOpenFSRef(_inRef: UnsafePointer<FSRef>, _outLaunchedRef: UnsafeMutablePointer<FSRef>) -> OSStatusParameters
inRefA 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
FSRefdata type.outLaunchedRefA pointer to a file-system reference that, on return, will identify the application launched. Pass
NULLif 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
LSOpenFromRefSpecfunction with a launch specification specifying the launch flagkLSLaunchDefaults: 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, callLSOpenFromRefSpecdirectly. 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:
If the item is a document, its preferred application is launched (or activated if it is already running) and sent an
'odoc'(“open document”) Apple event.If the item is an application that is not already running, it is launched and sent an
'oapp'(“open application”) Apple event.If the item is an application that is already running, it is activated and sent an
'rapp'(“reopen application”) Apple event.
As of OS X v10.4 and later,
LSOpenItemsWithRoleis the preferred way of opening an item.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
LSOpenFromRefSpec(_:_:) LSOpenFromRefSpec(OS X v10.10)Opens one or more items designated by file-system reference, in either their preferred applications or a designated application.
Declaration
Swift
func LSOpenFromRefSpec(_inLaunchSpec: UnsafePointer<LSLaunchFSRefSpec>, _outLaunchedRef: UnsafeMutablePointer<FSRef>) -> OSStatusObjective-C
OSStatus LSOpenFromRefSpec ( const LSLaunchFSRefSpec *inLaunchSpec, FSRef *outLaunchedRef );Parameters
inLaunchSpecA 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.
outLaunchedRefA 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
FSRefdata type. PassNULLif 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
LSOpenFSReffunction. 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
inLaunchSpecparameter 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:If the launch specification designates both items to open and an application with which to open them, the designated application is used to open all of the items. The application is launched (or activated if it is already running) and sent an
'odoc'(“open document”) Apple event containing the list of items to open; if the items are to be printed, the Apple event is'pdoc'(“print document”) instead.If the launch specification designates items to open but not an application with which to open them, each item is opened in its own preferred application. Each application is launched or activated and sent an
'odoc'or'pdoc'Apple event, as described for the preceding case. (If two or more of the items have the same preferred application, the application receives a single'odoc'or'pdoc'event listing all of the relevant items.)If the launch specification designates only an application to launch (or if one or more of the items to open are applications):
If the application is not already running, it is launched and sent an
'oapp'(“open application”) Apple event.If the application is already running, it is activated and sent an
'rapp'(“reopen application”) Apple event.
As of OS X v10.4 and later,
LSOpenItemsWithRoleis the preferred way of opening items.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Opens an item designated by URL, in the default manner in its preferred application.
Declaration
Swift
func LSOpenCFURLRef(_inURL: CFURL!, _outLaunchedURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusParameters
inURLA Core Foundation URL reference designating the item to open; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the
CFURLRefdata type.outLaunchedURLA pointer to a Core Foundation URL reference that, on return, will identify the application launched. Pass
NULLif this information is unimportant.Despite the absence of the word
Copyin 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
LSOpenFromURLSpecfunction with a launch specification specifying the launch flagkLSLaunchDefaults: 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, callLSOpenFromURLSpecdirectly. 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 ashttp,ftp, ormailto). The application is launched or activated, as required, and sent an appropriate Apple event depending on the circumstances:If the URL’s scheme is
fileand it designates a document, the document’s preferred application is launched (or activated if it is already running).If the application claims to accept
fileURLs, it is sent a'GURL'(“get URL”) Apple event containing the item’s URL.If the application does not claim to accept
fileURLs, it is sent an'odoc'(“open document”) Apple event identifying the document to open.
If the URL’s scheme is
fileand it designates an application:If the application is not already running, it is launched and sent an
'oapp'(“open application”) Apple event.If the application is already running, it is activated and sent an
'rapp'(“reopen application”) Apple event.
If the URL has a scheme other than
file, the scheme’s preferred application is launched (or activated if it is already running) and sent a'GURL'(“get URL”) Apple event containing the item’s URL.
As of OS X v10.4 and later,
LSOpenURLsWithRoleis the preferred way of opening a URL.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
Opens one or more items designated by URL, in either their preferred applications or a designated application.
Declaration
Swift
func LSOpenFromURLSpec(_inLaunchSpec: UnsafePointer<LSLaunchURLSpec>, _outLaunchedURL: UnsafeMutablePointer<Unmanaged<CFURL>?>) -> OSStatusObjective-C
OSStatus LSOpenFromURLSpec ( const LSLaunchURLSpec *inLaunchSpec, CFURLRef *outLaunchedURL );Parameters
inLaunchSpecA 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.
outLaunchedURLA 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
CFURLRefdata type. PassNULLif 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
Copyin 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
LSOpenCFURLReffunction. 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
inLaunchSpecparameter 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:If the launch specification designates both items to open and an application with which to open them, the designated application is used to open all of the items. The application is launched (or activated if it is already running) and sent one or more Apple events:
If one or more of the item URLs have scheme
fileand designate documents to open, and if the application claims to acceptfileURLs, it is sent a'GURL'(“get URL”) Apple event for each such URL.If one or more of the item URLs have scheme
fileand designate documents to open, and if the application does not claim to acceptfileURLs, it is sent a single'odoc'(“open document”) Apple event containing the list of items to open; if the items are to be printed, the Apple event is'pdoc'(“print document”) instead.For each item URL with a scheme other than
file, the application is sent a'GURL'(“get URL”) Apple event containing the item’s URL.
If the launch specification designates items to open but not an application with which to open them, each item is opened in its own preferred application. Each application is launched or activated and sent one or more Apple events, as described for the preceding case. (If two or more of the items have the same preferred application, the application receives a single
'odoc'or'pdoc'event listing all of the relevant items.)If the launch specification designates only an application to launch (or if one or more of the items to open are
fileURLs designating applications):If the application is not already running, it is launched and sent an
'oapp'(“open application”) Apple event.If the application is already running, it is activated and sent an
'rapp'(“reopen application”) Apple event.
As of OS X v10.4 and later,
LSOpenURLsWithRoleis the preferred way of opening URLs.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
The functions described in this section obtain requested information about an item.
-
LSCopyItemInfoForRef(_:_:_:) LSCopyItemInfoForRef(OS X v10.10)Obtains requested information about an item designated by file-system reference.
Deprecation Statement
Use
LSCopyItemInfoForURLor URL resource properties instead.Declaration
Swift
func LSCopyItemInfoForRef(_inItemRef: UnsafePointer<FSRef>, _inWhichInfo: LSRequestedInfo, _outItemInfo: UnsafeMutablePointer<LSItemInfoRecord>) -> OSStatusObjective-C
OSStatus LSCopyItemInfoForRef ( const FSRef *inItemRef, LSRequestedInfo inWhichInfo, LSItemInfoRecord *outItemInfo );Parameters
inItemRefA 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
FSRefdata type.inWhichInfoFlags specifying what information to obtain; see Requested-Information Flags for a description of these flags.
outItemInfoA 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
extensionof the item-information record, requested by flagkLSRequestExtension), 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Obtains requested information about an item designated by URL.
Declaration
Swift
func LSCopyItemInfoForURL(_inFileURL: CFURL!, _inWhichInfo: LSRequestedInfo, _outItemInfo: UnsafeMutablePointer<LSItemInfoRecord>) -> OSStatusObjective-C
OSStatus LSCopyItemInfoForURL ( CFURLRef inURL, LSRequestedInfo inWhichInfo, LSItemInfoRecord *outItemInfo );Parameters
inFileURLA 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
CFURLRefdata type. The URL must have schemefileand contain a valid path to either a file or a directory.inWhichInfoFlags specifying what information to obtain; see Requested-Information Flags for a description of these flags.
outItemInfoA 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
extensionof the item-information record, requested by flagkLSRequestExtension), 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
LSCopyDisplayNameForRef(_:_:) LSCopyDisplayNameForRef(OS X v10.10)Obtains the display name for an item designated by file-system reference.
Deprecation Statement
Use
LSCopyDisplayNameForURLor the URL resource propertykCFURLLocalizedNameKey/NSURLLocalizedNameKeyinstead.Declaration
Swift
func LSCopyDisplayNameForRef(_inRef: UnsafePointer<FSRef>, _outDisplayName: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyDisplayNameForRef ( const FSRef *inRef, CFStringRef *outDisplayName );Parameters
inRefA 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
FSRefdata type.outDisplayNameA 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
CFStringRefdata 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.1 and later.
Deprecated in OS X v10.10.
-
Obtains the display name for an item designated by URL.
Declaration
Swift
func LSCopyDisplayNameForURL(_inFileURL: CFURL!, _outDisplayName: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyDisplayNameForURL ( CFURLRef inURL, CFStringRef *outDisplayName );Parameters
inFileURLA 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
CFURLRefdata type. The URL must have schemefileand contain a valid path to either a file or a directory.outDisplayNameA 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
CFStringRefdata 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.1 and later.
-
LSCopyKindStringForRef(_:_:) LSCopyKindStringForRef(OS X v10.10)Obtains the kind string for an item designated by file-system reference.
Deprecation Statement
Use
LSCopyKindStringForURLor the URL resource propertykCFURLLocalizedTypeDescriptionKey/NSURLLocalizedTypeDescriptionKeyinstead.Declaration
Swift
func LSCopyKindStringForRef(_inFSRef: UnsafePointer<FSRef>, _outKindString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyKindStringForRef ( const FSRef *inFSRef, CFStringRef *outKindString );Parameters
inFSRefA 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
FSRefdata type.outKindStringA 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
CFStringRefdata 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 justDocumentif the item is a document for which no application is found.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Obtains the kind string for an item designated by URL.
Declaration
Swift
func LSCopyKindStringForURL(_inURL: CFURL!, _outKindString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyKindStringForURL ( CFURLRef inURL, CFStringRef *outKindString );Parameters
inURLA 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
CFURLRefdata type.outKindStringA 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
CFStringRefdata 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 justDocumentif the item is a document for which no application is found. If the item URL’s scheme isfile(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 ashttp,ftp, ormailto).Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
Obtains a kind string for items with a specified file type, creator signature, filename extension, or any combination of these characteristics.
Deprecation Statement
Use
UTTypeCopyDescriptioninstead.Declaration
Swift
func LSCopyKindStringForTypeInfo(_inType: OSType, _inCreator: OSType, _inExtension: CFString!, _outKindString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyKindStringForTypeInfo ( OSType inType, OSType inCreator, CFStringRef inExtension, CFStringRef *outKindString );Parameters
inTypeThe file type to consider. Comparison of file types is case-sensitive. Pass
kLSUnknownTypeif the items’ file type is unimportant.inCreatorinExtensionA 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
CFStringRefdata type. Comparison of filename extensions is case-insensitive. PassNULLif the items’ filename extension is unimportant.outKindStringA 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
CFStringRefdata 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, andinExtensionparameters; 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 beFrameMaker Document, or justDocumentif 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.Import Statement
import CoreServicesAvailability
Available in OS X v10.2 and later.
Deprecated in OS X v10.10.
-
LSCopyKindStringForMIMEType(_:_:) LSCopyKindStringForMIMEType(OS X v10.10)Obtains the kind string for a specified MIME type.
Deprecation Statement
Use
UTTypeCopyDescriptioninstead.Declaration
Swift
func LSCopyKindStringForMIMEType(_inMIMEType: CFString!, _outKindString: UnsafeMutablePointer<Unmanaged<CFString>?>) -> OSStatusObjective-C
OSStatus LSCopyKindStringForMIMEType ( CFStringRef inMIMEType, CFStringRef *outKindString );Parameters
inMIMETypeA 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
CFStringRefdata type. Comparison of MIME types is case-insensitive.outKindStringA 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
CFStringRefdata 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.2 and later.
Deprecated in OS X v10.10.
-
LSCopyItemAttribute(_:_:_:_:) LSCopyItemAttribute(OS X v10.10)Obtains the value of an item’s attribute.
Deprecation Statement
Use
CFURLCopyResourcePropertyForKeyorgetResourceValue:forKey:error:instead.Declaration
Swift
func LSCopyItemAttribute(_inItem: UnsafePointer<FSRef>, _inRoles: LSRolesMask, _inAttributeName: CFString!, _outValue: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> OSStatusObjective-C
OSStatus LSCopyItemAttribute ( const FSRef *inItem, LSRolesMask inRoles, CFStringRef inAttributeName, CFTypeRef *outValue );Parameters
inItemThe
FSRefof the item to query.inRolesThe roles. When obtaining attributes related to document binding (such as
kLSItemRoleHandlerDisplayName), at least one of the roles must be provided by the application selected. PasskLSRolesAllif any role is acceptable.inAttributeNameThe name of the attribute to copy. For possible values, see Item Attribute Constants.
outValueA pointer to a
CFTypeRef. On return, theCFTypeRefis set to the copied attribute value (a CF object), or isNULLif 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
LSCopyItemAttributes(_:_:_:_:) LSCopyItemAttributes(OS X v10.10)Obtains multiple item attribute values as a dictionary.
Deprecation Statement
Use
CFURLCopyResourcePropertiesForKeysorresourceValuesForKeys:error:instead.Declaration
Swift
func LSCopyItemAttributes(_inItem: UnsafePointer<FSRef>, _inRoles: LSRolesMask, _inAttributeNames: CFArray!, _outValues: UnsafeMutablePointer<Unmanaged<CFDictionary>?>) -> OSStatusObjective-C
OSStatus LSCopyItemAttributes ( const FSRef *inItem, LSRolesMask inRoles, CFArrayRef inAttributeNames, CFDictionaryRef *outValues );Parameters
inItemThe
FSRefof the item to query.inRolesThe roles. When obtaining attributes related to document binding (such as
kLSItemRoleHandlerDisplayName), at least one of the roles must be provided by the application selected. PasskLSRolesAllif any role is acceptable.inAttributeNamesA
CFArrayReffor an array containing the attribute names to copy. For possible values, see Item Attribute Constants.outValuesOn return, a pointer a
CFDictionaryReffor a dictionary whose keys are the attribute names specified by theinAttributeNamesparameter and whose values are the attribute’s values. TheCFTypeIDof 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
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.
-
Obtains the starting index of the extension within a filename.
Declaration
Swift
func LSGetExtensionInfo(_inNameLen: UniCharCount, _inNameBuffer: UnsafePointer<UniChar>, _outExtStartIndex: UnsafeMutablePointer<UniCharCount>) -> OSStatusObjective-C
OSStatus LSGetExtensionInfo ( UniCharCount inNameLen, const UniChar inNameBuffer[], UniCharCount *outExtStartIndex );Parameters
inNameLenThe number of characters in the filename specified by the
inNameBufferparameter.inNameBufferThe buffer containing the filename’s Unicode characters.
outExtStartIndexA pointer to a value of type
UniCharCountthat, 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 bekLSInvalidExtensionIndex.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).
Import Statement
import CoreServicesAvailability
Available in OS X v10.1 and later.
-
LSSetExtensionHiddenForRef(_:_:) LSSetExtensionHiddenForRef(OS X v10.10)Specifies whether the filename extension for an item designated by file-system reference should be hidden or shown.
Deprecation Statement
Use
LSSetExtensionHiddenForURLor the URL resource propertykCFURLHasHiddenExtensionKey/NSURLHasHiddenExtensionKeyinstead.Declaration
Swift
func LSSetExtensionHiddenForRef(_inRef: UnsafePointer<FSRef>, _inHide: Boolean) -> OSStatusObjective-C
OSStatus LSSetExtensionHiddenForRef ( const FSRef *inRef, Boolean inHide );Parameters
inRefA pointer to a file-system reference designating the item whose filename extension is to be hidden or shown; see the File Manager Reference in the Carbon File Management Documentation for a description of the
FSRefdata type.inHideA Boolean value specifying whether the filename extension should be hidden (
true) or shown (false).Return Value
A result code; see Launch Services Result Codes. The function will return the result code
kLSCannotSetInfoErrif:The extension is not valid (contains spaces)
The extension is not active (is not claimed by an application registered with Launch Services)
Hiding the extension would make the filename appear to have an active but incorrect extension (for example, in the filename
Photo.jpeg.scpt, where hiding the extension would make an AppleScript file appear to be a JPEG file)
Discussion
This function sets the necessary file-system state controlling whether the filename extension should be hidden in the display name of the item designated by the
inRefparameter. To determine whether an item’s extension is currently hidden, you can use theLSCopyItemInfoForReffunction.Import Statement
import CoreServicesAvailability
Available in OS X v10.1 and later.
Deprecated in OS X v10.10.
-
Specifies whether the filename extension for an item designated by URL should be hidden or shown.
Declaration
Swift
func LSSetExtensionHiddenForURL(_inFileURL: CFURL!, _inHide: Boolean) -> OSStatusObjective-C
OSStatus LSSetExtensionHiddenForURL ( CFURLRef inURL, Boolean inHide );Parameters
inFileURLA Core Foundation URL reference designating the item whose filename extension is to be hidden or shown; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the
CFURLRefdata type. The URL must have schemefileand contain a valid path to either a file or a directory.inHideA Boolean value specifying whether the extension should be hidden (
true) or shown (false).Return Value
A result code; see Launch Services Result Codes. The function will return the result code
kLSCannotSetInfoErrif:The extension is not valid (contains spaces)
The extension is not active (is not claimed by an application registered with Launch Services)
Hiding the extension would make the filename appear to have an active but incorrect extension (for example, in the filename
Photo.jpeg.scpt, where hiding the extension would make an AppleScript file appear to be a JPEG file)
Discussion
This function sets the necessary file-system state controlling whether the filename extension should be hidden in the display name of the item designated by the
inFileURLparameter. To determine whether an item’s extension is currently hidden, you can use theLSCopyItemInfoForURLfunction.Import Statement
import CoreServicesAvailability
Available in OS X v10.1 and later.
The functions described in this section register an application in the Launch Services database.
-
Registers an application, designated by URL, in the Launch Services database.
Declaration
Swift
func LSRegisterURL(_inFileURL: CFURL!, _inUpdate: Boolean) -> OSStatusObjective-C
OSStatus LSRegisterURL ( CFURLRef inURL, Boolean inUpdate );Parameters
inFileURLA Core Foundation URL reference designating the application to be registered; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the
CFURLRefdata type. The URL must have schemefileand contain a valid path to an application file or application bundle.inUpdateA Boolean value specifying whether Launch Services should update existing information registered for the application, if any. If this parameter is
false, the application will not be registered if it has already been registered previously and its current modification date has not changed from when it was last registered; if the parameter istrue, the application’s registered information will be updated even if its modification date has not changed.Return Value
A result code; see Launch Services Result Codes.
Discussion
This function adds the designated application and its document and URL claims (if any) to the Launch Services database, making the application a candidate for document and URL binding.
Import Statement
import CoreServicesAvailability
Available in OS X v10.3 and later.
-
LSRegisterFSRef(_:_:) LSRegisterFSRef(OS X v10.10)Registers an application, designated by file-system reference, in the Launch Services database.
Deprecation Statement
Use
LSRegisterURLinstead.Declaration
Swift
func LSRegisterFSRef(_inRef: UnsafePointer<FSRef>, _inUpdate: Boolean) -> OSStatusObjective-C
OSStatus LSRegisterFSRef ( const FSRef *inRef, Boolean inUpdate );Parameters
inRefA pointer to a file-system reference designating the application to be registered; see the File Manager Reference in the Carbon File Management Documentation for a description of the
FSRefdata type.inUpdateA Boolean value specifying whether Launch Services should update existing information registered for the application, if any. If this parameter is
false, the application will not be registered if it has already been registered previously and its current modification date has not changed from when it was last registered; if the parameter istrue, the application’s registered information will be updated even if its modification date has not changed.Return Value
A result code; see Launch Services Result Codes.
Discussion
This function adds the designated application and its document and URL claims (if any) to the Launch Services database, making the application a candidate for document and URL binding.
Import Statement
import CoreServicesAvailability
Available in OS X v10.3 and later.
Deprecated in OS X v10.10.
The functions described in this section get and set application bundle identifiers for handlers of specified content types and URL schemes.
-
Returns an array of application bundle identifiers for applications capable of handling a specified content type with the specified roles.
Declaration
Swift
func LSCopyAllRoleHandlersForContentType(_inContentType: CFString!, _inRole: LSRolesMask) -> Unmanaged<CFArray>!Objective-C
CFArrayRef LSCopyAllRoleHandlersForContentType ( CFStringRef inContentType, LSRolesMask inRole );Parameters
inContentTypeThe content type. The content type is a uniform type identifier (UTI).
inRoleThe role. Pass
kLSRolesAllif 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
NULLif 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
CFBundleDocumentTypeskey in an application’sInfo.plistcan be used to set an application’s content handling capabilities. TheLSItemContentTypeskey is particularly useful because it supports the use of UTIs in document claims. For information on theCFBundleDocumentTypeskey, see the section “CFBundleDocumentTypes” in OS X Runtime Configuration Guidelines.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Returns the application bundle identifier of the user’s preferred default handler for the specified content type with the specified role.
Declaration
Swift
func LSCopyDefaultRoleHandlerForContentType(_inContentType: CFString!, _inRole: LSRolesMask) -> Unmanaged<CFString>!Objective-C
CFStringRef LSCopyDefaultRoleHandlerForContentType ( CFStringRef inContentType, LSRolesMask inRole );Parameters
inContentTypeThe content type. The content type is a uniform type identifier (UTI).
inRoleThe role. Pass
kLSRolesAllif 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
NULLif no handler is available.Discussion
This function returns the user’s currently preferred default handler for the specified content type. Say, for example, that
LSSetDefaultRoleHandlerForContentTypehas 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 callLSCopyDefaultRoleHandlerForContentType (CFSTR(“public.xml”), kLSRolesAll), the stringcom.apple.TextEditis returned.The
CFBundleDocumentTypeskey in an application’sInfo.plistcan be used to set an application’s content handling capabilities. TheLSItemContentTypeskey is particularly useful because it supports the use of UTIs in document claims. For information on theCFBundleDocumentTypeskey, see the section “CFBundleDocumentTypes” in OS X Runtime Configuration Guidelines.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Sets the user’s preferred default handler for the specified content type in the specified roles.
Declaration
Swift
func LSSetDefaultRoleHandlerForContentType(_inContentType: CFString!, _inRole: LSRolesMask, _inHandlerBundleID: CFString!) -> OSStatusObjective-C
OSStatus LSSetDefaultRoleHandlerForContentType ( CFStringRef inContentType, LSRolesMask inRole, CFStringRef inHandlerBundleID );Parameters
inContentTypeThe content type for which the default role handler is being set. The content type is a uniform type identifier (UTI).
inRoleThe roles for which the default role handler is being set. Pass
kLSRolesAllto specify all roles. For additional possible values, see Roles Mask.inHandlerBundleIDThe application bundle identifier that is to be set as the default handler for the specified content type and roles.
Return Value
A result code; see Launch Services Result Codes.
Discussion
Call
LSCopyDefaultRoleHandlerForContentTypeto get the current setting of the user’s preferred default handler for a specified content type.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Gets the handler options for the specified content type.
Declaration
Swift
func LSGetHandlerOptionsForContentType(_inContentType: CFString!) -> LSHandlerOptionsObjective-C
LSHandlerOptions LSGetHandlerOptionsForContentType ( CFStringRef inContentType );Parameters
inContentTypeThe 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Sets the handler option for the specified content type.
Declaration
Swift
func LSSetHandlerOptionsForContentType(_inContentType: CFString!, _inOptions: LSHandlerOptions) -> OSStatusObjective-C
OSStatus LSSetHandlerOptionsForContentType ( CFStringRef inContentType, LSHandlerOptions inOptions );Parameters
inContentTypeThe content type for which the handler options are to be set. The content type is a uniform type identifier (UTI).
inOptionsThe handler options to set. For possible values, see Handler Option Constants.
Return Value
A result code; see Launch Services Result Codes.
Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Returns an array of application bundle identifiers for applications capable of handling the specified URL scheme.
Declaration
Swift
func LSCopyAllHandlersForURLScheme(_inURLScheme: CFString!) -> Unmanaged<CFArray>!Objective-C
CFArrayRef LSCopyAllHandlersForURLScheme ( CFStringRef inURLScheme );Parameters
inURLSchemeThe 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, orNULLif 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
CFBundleURLTypeskey in an application’sInfo.plist. For information on theCFBundleURLTypeskey, see the section “CFBundleURLTypes” in OS X Runtime Configuration Guidelines.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Returns the application bundle identifier of the user’s preferred default handler for the specified URL scheme.
Declaration
Swift
func LSCopyDefaultHandlerForURLScheme(_inURLScheme: CFString!) -> Unmanaged<CFString>!Objective-C
CFStringRef LSCopyDefaultHandlerForURLScheme ( CFStringRef inURLScheme );Parameters
inURLSchemeThe 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
CFBundleURLTypeskey in an application’sInfo.plist. For information on theCFBundleURLTypeskey, see the section “CFBundleURLTypes” in OS X Runtime Configuration Guidelines.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
Sets the user’s preferred default handler for the specified URL scheme.
Declaration
Swift
func LSSetDefaultHandlerForURLScheme(_inURLScheme: CFString!, _inHandlerBundleID: CFString!) -> OSStatusObjective-C
OSStatus LSSetDefaultHandlerForURLScheme ( CFStringRef inURLScheme, CFStringRef inHandlerBundleID );Parameters
inURLSchemeThe URL scheme for which the handler is to be set.
inHandlerBundleIDThe application bundle identifier that is to be set as the handler for the URL scheme specified by
inURLScheme.Return Value
A result code; see Launch Services Result Codes.
Discussion
Call
LSCopyDefaultHandlerForURLSchemeto get the current setting of the user’s preferred default handler for a specified content type.URL handling capability is determined according to the value of the
CFBundleURLTypeskey in an application’sInfo.plist. For information on theCFBundleURLTypeskey, see the section “CFBundleURLTypes” in OS X Runtime Configuration Guidelines.Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
The functions described in this section are no longer used.
-
Deprecation Statement
Formerly used to initialize Launch Services; no longer necessary.
Declaration
Objective-C
OSStatus LSInit ( LSInitializeFlags inFlags );Discussion
Calling this function was formerly required in order to initialize Launch Services; it is no longer needed, however, because Launch Services is now initialized automatically the first time one of its functions is called.
LSInitnow does nothing at all.Import Statement
Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.3.
-
Deprecation Statement
Formerly used to terminate Launch Services; now does nothing.
Declaration
Objective-C
OSStatus LSTerm ( void );Discussion
Calling this function was formerly required in order to terminate Launch Services; however, it is no longer needed and so should not be called. It now does nothing at all.
Import Statement
Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.3.
This section describes the data types defined in the Launch Services API.
-
Specifies the application, launch flags, and additional parameters that control how an application is launched.
Declaration
Objective-C
struct LSApplicationParameters { CFIndex version; LSLaunchFlags flags; const FSRef * application; void * asyncLaunchRefCon; CFDictionaryRef environment; CFArrayRef argv; AppleEvent * initialEvent }; typedef struct LSApplicationParameters LSApplicationParameters;Fields
versionThe version of the structure. The value of this field must be
0.flagsLaunch flags. For possible values, see Launch Flags.
applicationThe
FSRefof the application to open.asyncLaunchRefConThe client
refConthat is to appear in subsequent launch notifications.environmentA dictionary of
CFStringRefkeys and values for environment variables to set in the launched process. The value of this field can beNULL.argvAn array of values of type
CFStringRefthat specify the arguments that are to be passed tomain()in the launched process. The value of this field can beNULL. This field is ignored in OS X v10.4.initialEventThe first Apple Event to send to the launched process. The value of this field can be
NULL.Discussion
This structure is passed as a parameter to
LSOpenApplication,LSOpenItemsWithRole, andLSOpenURLsWithRole.Availability
Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
Specifies, by file-system reference, an application to launch, items to open, or both, along with related information.
Declaration
Objective-C
struct LSLaunchFSRefSpec { const FSRef *appRef; UInt32 numDocs; const FSRef *itemRefs; const AEDesc *passThruParams; LSLaunchFlags launchFlags; void *asyncRefCon; }; typedef struct LSLaunchFSRefSpec LSLaunchFSRefSpec;Fields
appRefA 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
FSRefdata type. Set this field toNULLto request that each item in theitemRefsarray be opened in its own preferred application.numDocsThe number of elements in the array specified by the
itemRefsfield. The value of this field can be0, in which case the application designated byappRefis launched without opening any items.itemRefsAn array of file-system references designating the item or items to open. If the value of
numDocsis0, this field is ignored and can be set toNULL.passThruParamsA 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 byappRef). See the Apple Event Manager Reference in the Carbon Interapplication Communication Documentation for a description of theAEDescdata type. The value of this field can beNULL.launchFlagsLaunch flags specifying how to launch each application (including whether to print or merely open documents); see Launch Flags for a description of these flags.
asyncRefConA 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.Discussion
This data type defines a file-based launch specification designating, by file-system reference, an application to launch, items to open, or both. To request that items be opened in a particular application, set
appRef,numDocs, anditemRefsaccordingly. To request that each designated item be opened in its own preferred application, setappReftoNULL. To request that a particular application be launched without opening any documents, setappRefaccordingly and setnumDocsto0.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.10.
-
Specifies, by URL, an application to launch, items to open, or both, along with related information.
Declaration
Objective-C
struct LSLaunchURLSpec { CFURLRef appURL; CFArrayRef itemURLs; const AEDesc *passThruParams; LSLaunchFlags launchFlags; void *asyncRefCon; }; typedef struct LSLaunchURLSpec LSLaunchURLSpec;Fields
appURLA Core Foundation URL reference designating the application to launch; see the CFURL Reference in the Core Foundation Reference Documentation for a description of the
CFURLRefdata type. The URL must have schemefileand contain a valid path to an application file or application bundle. Set this field toNULLto request that each item in theitemURLsarray be opened in its own preferred application.itemURLsA 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
CFArrayRefdata type. The value of this field can beNULL, in which case the application designated byappURLwill be launched without opening any items.passThruParamsA 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 byappURL). See the Apple Event Manager Reference in the Carbon Interapplication Communication Documentation for a description of theAEDescdata type. The value of this field can beNULL.launchFlagsLaunch flags specifying how to launch each application (including whether to print or merely open documents); see Launch Flags for a description of these flags.
asyncRefConA 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.Discussion
This data type defines a URL-based launch specification designating, by URL, an application to launch, items to open, or both. To request that items be opened in a particular application, set
appURLanditemURLsaccordingly. To request that each designated item be opened in its own preferred application, setappURLtoNULL. If the item URL’s scheme isfile(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 ashttp,ftp, ormailto). To request that a particular application be launched without opening any document, setappURLaccordingly and setitemURLstoNULL.Availability
Available in OS X v10.0 and later.
-
Contains requested information about an item.
Declaration
Objective-C
struct LSItemInfoRecord { LSItemInfoFlags flags; OSType filetype; OSType creator; CFStringRef extension; CFStringRef iconFileName; LSKindID kindID; }; typedef struct LSItemInfoRecord LSItemInfoRecord;Fields
flagsItem-information flags specifying information about the item; see Item-Information Flags for a description of these flags.
filetypeThe item’s file type.
creatorThe item’s creator signature.
extensionA 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
CFStringRefdata type.iconFileNameNo longer used.
kindIDNo longer used.
Discussion
This data type defines an item-information record used by the
LSCopyItemInfoForRefandLSCopyItemInfoForURLfunctions to return requested information about an item.Availability
Available in OS X v10.0 and later.
-
Data type of the
kindIDfield of an item-information record (LSItemInfoRecord); no longer used.Declaration
Objective-C
typedef UInt32 LSKindID;Availability
Available in OS X v10.0 and later.
Not available to 64-bit applications.
This section describes the constants defined in the Launch Services API.
-
Specify the desired role or roles for an application to claim with respect to an item or family of items.
Declaration
Swift
typealias LSRolesMask = OptionBitsObjective-C
typedef OptionBits LSRolesMask;enum { kLSRolesNone = 0x00000001 , kLSRolesViewer = 0x00000002 , kLSRolesEditor = 0x00000004 , kLSRolesShell = 0x00000008 , kLSRolesAll = 0xFFFFFFFF };Constants
-
kLSRolesNonekLSRolesNoneRequests 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.
-
kLSRolesViewerkLSRolesViewerRequests 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.
-
kLSRolesEditorkLSRolesEditorRequests the role
Editor(the application can read, present, manipulate, and save the item).Available in OS X v10.0 and later.
-
kLSRolesShellkLSRolesShellRequests the role
Shell(the application can execute the item).Available in OS X v10.4 and later.
-
kLSRolesAllkLSRolesAllAccepts any role with respect to the item.
Available in OS X v10.0 and later.
Discussion
This bit mask is passed to functions that find the preferred application for a given item or family of items (
LSGetApplicationForItem,LSGetApplicationForURL,LSGetApplicationForInfo), or that determine whether a given application can open a designated item (LSCanRefAcceptItem,LSCanURLAcceptURL), to specify the application’s desired role or roles with respect to the item. For example, to request only an editor application, specifykLSRolesEditor; if either an editor or a viewer application is acceptable, specifykLSRolesEditor | kLSRolesViewer.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
-
Specify how to launch an application.
Declaration
Swift
typealias LSLaunchFlags = OptionBitsObjective-C
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
-
kLSLaunchDefaultskLSLaunchDefaultsRequests launching in the default manner (as if the only flags set were
kLSLaunchNoParams,kLSLaunchAsync, andkLSLaunchStartClassic).Available in OS X v10.0 and later.
-
kLSLaunchAndPrintkLSLaunchAndPrintRequests that documents opened in the application be printed.
Available in OS X v10.0 and later.
-
kLSLaunchReserved2kLSLaunchReserved2Reserved for future use.
Available in OS X v10.0 and later.
-
kLSLaunchReserved3kLSLaunchReserved3Reserved for future use.
Available in OS X v10.0 and later.
-
kLSLaunchReserved4kLSLaunchReserved4Reserved for future use.
Available in OS X v10.0 and later.
-
kLSLaunchReserved5kLSLaunchReserved5Reserved for future use.
Available in OS X v10.0 and later.
-
kLSLaunchAndDisplayErrorskLSLaunchAndDisplayErrorsRequests that launch and open failures be displayed in the UI.
Available in OS X v10.4 and later.
-
kLSLaunchInhibitBGOnlykLSLaunchInhibitBGOnlyRequests that the launch be made to fail if the application is background-only.
Available in OS X v10.0 and later.
-
kLSLaunchDontAddToRecentskLSLaunchDontAddToRecentsRequests that the application or documents not be added to the Finder’s Recent Items menu.
Available in OS X v10.0 and later.
-
kLSLaunchDontSwitchkLSLaunchDontSwitchRequests that the application be launched without being brought to the foreground.
Available in OS X v10.0 and later.
-
kLSLaunchNoParamskLSLaunchNoParamsRequests that the application’s information property list be used to determine the launch parameters.
Available in OS X v10.0 and later.
-
kLSLaunchAsynckLSLaunchAsyncRequests 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.
-
kLSLaunchStartClassickLSLaunchStartClassicRequests 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.
-
kLSLaunchInClassickLSLaunchInClassicRequests that the application be forced to launch in the Classic emulation environment.
Available in OS X v10.0 and later.
-
kLSLaunchNewInstancekLSLaunchNewInstanceRequests that a new instance of the application be started, even if one is already running.
Available in OS X v10.0 and later.
-
kLSLaunchAndHidekLSLaunchAndHideRequests that the application be hidden as soon as it completes its launch sequence.
Available in OS X v10.0 and later.
-
kLSLaunchAndHideOtherskLSLaunchAndHideOthersRequests that other applications be hidden as soon as the opened application completes its launch sequence.
Available in OS X v10.0 and later.
-
kLSLaunchHasUntrustedContentskLSLaunchHasUntrustedContentsRequests that the items to be launched should be marked as untrusted.
Available in OS X v10.4 and later.
Discussion
They are passed in a launch specification structure (
LSLaunchFSRefSpecto theLSOpenFromRefSpecfunction orLSLaunchURLSpecto theLSOpenFromURLSpecfunction), to control the manner in which applications are launched.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
-
Specify what information to obtain about an item.
Declaration
Swift
typealias LSRequestedInfo = OptionBitsObjective-C
typedef OptionBits LSRequestedInfo;enum { kLSRequestExtension = 0x00000001 , kLSRequestTypeCreator = 0x00000002 , kLSRequestBasicFlagsOnly = 0x00000004 , kLSRequestAppTypeFlags = 0x00000008 , kLSRequestAllFlags = 0x00000010 , kLSRequestIconAndKind = 0x00000020 , kLSRequestExtensionFlagsOnly = 0x00000040 , kLSRequestAllInfo = 0xFFFFFFFF };Constants
-
kLSRequestExtensionkLSRequestExtensionRequests the item’s filename extension.
Available in OS X v10.0 and later.
-
kLSRequestTypeCreatorkLSRequestTypeCreatorRequests the item’s file type and creator signature.
Available in OS X v10.0 and later.
-
kLSRequestBasicFlagsOnlykLSRequestBasicFlagsOnlyRequests all item-information flags that are not application-specific: that is, all except
kLSItemInfoIsNativeAppthroughkLSItemInfoAppIsScriptable.Available in OS X v10.0 and later.
-
kLSRequestAppTypeFlagskLSRequestAppTypeFlagsRequests all application-specific item-information flags: that is,
kLSItemInfoIsNativeAppthroughkLSItemInfoAppIsScriptable.Available in OS X v10.0 and later.
-
kLSRequestAllFlagskLSRequestAllFlagsRequests all item-information flags.
Available in OS X v10.0 and later.
-
kLSRequestIconAndKindkLSRequestIconAndKindNot used.
Available in OS X v10.0 and later.
-
kLSRequestExtensionFlagsOnlykLSRequestExtensionFlagsOnlyRequests only the
kLSItemInfoExtensionIsHiddenitem-information flag.Available in OS X v10.1 and later.
-
kLSRequestAllInfokLSRequestAllInfoRequests all available item information.
Available in OS X v10.0 and later.
Discussion
These flags are passed to the
LSCopyItemInfoForRefandLSCopyItemInfoForURLfunctions to specify the type of information to be obtained in an item-information record; see LSItemInfoRecord for a description of this structure.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
-
Constants used to retrieve item attributes.
Declaration
Swift
let kLSItemContentType: CFString! let kLSItemFileType: CFString! let kLSItemFileCreator: CFString! let kLSItemExtension: CFString! let kLSItemDisplayName: CFString! let kLSItemDisplayKind: CFString! let kLSItemRoleHandlerDisplayName: CFString! let kLSItemIsInvisible: CFString! let kLSItemExtensionIsHidden: CFString!Objective-C
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
-
kLSItemContentTypekLSItemContentTypeThe item’s content type identifier, which is a uniform type identifier string. The value type of this attribute theis
CFStringRef.Use the URL resource property
kCFURLTypeIdentifierKey/NSURLTypeIdentifierKeyinstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemFileTypekLSItemFileTypeThe item’s file type (OSType). The value type of this attribute is
CFStringRef.Use the URL resource property
kCFURLTypeIdentifierKey/NSURLTypeIdentifierKeyto get the file's UTI instead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemFileCreatorkLSItemFileCreatorThe item’s file creator (OSType). The value type of this attribute is
CFStringRef.Use the URL resource property
kCFURLTypeIdentifierKey/NSURLTypeIdentifierKeyto get the file's UTI instead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemExtensionkLSItemExtensionThe item’s filename extension. The value type of this attribute is
CFStringRef.Use
CFURLCopyPathExtensionorpathExtensioninstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemDisplayNamekLSItemDisplayNameThe 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.Use
LSCopyDisplayNameForURLor the URL resource propertykCFURLLocalizedNameKey/NSURLLocalizedNameKeyinstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemDisplayKindkLSItemDisplayKindThe localized kind string describing the item’s type. The value type of this attribute is
CFStringRef.Use
LSCopyKindStringForURLor the URL resource propertykCFURLLocalizedTypeDescriptionKey/NSURLLocalizedTypeDescriptionKeyinstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemRoleHandlerDisplayNamekLSItemRoleHandlerDisplayNameThe 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.Instead of using this constant, resolve the desired role handler for the file, then use the URL resource property
kCFURLLocalizedNameKey/NSURLLocalizedNameKeyon the role handler's URL.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemIsInvisiblekLSItemIsInvisibleA value of
kCFBooleanTrueif the item is normally hidden from users; otherwise,kCFBooleanFalse. The value type of this attribute isCFBooleanRef.Use the URL resource property
kCFURLIsHiddenKey/NSURLIsHiddenKeyinstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
-
kLSItemExtensionIsHiddenkLSItemExtensionIsHiddenA value of
kCFBooleanTrueif the item’s extension is set to be hidden; otherwise,kCFBooleanFalse. The value type of this attribute isCFBooleanRef.Use
LSSetExtensionHiddenForURLor the URL resource propertykCFURLHasHiddenExtensionKey/NSURLHasHiddenExtensionKeyinstead.Available in OS X v10.4 and later.
Deprecated in OS X v10.10.
Import Statement
-
-
Provide information about an item.
Declaration
Swift
typealias LSItemInfoFlags = OptionBitsObjective-C
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
-
kLSItemInfoIsPlainFilekLSItemInfoIsPlainFileItem is a data file (and not, for example, a directory, volume, or UNIX symbolic link).
Available in OS X v10.0 and later.
-
kLSItemInfoIsPackagekLSItemInfoIsPackageItem is a packaged directory.
Available in OS X v10.0 and later.
-
kLSItemInfoIsApplicationkLSItemInfoIsApplicationItem is a single-file or packaged application.
Available in OS X v10.0 and later.
-
kLSItemInfoIsContainerkLSItemInfoIsContainerItem is a directory (includes packages) or volume.
Available in OS X v10.0 and later.
-
kLSItemInfoIsAliasFilekLSItemInfoIsAliasFileItem is an alias file (includes symbolic links).
Available in OS X v10.0 and later.
-
kLSItemInfoIsSymlinkkLSItemInfoIsSymlinkItem is a UNIX symbolic link.
Available in OS X v10.0 and later.
-
kLSItemInfoIsInvisiblekLSItemInfoIsInvisibleItem is invisible, because either its name begins with a period or its
isInvisibleFinder flag is set.Available in OS X v10.0 and later.
-
kLSItemInfoIsNativeAppkLSItemInfoIsNativeAppItem is an application that can run natively in OS X.
Available in OS X v10.0 and later.
-
kLSItemInfoIsClassicAppkLSItemInfoIsClassicAppItem is an application that cannot run natively and must be launched in the Classic emulation environment.
Available in OS X v10.0 and later.
-
kLSItemInfoAppPrefersNativekLSItemInfoAppPrefersNativeItem 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
kLSItemInfoIsNativeAppis set.Available in OS X v10.0 and later.
-
kLSItemInfoAppPrefersClassickLSItemInfoAppPrefersClassicItem 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
kLSItemInfoIsNativeAppis set.Available in OS X v10.0 and later.
-
kLSItemInfoAppIsScriptablekLSItemInfoAppIsScriptableItem is an application that can be scripted.
Available in OS X v10.0 and later.
-
kLSItemInfoIsVolumekLSItemInfoIsVolumeItem is the root directory of a volume or mount point.
Available in OS X v10.0 and later.
-
kLSItemInfoExtensionIsHiddenkLSItemInfoExtensionIsHiddenItem has a hidden filename extension.
Available in OS X v10.1 and later.
Discussion
These flags are set in an item-information record to provide information about an item; see LSItemInfoRecord for a description of this structure.
Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
-
Specify behavior to observe when testing whether an application can accept (open) an item.
Declaration
Swift
typealias LSAcceptanceFlags = OptionBitsObjective-C
typedef OptionBits LSAcceptanceFlags;enum { kLSAcceptDefault = 0x00000001 , kLSAcceptAllowLoginUI = 0x00000002 };Constants
-
kLSAcceptDefaultkLSAcceptDefaultRequests the default behavior (as opposed to the behavior specified by the
kLSAcceptAllowLoginUIflag).Available in OS X v10.0 and later.
-
kLSAcceptAllowLoginUIkLSAcceptAllowLoginUIRequests that the user interface to log in be presented if necessary. If
LSCanRefAcceptItemorLSCanURLAcceptURLis 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 thekLSAcceptAllowLoginUIflag.Available in OS X v10.0 and later.
Discussion
These flags are passed to the functions
LSCanRefAcceptItemandLSCanURLAcceptURL.Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
-
Specify the options for controlling how content handlers are selected.
Declaration
Swift
typealias LSHandlerOptions = OptionBitsObjective-C
typedef OptionBits LSHandlerOptions;enum { kLSHandlerOptionsDefault = 0, kLSHandlerOptionsIgnoreCreator = 1 };Constants
-
kLSHandlerOptionsDefaultkLSHandlerOptionsDefaultWhen 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.
-
kLSHandlerOptionsIgnoreCreatorkLSHandlerOptionsIgnoreCreatorWhen 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.
Import Statement
import CoreServicesAvailability
Available in OS X v10.4 and later.
-
-
Represents an invalid filename extension index.
Declaration
Objective-C
enum { kLSInvalidExtensionIndex = 0xFFFFFFFF };Constants
-
kLSInvalidExtensionIndexkLSInvalidExtensionIndexThe value obtained by the
LSGetExtensionInfofunction if the filename does not contain a valid extension.Available in OS X v10.1 through OS X v10.4.
Not available to 64-bit applications.
Import Statement
-
-
Represent an unknown file type or creator.
Declaration
Objective-C
enum { kLSUnknownType = 0, kLSUnknownCreator = 0 };Constants
-
kLSUnknownTypekLSUnknownTypeThe value to supply as the file type (for example, to the
LSGetApplicationForInfofunction) if no file type information is available.Available in OS X v10.0 and later.
-
kLSUnknownCreatorkLSUnknownCreatorThe value to supply as the creator signature if no file creator information is available.
Available in OS X v10.0 and later.
Import Statement
-
-
The following constants are no longer used.
Declaration
Swift
typealias LSInitializeFlags = OptionBitsObjective-C
typedef OptionBits LSInitializeFlags;enum { kLSInitializeDefaults = 0x00000001 };enum { kLSUnknownKindID = 0 };enum { kLSMinCatInfoBitmap = (kFSCatInfoNodeFlags | kFSCatInfoParentDirID | kFSCatInfoFinderInfo | kFSCatInfoFinderXInfo ) };Constants
-
kLSInitializeDefaultskLSInitializeDefaultsFormerly passed to the
LSInitfunction, which is no longer used.Available in OS X v10.0 and later.
-
kLSUnknownKindIDkLSUnknownKindIDA possible value of the
kindIDfield of an item-information record, which is no longer used.Available in OS X v10.0 and later.
Not available to 64-bit applications.
-
kLSMinCatInfoBitmapkLSMinCatInfoBitmapA minimal catalog information bitmap; no longer used.
Available in OS X v10.1 and later.
Import Statement
import CoreServicesAvailability
Available in OS X v10.0 and later.
-
The table below lists the most common result codes returned by Launch Services functions.
-
The application cannot be run because it is inside a Trash folder.
Value
-10660
Description
The application cannot be run because it is inside a Trash folder.
Available in OS X v10.3 and later.
-
An unknown error has occurred.
Value
-10810
Description
An unknown error has occurred.
Available in OS X v10.0 and later.
-
The item to be registered is not an application.
Value
-10811
Description
The item to be registered is not an application.
Available in OS X v10.0 and later.
-
Data of the desired type is not available (for example, there is no kind string).
Value
-10813
Description
Data of the desired type is not available (for example, there is no kind string).
Available in OS X v10.0 and later.
-
No application in the Launch Services database matches the input criteria.
Value
-10814
Description
No application in the Launch Services database matches the input criteria.
Available in OS X v10.0 and later.
-
Not currently used.
Value
-10815
Description
Not currently used.
Available in OS X v10.0 and later.
-
Not currently used.
Value
-10816
Description
Not currently used.
Available in OS X v10.0 and later.
-
Data is structured improperly (for example, an item’s information property list is malformed). Not used in OS X v10.4.
Value
-10817
Description
Data is structured improperly (for example, an item’s information property list is malformed). Not used in OS X v10.4.
Available in OS X v10.0 and later.
-
A launch of the application is already in progress.
Value
-10818
Description
A launch of the application is already in progress.
Available in OS X v10.0 and later.
-
Not currently used.
Value
-10819
Description
Not currently used.
Available in OS X v10.0 and later.
-
Not currently used.
Value
-10820
Description
Not currently used.
Available in OS X v10.0 and later.
-
Not currently used.
Value
-10821
Description
Not currently used.
Available in OS X v10.0 and later.
-
There is a problem communicating with the server process that maintains the Launch Services database.
Value
-10822
Description
There is a problem communicating with the server process that maintains the Launch Services database.
Available in OS X v10.0 and later.
-
The filename extension to be hidden cannot be hidden.
Value
-10823
Description
The filename extension to be hidden cannot be hidden.
Available in OS X v10.1 and later.
-
Not currently used.
Value
-10824
Description
Not currently used.
Available in OS X v10.3 and later.
-
The application to be launched cannot run on the current Mac OS version.
Value
-10825
Description
The application to be launched cannot run on the current Mac OS version.
Available in OS X v10.3 and later.
-
The user does not have permission to launch the application (on a managed network).
Value
-10826
Description
The user does not have permission to launch the application (on a managed network).
Available in OS X v10.3 and later.
-
The executable file is missing or has an unusable format.
Value
-10827
Description
The executable file is missing or has an unusable format.
Available in OS X v10.3 and later.
-
The Classic emulation environment was required but is not available.
Value
-10828
Description
The Classic emulation environment was required but is not available.
Available in OS X v10.3 and later.
-
The application to be launched cannot run simultaneously in two different user sessions.
Value
-10829
Description
The application to be launched cannot run simultaneously in two different user sessions.
Available in OS X v10.3 and later.
Copyright © 2014 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2014-10-16
