Contents

LSOpenFromRefSpec(_:_:)

Opens one or more items with a file-system reference in either their preferred apps or a designated app.

Declaration

func LSOpenFromRefSpec(_ inLaunchSpec: UnsafePointer<LSLaunchFSRefSpec>!, _ outLaunchedRef: UnsafeMutablePointer<FSRef>!) -> OSStatus

Parameters

  • inLaunchSpec:

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

  • outLaunchedRef:

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

Return Value

A result code; see Result Codes.

Discussion

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

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

  • 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 macOS 10.4 and later, LSOpenItemsWithRole(_:_:_:_:_:_:_:) is the preferred way of opening items.

Version-Notes

Thread-safe since Mac OS version 10.2.

See Also

Deprecated Functions