Launch Services Tasks
This chapter summarizes how to use Launch Services to perform common tasks in your application.
The most common operation you’ll want to perform with Launch Services is opening applications, document files, and URLs. Depending on the circumstances, you can use any of four Launch Services functions for this purpose:
Opening Items by File-System Reference
When an item you wish to open is identified by a file-system reference (
FSRef), the simplest way to open it is with
LSOpenFSRef. You simply supply the file-system reference and Launch Services opens the item in a straightforward, no-frills, default way:
If the designated item is 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 (brought to the front of the screen) and sent an
'rapp'(“reopen application”) Apple event.
If the designated item is a document, its preferred application is launched (or activated if it was already running) and sent an
'odoc'(“open document”) Apple event instructing it to open the document.
LSOpenFSRef in turn calls the more general function
LSOpenFromRefSpec, a “Swiss Army knife” function that provides access to the full range of options for opening applications and documents. You can call this function directly yourself if you need to request something other than the default behavior. For instance, you can use it to:
Open more than one document at a time, in either the same or different applications
Force a document to open in an application other than its own preferred application
Open documents for printing rather than for simple viewing or editing
Force an application to open in the Classic emulation environment
Open a specified application and hide all others
Prevent an application or document from being added to the Finder’s Recent Items menu
Instead of a direct file-system reference to an item to be opened, you supply a pointer to a launch specification, a data structure of type
LSLaunchFSRefSpec that identifies one or more items along with additional information about how to open them:
To open one or more documents, pass an array of file-system references in the launch specification’s
numDocsfield tells how many there are. If the
appReffield is also non-null, it specifies the application in which to open the documents; otherwise, each document will be opened in its own preferred application.
To open an application without specifying any documents, pass a file-system reference to the application in the launch specification’s
appReffield and set the
The additional information in the launch specification includes:
A flag word (
launchFlags) containing various launch options to control the manner in which the application is opened; see “Launch Options”
A pointer to an optional Apple event descriptor record (
passThruParams) containing parameter information to be passed with the Apple event the application receives on opening
An optional reference constant (
asyncRefCon) to be passed to your Carbon event handler routine for asynchronous launch notifications, as described under “Synchronous and Asynchronous Launch”
LSOpenFromRefSpec, the output parameter
outLaunchedRef holds a pointer to a file-system reference that the function will set to indicate the application that was opened (or the first such application, in the case of multiple documents opened in different applications). If this information is not of interest, you can set this parameter to
Opening Items by URL
To open a URL, you use the Launch Services function
LSOpenFromURLSpec. These are analogous to
LSOpenFromRefSpec, but accept Core Foundation URL references (
CFURLRef) instead of file-system references. These functions also are often useful when you have a file-system pathname to an application or document to be opened: you can construct a URL with scheme
file containing the path and then use this URL in place of a file-system reference to open the item. The
LSOpenFromURLSpec functions are the only way to open URLs with other schemes, such as
LSOpenFSRef for file-system references,
LSOpenCFURLRef opens a designated URL in its preferred application in the default way. The more general function
LSOpenFromURLSpec accepts a launch specification (analogous to the one for
LSOpenFromRefSpec but of type
LSLaunchURLSpec rather than
LSLaunchFSRefSpec) specifying in greater detail the manner in which the URL is to be opened. As with
LSOpenFromRefSpec, you can call this function directly yourself if you need to request something other than the default behavior provided by
LSOpenFromURLSpec determine what application to use to open a specified URL, launch the application (or activate it if it is already running), and send it an Apple event instructing it to open the URL. (With
LSOpenFromURLSpec, you can override the URL’s preferred application by explicitly designating another application in the launch specification’s
appURL field.) Ordinarily, the application receives a
'GURL' (“get URL”) Apple event; but if the URL’s scheme is
file and the application doesn’t claim to accept URLs with this scheme, it is sent an
'odoc' (“open document”) Apple event instead.
Like their counterparts for file-system references, both of the URL-based functions can optionally return information about which application was actually opened (or the first, in the case of multiple URLs opened in different applications). This information is passed back via a Core Foundation URL reference to which you supply a pointer in the output parameter
outLaunchedURL. You can set this parameter to
NULL if the identity of the application is not of interest.
Finding an Item’s Preferred Application
To find the preferred application for a document file, URL, or MIME type without opening it, use the Launch Services function
LSCopyApplicationForMIMEType, respectively. You identify the item of interest with a file-system reference (
FSRef) to the document, a Core Foundation URL reference (
CFURLRef) to the URL, or a Core Foundation string reference (
CFStringRef) to a string specifying the MIME type. Another Launch Services function,
LSGetApplicationForInfo, finds the preferred application for a family of documents defined by their file type, creator signature, filename extension, or any combination of these characteristics.
In each case, you must supply a role mask (
LSRolesMask) specifying one or more roles (
None) that the application should claim with respect to the given item or family of items. (Note that
None does not mean “no role at all,” but rather refers to a specific role that the application can claim with respect to the item: that of providing identifying information such as a display name and icon file without actually being able to open the item itself.) If you don’t care what role the application claims, use the mask value
To receive the result, you pass a pointer to a file-system reference (in the
outAppRef parameter), a Core Foundation URL reference (in the
outAppURL parameter), or both; Launch Services will set the designated data structure to refer to the item’s preferred application. You can pass a null pointer for either of these parameters if you don’t care to receive the result in that form, but at least one of the two pointers must be non-null. (In the case of
LSCopyApplicationForMIMEType, only the URL option is available; there is no
To find all known applications that can open a given item with a specified role, use the Launch Services function
LSCopyApplicationURLsForURL. Although this function can only accept a URL reference and not a file-system reference, you can use it for document files as well, by passing a URL with scheme
file referring to the desired document.
The Launch Services function
LSFindApplicationForInfo locates an application based on its name, creator signature, bundle ID, or any combination of these characteristics. (Note that this differs from
LSGetApplicationForInfo in that the specified characteristics apply to the application itself, rather than to the document files it can open.) As with other Launch Services functions discussed earlier, you can receive the result as either a file-system reference, a URL, or both, by passing pointers to the appropriate data structures to be filled with the information.
Testing Whether an Application Can Open an Item
Often it is useful to find out whether a given application claims the ability to open a particular document or URL. The Launch Services functions
LSCanURLAcceptURL provide this information. You supply either file-system references or URL references to the item and the target application, along with a role mask and a flag word controlling certain technical aspects of the function’s behavior; the function responds by setting a Boolean variable, to which you provide a pointer, to indicate whether the application can accept the designated item.
Registering an Application
It isn’t ordinarily necessary to register an application explicitly with Launch Services, since this is done for you automatically whenever the application becomes known to the Finder, the system is booted, or a new user logs in (see “Application Registration”). On those rare occasions when you do need to register an application explicitly (such as in a custom installer program), you can use the Launch Services function
LSRegisterURL, depending on whether the application is identified with a file-system reference or a Core Foundation URL reference. In either case, the application and its document binding information are copied into the Launch Services database, making the application available for opening documents and URLs.
Obtaining Information About an Item
You can use the Launch Services functions
LSCopyItemInfoForURL to obtain a variety of information about file-system objects such as applications, documents, folders, or volumes. You supply a file-system reference or a Core Foundation URL reference (with scheme
file) to identify the item of interest, along with a flag word (
LSRequestedInfo) specifying the information you want and a pointer to an item information record (
LSItemInfoRecord) in which to receive back the information. The information in this record can include the item’s file type, creator signature, filename extension, and various flags describing attributes of the item (see “Item Information”).
Two other pieces of information about an item that you may find useful are its display name (used for displaying its name to the user on the screen) and its kind string (used, for instance in the Finder’s Get Info window or the Kind column of the Finder’s list view, to characterize the item’s general nature, such as
QuickTime Movie, or
FrameMaker Document). You can obtain the display name with the Launch Services function
LSCopyDisplayNameForURL and the kind string with