Property List Keys for Launch Services

Launch Services obtains the information it needs about an application from the application’s bundle information property list (Info.plist) or, in the case of a single-file application, from a 'plst' resource in the application’s resource fork. Table 1-1 shows the relevant keys. (See Runtime Configuration Guidelines for more detailed information on these and other property-list keys.)

The CFBundleDisplayName key specifies the application’s display name; this key can be localized by including it in the InfoPlist.strings file of the appropriate .lproj subdirectory. CFBundleIconFile identifies the file containing the icon image to be used for displaying the application on the screen. CFBundleIdentifier defines the application’s bundle identifier, a unique identifying string used to locate its bundle at runtime. CFBundleSignature is the application’s creator signature, a four-character code that identifies document files belonging to this application.

The keys LSRequiresCarbon, LSPrefersCarbon, LSRequiresClassic, LSPrefersClassic, LSBackgroundOnly, and LSUIElement specify various aspects of the environment in which the application should be run. A string value of “1” for any of these keys declares the corresponding attribute to be true. (In OS X version 10.2 or later, these keys can also take values of type Boolean or Number rather than String, but such values are not supported in earlier system versions.)

The LSRequiresCarbon, LSPrefersCarbon, LSRequiresClassic, and LSPrefersClassic keys are mutually exclusive: at most one of them can be set to "1". You can obtain information about the values of these four keys via the flags field of the item-information record returned by the Launch Services functions LSCopyItemInfoForRef and LSCopyItemInfoForURL. LSRequiresCarbon specifies that the application must be run natively in OS X and cannot be run in the Classic emulation environment; LSRequiresClassic means the reverse. LSPrefersCarbon and LSPrefersClassic indicate that the application can run in either environment but has a preference for one or the other; the Finder offers the user the choice of which environment to use by displaying a checkbox in the application’s Get Info window labeled “Open in the Classic environment,” initially selected or deselected depending on which key the application itself specifies.

If none of the four keys is set to "1", Launch Services infers the application’s required or preferred environment by other means:

• If the application is bundled, it is assumed to be a native Mac app and is run natively (equivalent to LSRequiresCarbon).

• If the application is not bundled and its resource fork contains a 'plst' or 'carb' resource, it is assumed to be compatible with either environment but prefer to run natively (equivalent to LSPrefersCarbon).

• If the application is not bundled and has no 'plst' or 'carb' resource, it is assumed to be a Classic application incapable of running natively (equivalent to LSRequiresClassic).

The most important property-list keys, for Launch Services’ purposes, are CFBundleDocumentTypes and CFBundleURLTypes. The value associated with each of these keys is an array of dictionaries (type-definition and scheme-definition dictionaries, respectively), each of which declares (claims) a family of document files or URLs that the application is prepared to handle. Launch Services uses this information in deciding what application to use to open a given document file or URL.

Application Roles

In declaring a document type, an application can claim a particular role with respect to documents of that type, defining the kinds of operations the application is capable of performing on such documents. The role is declared via the CFBundleTypeRole key in the application’s type-definition dictionary for the given document type. Launch Services recognizes three such roles:

• Editor. The application can read, present, manipulate, and save documents of the given type.

• Viewer. The application can read and present documents of the given type, but cannot manipulate or save them.

• None. The application cannot operate on documents of the given type. This role is useful for declaring information about document types that the application is incapable of opening, such as their abstract names and icon files.

Launch Services defines a set of bit-mask constants of type LSRolesMask denoting the various possible roles. Launch Services functions that find the preferred application for a document or family of documents (LSGetApplicationForItem, LSGetApplicationForURL, and LSGetApplicationForInfo), or that determine whether a given application can open a designated document (LSCanRefAcceptItem and LSCanURLAcceptURL), take a parameter of this type to specify the application’s desired role with respect to the document.

Opening Applications

When the item to be opened is an application (or a URL with scheme file designating an application), Launch Services checks whether the application is already running and proceeds accordingly:

• If the application is not already running, Launch Services starts it up (launches it) and sends it an 'oapp' (“open application”) Apple event. The application should respond to this event by performing its normal startup processing.

• If the application is already running, Launch Services activates it (brings it to the front of the screen) and sends it an 'rapp' (“reopen application”) Apple event. This instructs the application to take some additional action, if necessary, to provide visual feedback to the user that it has become active: for example, it might open an empty document window or a document creation dialog if it has no other windows already open.

In either case, Launch Services adds the application to the Recent Items submenu in the Apple menu.

Opening Documents

If the item to be opened is a document (or a URL with scheme file designating a document file), Launch Services must first determine what application to use to open the item. This is known as the item’s preferred application. As described under User-Specified Binding Preferences, the OS X user interface allows the user to specify an explicit binding between a document and its preferred application. If such an explicit binding has been specified, it takes precedence over any other considerations; if not, Launch Services uses a set of implicit binding criteria to determine the preferred application, as described under Preferred Applications.

Once the preferred application has been determined, Launch Services launches or activates it (depending on whether it is already running) and sends it an 'odoc' (“open document”) Apple event instructing it to open the specified document. (If the document is to be printed rather than merely opened, a 'pdoc' (“print document”) Apple event is sent instead of 'odoc'; in the case of a file URL, if the application claims to handle URLs with that scheme, it is sent a ‘GURL' (“get URL”) Apple event instead.)

Finally, Launch Services adds both the application and the document (or URL) to the Recent Items submenus in the Apple menu.

Opening URLs

If the item to be opened is a URL with a scheme other than file, it is opened in essentially the same way as a document, but with the following exceptions:

• As described under Preferred Applications, the implicit binding criteria for selecting a preferred application are based on the URL’s scheme component rather than on a creator signature, file type, or filename extension.

• The Apple event sent to the application after launching or activating it is 'GURL' (“get URL”) rather than 'odoc' (“open document”).

After the preferred application is launched or activated, Launch Services adds the application to the Recent Items submenu in the Apple menu.

Launch Options

When opening an application (whether by itself or to open one or more documents or URLs), you can specify various launch options to control the manner in which it is launched or activated. These can include:

• Whether to open the documents or URLs (if any) in a specifically designated application or in their own preferred applications

• Whether to print the documents or URLs (if any) or merely open them

• Whether to add the application and the documents (if any) to the Finder’s Recent Items menu or to suppress this action

• Whether to permit the application to open in the background or to fail if it is a background-only application

• Whether to open the application without bringing it to the foreground

• Whether to permit the application to open in the Classic emulation environment or to fail if it is a Classic-only application

• Whether to launch a new instance of the application, even if another instance is already running

• Whether to hide the application after launching it

• Whether to hide all other applications after launching this one

• Whether to launch the application synchronously or asynchronously (see next section)

Synchronous and Asynchronous Launch

One of the options you can specify when launching an application is whether to launch it synchronously or asynchronously:

• In a synchronous launch, control does not return from the Launch Services function launching the application until the application has completed its launch sequence (indicated visually to the user when the application’s icon stops “bouncing” in the Dock).

• In an asynchronous launch, control returns immediately, while the icon in the Dock is still “bouncing.” When the launch sequence has been completed, your application is notified with a Carbon event of type kEventAppLaunchNotification. You can install an event handler callback routine to respond to this event in whatever way is appropriate. In your call to the Launch Services function that launches the application, you can supply an arbitrary 4-byte reference constant that will be passed back to your handler routine as part of the notification event.

Choosing the Binding Preference for a File

The user can specify a preferred application for a file by selecting the item in the Finder and choosing the Get Info command (see Figure 1-1).

The Open With pane of the Get Info window contains a pop-up menu listing all known applications in the Launch Services database that claim to accept the selected item (see Figure 1-2). The user can then choose an application from the menu to become the item’s preferred application (Figure 1-3).

Clicking the Change All button (Figure 1-4) makes the chosen application the preferred application for all items of the same document or URL type, rather than just for the single item selected.

Occasionally, a user may wish to designate a preferred application that doesn’t claim to accept a given document or URL. (This might be useful, for instance, for opening documents in a text-encoded format, such as HTML, as unencoded text in a text editor.) The Other item in the Open With pane’s pop-up menu opens the dialog shown in Figure 1-5, in which the user can navigate to the desired application. The All Applications item in the pop-up menu labeled Show at the top of the dialog allows any desired application to be selected; Recommended Applications causes those not claiming to accept the item to be dimmed.

Choosing the Binding Preference for a URL

There is no system-level user interface for setting non-file URL scheme handlers. However, individual applications can allow users to choose a preferred application for a specific URL scheme. For example:

• The Safari application allows users to set the http: handler by choosing a default web browser.

• The Mail application allows users to set the mailto: handler by choosing a default email reader.

Preferred Application for a Document

For individual document files (whether specified by a file-system reference or a URL with scheme file), the criteria are as follows:

1. If the user has specified an explicit binding for the document (or for the entire document type to which it belongs), the preferred application is the one the user has specified.

2. If the document has a filename extension (or if one has been specified as a parameter to LSGetApplicationForInfo), find all applications in the Launch Services database that claim to accept documents with that extension.

3. If the document carries a four-character file type (or if one has been specified as a parameter), find all applications that claim to accept files of that type.

4. If more than one application has been found as a result of steps 2–3, apply the following criteria in the order shown:

   1. If the document carries a four-character creator signature (or if one has been specified as a parameter), give preference to any application that claims to accept documents with that signature (typically the application to which the signature belongs).

   2. Give preference to native OS X applications over those that run in the Classic emulation environment.

   3. Give preference to applications residing on the boot volume over those residing on other file-system volumes.

   4. Give preference to applications residing on a local volume over those residing on a remote volume.

   5. If two or more versions of the same application have been found, give preference to the one with the latest version number as identified by CFBundleVersion.

If two or more candidate applications remain after all of the foregoing criteria have been applied, Launch Services chooses one of the remaining applications in an unspecified manner.

Preferred Application for a URL

The criteria for URLs with schemes other than file are similar to those for document files, except that the search is based on the URL’s scheme rather than on file characteristics such as the creator signature, filename extension, and file type:

1. If the user has specified an explicit binding for the URL (or for the entire URL type to which it belongs), the preferred application is the one the user has specified.

2. If no explicit binding has been specified, find all applications in the Launch Services database that claim to accept URLs with the given scheme.

3. If more than one application has been found in step 2, apply the following criteria in the order shown:

   1. Give preference to native OS X applications over those that run in the Classic emulation environment.

   2. Give preference to applications residing on the boot volume over those residing on other file-system volumes.

   3. Give preference to applications residing on a local volume over those residing on a remote volume.

   4. If two or more versions of the same application have been found, give preference to the one with the latest version number.

If two or more candidate applications remain after all of the foregoing criteria have been applied, Launch Services chooses one of the remaining applications in an unspecified manner.