|
|
@@ -0,0 +1,196 @@
|
|
|
+//
|
|
|
+// AppSandboxFileAccess.h
|
|
|
+// AppSandboxFileAccess
|
|
|
+//
|
|
|
+// Created by Leigh McCulloch on 23/11/2013.
|
|
|
+//
|
|
|
+// Copyright (c) 2013, Leigh McCulloch
|
|
|
+// All rights reserved.
|
|
|
+//
|
|
|
+// BSD-2-Clause License: http://opensource.org/licenses/BSD-2-Clause
|
|
|
+//
|
|
|
+// Redistribution and use in source and binary forms, with or without
|
|
|
+// modification, are permitted provided that the following conditions are
|
|
|
+// met:
|
|
|
+//
|
|
|
+// 1. Redistributions of source code must retain the above copyright
|
|
|
+// notice, this list of conditions and the following disclaimer.
|
|
|
+//
|
|
|
+// 2. Redistributions in binary form must reproduce the above copyright
|
|
|
+// notice, this list of conditions and the following disclaimer in the
|
|
|
+// documentation and/or other materials provided with the distribution.
|
|
|
+//
|
|
|
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
|
|
+// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
|
+// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|
|
+// PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
|
+// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
|
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
|
|
|
+// TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
|
+// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
|
+// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
|
+// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
|
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
+//
|
|
|
+
|
|
|
+#import <Foundation/Foundation.h>
|
|
|
+#import <AppKit/AppKit.h>
|
|
|
+//@import AppKit;
|
|
|
+
|
|
|
+#pragma mark -
|
|
|
+#pragma mark AppSandboxFileAccessProtocol
|
|
|
+
|
|
|
+@protocol AppSandboxFileAccessProtocol<NSObject>
|
|
|
+
|
|
|
+@required
|
|
|
+- (NSData *)bookmarkDataForURL:(NSURL *)url;
|
|
|
+- (void)setBookmarkData:(NSData *)data forURL:(NSURL *)url;
|
|
|
+- (void)clearBookmarkDataForURL:(NSURL *)url;
|
|
|
+
|
|
|
+@end
|
|
|
+
|
|
|
+#pragma mark -
|
|
|
+#pragma mark AppSandboxFileAccess
|
|
|
+
|
|
|
+typedef void (^AppSandboxFileAccessBlock)(void);
|
|
|
+typedef void (^AppSandboxFileSecurityScopeBlock)(NSURL *securityScopedFileURL, NSData *bookmarkData);
|
|
|
+
|
|
|
+@interface AppSandboxFileAccess : NSObject
|
|
|
+
|
|
|
+/*! @brief The title of the NSOpenPanel displayed when asking permission to access a file.
|
|
|
+ Default: "Allow Access"
|
|
|
+ */
|
|
|
+@property (readwrite, copy, nonatomic) NSString *title;
|
|
|
+/*! @brief The message contained on the the NSOpenPanel displayed when asking permission to access a file.
|
|
|
+ Default: "[Application Name] needs to access this path to continue. Click Allow to continue."
|
|
|
+ */
|
|
|
+@property (readwrite, copy, nonatomic) NSString *message;
|
|
|
+/*! @brief The prompt button on the the NSOpenPanel displayed when asking permission to access a file.
|
|
|
+ Default: "Allow"
|
|
|
+ */
|
|
|
+@property (readwrite, copy, nonatomic) NSString *prompt;
|
|
|
+
|
|
|
+/*! @brief This is an optional delegate object that can be provided to customize the persistance of bookmark data (e.g. in a Core Data database).
|
|
|
+ Default: nil (Default uses the AppSandboxFileAccessPersist class.)
|
|
|
+ */
|
|
|
+@property (nonatomic, weak) id <AppSandboxFileAccessProtocol> bookmarkPersistanceDelegate;
|
|
|
+
|
|
|
+/*! @brief Create the object with the default values. */
|
|
|
++ (AppSandboxFileAccess *)fileAccess;
|
|
|
+
|
|
|
+/*! @brief Initialise the object with the default values. */
|
|
|
+- (instancetype)init;
|
|
|
+
|
|
|
+/*! @brief Access a file path to read or write, automatically gaining permission from the user with NSOpenPanel if required
|
|
|
+ and using persisted permissions if possible.
|
|
|
+
|
|
|
+ @see accessFile:persistPermission:withBlock:
|
|
|
+ @see securityScopedURLForFilePath:persistPermission:bookmark:
|
|
|
+
|
|
|
+ @param path A file path, either a file or folder, that the caller needs access to.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @param block The block that will be given access to the file or folder.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)accessFilePath:(NSString *)path persistPermission:(BOOL)persist withBlock:(AppSandboxFileAccessBlock)block;
|
|
|
+
|
|
|
+/*!
|
|
|
+ @warning Deprecated.
|
|
|
+
|
|
|
+ @see accessFilePath:persistPermission:withBlock:
|
|
|
+
|
|
|
+ @param path A file path, either a file or folder, that the caller needs access to.
|
|
|
+ @param block The block that will be given access to the file or folder.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)accessFilePath:(NSString *)path withBlock:(AppSandboxFileAccessBlock)block persistPermission:(BOOL)persist __attribute__((deprecated("Use 'accessFilePath:persistPermission:withBlock:' instead.")));
|
|
|
+
|
|
|
+/*! @brief Access a file URL to read or write, automatically gaining permission from the user with NSOpenPanel if required
|
|
|
+ and using persisted permissions if possible.
|
|
|
+
|
|
|
+ @see requestAccessPermissionsForFileURL:persistPermission:withBlock:
|
|
|
+
|
|
|
+ @discussion Internally calls `requestAccessPermissionsForFileURL:persistPermission:withBlock:` and accesses the returned scoped URL if successful.
|
|
|
+
|
|
|
+ @discussion See `requestAccessPermissionsForFileURL:persistPermission:withBlock:` for detailed behaviour.
|
|
|
+
|
|
|
+ @param fileURL A file URL, either a file or folder, that the caller needs access to.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @param block The block that will be given access to the file or folder.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)accessFileURL:(NSURL *)fileURL persistPermission:(BOOL)persist withBlock:(AppSandboxFileAccessBlock)block;
|
|
|
+
|
|
|
+/*!
|
|
|
+ @warning Deprecated.
|
|
|
+
|
|
|
+ @see accessFileURL:persistPermission:withBlock:
|
|
|
+
|
|
|
+ @param fileURL A file URL, either a file or folder, that the caller needs access to.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @param block The block that will be given access to the file or folder.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)accessFileURL:(NSURL *)fileURL withBlock:(AppSandboxFileAccessBlock)block persistPermission:(BOOL)persist __attribute__((deprecated("Use 'accessFileURL:persistPermission:withBlock:' instead.")));
|
|
|
+
|
|
|
+/*! @brief Request access permission for a file path to read or write, automatically with NSOpenPanel if required
|
|
|
+ and using persisted permissions if possible.
|
|
|
+
|
|
|
+ @see securityScopedURLForFilePath:persistPermission:bookmark:
|
|
|
+
|
|
|
+ @param path A file path, either a file or folder, that the caller needs access to.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)requestAccessPermissionsForFilePath:(NSString *)filePath persistPermission:(BOOL)persist withBlock:(AppSandboxFileSecurityScopeBlock)block;
|
|
|
+
|
|
|
+/*! @brief Request access permission for a file path to read or write, automatically with NSOpenPanel if required
|
|
|
+ and using persisted permissions if possible.
|
|
|
+
|
|
|
+ @discussion Use this function to access a file URL to either read or write in an application restricted by the App Sandbox.
|
|
|
+ This function will ask the user for permission if necessary using a well formed NSOpenPanel. The user will
|
|
|
+ have the option of approving access to the URL you specify, or a parent path for that URL. If persist is YES
|
|
|
+ the permission will be stored as a bookmark in NSUserDefaults and further calls to this function will
|
|
|
+ load the saved permission and not ask for permission again.
|
|
|
+
|
|
|
+ @discussion If the file URL does not exist, it's parent directory will be asked for permission instead, since permission
|
|
|
+ to the directory will be required to write the file. If the parent directory doesn't exist, it will ask for
|
|
|
+ permission of whatever part of the parent path exists.
|
|
|
+
|
|
|
+ @discussion Note: If the caller has permission to access a file because it was dropped onto the application or introduced
|
|
|
+ to the application in some other way, this function will not be aware of that permission and still prompt
|
|
|
+ the user. To prevent this, use the persistPermission function to persist a permission you've been given
|
|
|
+ whenever a user introduces a file to the application. E.g. when dropping a file onto the application window
|
|
|
+ or dock or when using an NSOpenPanel.
|
|
|
+
|
|
|
+ @param fileURL A file URL, either a file or folder, that the caller needs access to.
|
|
|
+ @param persist If YES will save the permission for future calls.
|
|
|
+ @param block The block that will be given access to the file or folder.
|
|
|
+ @return YES if permission was granted or already available, NO otherwise.
|
|
|
+ */
|
|
|
+- (BOOL)requestAccessPermissionsForFileURL:(NSURL *)fileURL persistPermission:(BOOL)persist withBlock:(AppSandboxFileSecurityScopeBlock)block;
|
|
|
+
|
|
|
+/*! @brief Persist a security bookmark for the given path. The calling application must already have permission.
|
|
|
+
|
|
|
+ @see persistPermissionURL:
|
|
|
+
|
|
|
+ @param path The path with permission that will be persisted.
|
|
|
+ @return Bookmark data if permission was granted or already available, nil otherwise.
|
|
|
+ */
|
|
|
+- (NSData *)persistPermissionPath:(NSString *)path;
|
|
|
+
|
|
|
+/*! @brief Persist a security bookmark for the given URL. The calling application must already have permission.
|
|
|
+
|
|
|
+ @discussion Use this function to persist permission of a URL that has already been granted when a user introduced
|
|
|
+ a file to the calling application. E.g. by dropping the file onto the application window, or dock icon,
|
|
|
+ or when using an NSOpenPanel.
|
|
|
+
|
|
|
+ Note: If the calling application does not have access to this file, this call will do nothing.
|
|
|
+
|
|
|
+ @param url The URL with permission that will be persisted.
|
|
|
+ @return Bookmark data if permission was granted or already available, nil otherwise.
|
|
|
+ */
|
|
|
+- (NSData *)persistPermissionURL:(NSURL *)url;
|
|
|
+
|
|
|
+@end
|
