Launch Services Tasks

This chapter summarizes how to use Launch Services to perform common tasks in your application.

Opening Items

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: LSOpenFSRef, LSOpenFromRefSpec, LSOpenCFURLRef, or LSOpenFromURLSpec.

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 itemRefs field; the numDocs field tells how many there are. If the appRef field 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 appRef field and set the itemRefs field to NULL and numDocs to 0.

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

For both LSOpenFSRef and 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 NULL.

Opening Items by URL

To open a URL, you use the Launch Services function LSOpenCFURLRef or LSOpenFromURLSpec. These are analogous to LSOpenFSRef and 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 LSOpenCFURLRef and LSOpenFromURLSpec functions are the only way to open URLs with other schemes, such as http, ftp, or mailto.

Like 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 LSOpenCFURLRef.

Both LSOpenCFURLRef and 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 LSGetApplicationForItem, LSGetApplicationForURL, or 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 (Editor, Viewer, or 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 kLSRolesAll.

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 outAppRef parameter.)

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 LSCanRefAcceptItem and 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 LSRegisterFSRef or 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 LSCopyItemInfoForRef and 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 Application, Folder, Alias, JPEG Picture, QuickTime Movie, or FrameMaker Document). You can obtain the display name with the Launch Services function LSCopyDisplayNameForRef or LSCopyDisplayNameForURL and the kind string with LSCopyKindStringForRef, LSCopyKindStringForURL, LSCopyKindStringForTypeInfo, or LSCopyKindStringForMIMEType.



Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-12-16