SecurityScopedBookmarks Icon

SecurityScopedBookmarks

Overview

This drop-in class preserves file and directory access rights between sessions.

OS-X can be quite restrictive (and rightly so!) when it comes to an applications file access rights to files outside its default space. The user has to explicitly allow this access. This is normally done through open and save dialogues. Good application design also stores references to files that were once opened (or saved) by a user so that he can use a shortcut to re-open such files. For example by implementing an “Open -> Recent” file menu.

The restrictions imposed by OS-X means that we have to ask the user again for access rights, unless we store those access rights the first time a user opens/saves a file. This is where the SecurityScopedBookmarks (SSB) come in handy. This is a drop-in class that with just 3 hooks, allows your application to store/reload file access rights.

The three hooks are simple: When a file is opened or saved, the access rights must be registered by the SSB. Then when quitting the application the SSB must be told to store the access rights, and on startup it must be told to read the acces rights. These hooks are easily called as follows:

  1. securityScopedBookmarks.add(url)
  2. securityScopedBookmarks.save()
  3. securityScopedBookmarks.restore()

That is all, though there are more API calls available to manage the bookmarks. Side note: The data is stored in the Application Support directory.

The SecurityScopedBookmarks needs SwifterJSON (which is available for free from Github)

The public interface to the SecurityScopedBookmarks is as follows:

let securityScopedBookmarks = SecurityScopedBookmarks() /// Implementation of the equatable protocol for the enum SecurityScopedBookmarks.Result func == (lhs: SecurityScopedBookmarks.Result, rhs: SecurityScopedBookmarks.Result) -> Bool {} /// This class manages security scoped bookmarks. See the singleton securityScopedBookmarks for a description on how to use this class. class SecurityScopedBookmarks { /// The type of return parameter for some of the methods on this object. enum Result: Equatable, CustomStringConvertible { case SUCCESS case NO_FAILURE case FAILURE(String) var description: String {} } } /// Convenience method that creates a URL from the given path (string) and then calls add(NSURL:) to add the path to the bookmarks managed by this object. /// /// aPath: A string representing the path of the file or directory for which a bookmark must be added. The file/directory must have the proper access rights at the point of time this method is called. Note: Calling this method will NOT grant the application the sandbox-access rights! /// /// returns: SUCCESS if successful, NO_FAILURE if the path is nil, FAILURE(error reason) if something went wrong. func add(aPath: String?) -> Result {} /// Adds the given URL to the bookmarks managed by this object. /// /// aUrl: A NSURL representing the path of the file or directory for which a bookmark must be added. The file/directory must have the proper access rights at the point of time this method is called. Note: Calling this method will NOT grant the application the sandbox-access rights! /// /// returns: SUCCESS if successful, NO_FAILURE if the path is nil, FAILURE(error reason) if something went wrong. func add(aUrl: NSURL?) -> Result {} /// Use this function to clean up the sandbox rights periodically. Releases kernel resources for bookmarks that no longer have an associated file or directory. /// A good place to call this method is when the undomanager stack is cleared. func releaseSandboxRightsForStaleBookmarks() {} /// Removes the file permissions from the bookmarks. The folder permissions remain as is. func removeFiles() {} /// Removes the given path from the bookmarks. func remove(aPath: String) {} /// Removes the given path from the bookmarks. func remove(aUrl: NSURL) {} /// Write the security scoped bookmarks data to disk. func save() -> Result {} /// Reads the security scoped bookmarks from disk and requests sandbox acces rights to the resources. func restore() -> Result {} /// Returns all URLs of the bookmarks that are currently opened var openURLs: Array<NSURL> {} }