bookmarkData(options:includingResourceValuesForKeys:relativeTo:)

Returns a bookmark for the URL, created with specified options and resource values.

Declaration

func bookmarkData(options: NSURL.BookmarkCreationOptions = [], includingResourceValuesForKeys keys: [URLResourceKey]?, relativeTo relativeURL: URL?) throws -> Data

Parameters

options:
Options taken into account when creating the bookmark for the URL. The possible flags (which can be combined with bitwise OR operations) are described in Bookmarkcreationoptions.
To create a security-scoped bookmark to support App Sandbox, include the Withsecurityscope flag. When you later resolve the bookmark, you can use the resulting security-scoped URL to obtain read/write access to the file-system resource pointed to by the URL.
If you instead want to create a security-scoped bookmark that, when resolved, enables you to obtain read-only access to a file-system resource, bitwise OR this parameter’s value with both the Withsecurityscope option and the Securityscopeallowonlyreadaccess option.
keys:
An array of names of URL resource properties to store as part of the bookmark. You can later access these values (without resolving the bookmark) by calling the Resourcevalues(forkeys:frombookmarkdata:) method.
The values of these properties must be of a type that the bookmark generation code can serialize. Specifically, the values can contain any of the following primitive types:
- NSString or CFString
- NSData or CFData
- NSDate or CFDate
- NSNumber or CFNumber
- CFBoolean
- NSURL or CFURL
- kCFNull or Nsnull
- CFUUID
In addition, the properties can contain the following collection classes:
- NSArray or CFArray containing only the above primitive types
- NSDictionary or CFDictionary with NSString or CFString keys, in which all values contain only the above primitive types
relativeURL:
The URL that the bookmark data will be relative to.
If you are creating a security-scoped bookmark to support App Sandbox, use this parameter as follows:
- To create an app-scoped bookmark, use a value of nil.
- To create a document-scoped bookmark, use the absolute path (despite this parameter’s name) to the document file that is to own the new security-scoped bookmark.
App Sandbox does not restrict which URL values may be passed to this parameter.

Return Value

A bookmark for the URL.

Discussion

This method returns bookmark data that can later be resolved into a URL object for a file even if the user moves or renames it (if the volume format on which the file resides supports doing so).

You can also use this method to create a security-scoped bookmark to support App Sandbox. Before you do so, you must first enable the appropriate entitlements for your app, as described in Enabling Security-Scoped Bookmark and URL Access. In addition, be sure to understand the behavior of the options and relativeURL parameters.

For an app-scoped bookmark, no sandboxed app other than the one that created the bookmark can obtain access to the file-system resource that the URL (obtained from the bookmark) points to. Specifically, a bookmark created with security scope fails to resolve if the caller does not have the same code signing identity as the caller that created the bookmark.

For a document-scoped bookmark, any sandboxed app that has access to the bookmark data itself, and has access to the document that owns the bookmark, can obtain access to the resource.