Skip to content

Commit 3008bde

Browse files
desertkundesertkun
committed
Persistent file access for sandbox mode
1 parent 7a2c1e7 commit 3008bde

10 files changed

Lines changed: 774 additions & 8 deletions

‎fusepb/AppSandboxFileAccess.h‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
//
2+
// AppSandboxFileAccess.h
3+
// AppSandboxFileAccess
4+
//
5+
// Created by Leigh McCulloch on 23/11/2013.
6+
//
7+
// Copyright (c) 2013, Leigh McCulloch
8+
// All rights reserved.
9+
//
10+
// BSD-2-Clause License: http://opensource.org/licenses/BSD-2-Clause
11+
//
12+
// Redistribution and use in source and binary forms, with or without
13+
// modification, are permitted provided that the following conditions are
14+
// met:
15+
//
16+
// 1. Redistributions of source code must retain the above copyright
17+
// notice, this list of conditions and the following disclaimer.
18+
//
19+
// 2. Redistributions in binary form must reproduce the above copyright
20+
// notice, this list of conditions and the following disclaimer in the
21+
// documentation and/or other materials provided with the distribution.
22+
//
23+
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
24+
// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25+
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
26+
// PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27+
// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28+
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29+
// TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30+
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31+
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32+
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33+
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34+
//
35+
36+
#import <Foundation/Foundation.h>
37+
#import <AppKit/AppKit.h>
38+
39+
#pragma mark -
40+
#pragma mark AppSandboxFileAccessProtocol
41+
42+
@protocol AppSandboxFileAccessProtocol<NSObject>
43+
44+
@required
45+
- (NSData *)bookmarkDataForURL:(NSURL *)url;
46+
- (void)setBookmarkData:(NSData *)data forURL:(NSURL *)url;
47+
- (void)clearBookmarkDataForURL:(NSURL *)url;
48+
49+
@end
50+
51+
#pragma mark -
52+
#pragma mark AppSandboxFileAccess
53+
54+
typedef void (^AppSandboxFileAccessBlock)(void);
55+
typedef void (^AppSandboxFileSecurityScopeBlock)(NSURL *securityScopedFileURL, NSData *bookmarkData);
56+
57+
@interface AppSandboxFileAccess : NSObject
58+
59+
/*! @brief The title of the NSOpenPanel displayed when asking permission to access a file.
60+
Default: "Allow Access"
61+
*/
62+
@property (readwrite, copy, nonatomic) NSString *title;
63+
/*! @brief The message contained on the the NSOpenPanel displayed when asking permission to access a file.
64+
Default: "[Application Name] needs to access this path to continue. Click Allow to continue."
65+
*/
66+
@property (readwrite, copy, nonatomic) NSString *message;
67+
/*! @brief The prompt button on the the NSOpenPanel displayed when asking permission to access a file.
68+
Default: "Allow"
69+
*/
70+
@property (readwrite, copy, nonatomic) NSString *prompt;
71+
72+
/*! @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).
73+
Default: nil (Default uses the AppSandboxFileAccessPersist class.)
74+
*/
75+
@property (nonatomic) id <AppSandboxFileAccessProtocol> bookmarkPersistanceDelegate;
76+
77+
/*! @brief Create the object with the default values. */
78+
+ (AppSandboxFileAccess *)fileAccess;
79+
80+
/*! @brief Initialise the object with the default values. */
81+
- (instancetype)init;
82+
83+
- (void)dealloc;
84+
85+
/*! @brief Access a file path to read or write, automatically gaining permission from the user with NSOpenPanel if required
86+
and using persisted permissions if possible.
87+
88+
@see accessFile:persistPermission:withBlock:
89+
@see securityScopedURLForFilePath:persistPermission:bookmark:
90+
91+
@param path A file path, either a file or folder, that the caller needs access to.
92+
@param persist If YES will save the permission for future calls.
93+
@param block The block that will be given access to the file or folder.
94+
@return YES if permission was granted or already available, NO otherwise.
95+
*/
96+
- (BOOL)accessFilePath:(NSString *)path persistPermission:(BOOL)persist withBlock:(AppSandboxFileAccessBlock)block;
97+
98+
/*!
99+
@warning Deprecated.
100+
101+
@see accessFilePath:persistPermission:withBlock:
102+
103+
@param path A file path, either a file or folder, that the caller needs access to.
104+
@param block The block that will be given access to the file or folder.
105+
@param persist If YES will save the permission for future calls.
106+
@return YES if permission was granted or already available, NO otherwise.
107+
*/
108+
- (BOOL)accessFilePath:(NSString *)path withBlock:(AppSandboxFileAccessBlock)block persistPermission:(BOOL)persist __attribute__((deprecated("Use 'accessFilePath:persistPermission:withBlock:' instead.")));
109+
110+
/*! @brief Access a file URL to read or write, automatically gaining permission from the user with NSOpenPanel if required
111+
and using persisted permissions if possible.
112+
113+
@see requestAccessPermissionsForFileURL:persistPermission:withBlock:
114+
115+
@discussion Internally calls `requestAccessPermissionsForFileURL:persistPermission:withBlock:` and accesses the returned scoped URL if successful.
116+
117+
@discussion See `requestAccessPermissionsForFileURL:persistPermission:withBlock:` for detailed behaviour.
118+
119+
@param fileURL A file URL, either a file or folder, that the caller needs access to.
120+
@param persist If YES will save the permission for future calls.
121+
@param block The block that will be given access to the file or folder.
122+
@return YES if permission was granted or already available, NO otherwise.
123+
*/
124+
- (BOOL)accessFileURL:(NSURL *)fileURL persistPermission:(BOOL)persist withBlock:(AppSandboxFileAccessBlock)block;
125+
126+
/*!
127+
@warning Deprecated.
128+
129+
@see accessFileURL:persistPermission:withBlock:
130+
131+
@param fileURL A file URL, either a file or folder, that the caller needs access to.
132+
@param persist If YES will save the permission for future calls.
133+
@param block The block that will be given access to the file or folder.
134+
@return YES if permission was granted or already available, NO otherwise.
135+
*/
136+
- (BOOL)accessFileURL:(NSURL *)fileURL withBlock:(AppSandboxFileAccessBlock)block persistPermission:(BOOL)persist __attribute__((deprecated("Use 'accessFileURL:persistPermission:withBlock:' instead.")));
137+
138+
/*! @brief Request access permission for a file path to read or write, automatically with NSOpenPanel if required
139+
and using persisted permissions if possible.
140+
141+
@see securityScopedURLForFilePath:persistPermission:bookmark:
142+
143+
@param path A file path, either a file or folder, that the caller needs access to.
144+
@param persist If YES will save the permission for future calls.
145+
@return YES if permission was granted or already available, NO otherwise.
146+
*/
147+
- (BOOL)requestAccessPermissionsForFilePath:(NSString *)filePath persistPermission:(BOOL)persist withBlock:(AppSandboxFileSecurityScopeBlock)block;
148+
149+
/*! @brief Request access permission for a file path to read or write, automatically with NSOpenPanel if required
150+
and using persisted permissions if possible.
151+
152+
@discussion Use this function to access a file URL to either read or write in an application restricted by the App Sandbox.
153+
This function will ask the user for permission if necessary using a well formed NSOpenPanel. The user will
154+
have the option of approving access to the URL you specify, or a parent path for that URL. If persist is YES
155+
the permission will be stored as a bookmark in NSUserDefaults and further calls to this function will
156+
load the saved permission and not ask for permission again.
157+
158+
@discussion If the file URL does not exist, it's parent directory will be asked for permission instead, since permission
159+
to the directory will be required to write the file. If the parent directory doesn't exist, it will ask for
160+
permission of whatever part of the parent path exists.
161+
162+
@discussion Note: If the caller has permission to access a file because it was dropped onto the application or introduced
163+
to the application in some other way, this function will not be aware of that permission and still prompt
164+
the user. To prevent this, use the persistPermission function to persist a permission you've been given
165+
whenever a user introduces a file to the application. E.g. when dropping a file onto the application window
166+
or dock or when using an NSOpenPanel.
167+
168+
@param fileURL A file URL, either a file or folder, that the caller needs access to.
169+
@param persist If YES will save the permission for future calls.
170+
@param block The block that will be given access to the file or folder.
171+
@return YES if permission was granted or already available, NO otherwise.
172+
*/
173+
- (BOOL)requestAccessPermissionsForFileURL:(NSURL *)fileURL persistPermission:(BOOL)persist withBlock:(AppSandboxFileSecurityScopeBlock)block;
174+
175+
/*! @brief Persist a security bookmark for the given path. The calling application must already have permission.
176+
177+
@see persistPermissionURL:
178+
179+
@param path The path with permission that will be persisted.
180+
@return Bookmark data if permission was granted or already available, nil otherwise.
181+
*/
182+
- (NSData *)persistPermissionPath:(NSString *)path;
183+
184+
/*! @brief Persist a security bookmark for the given URL. The calling application must already have permission.
185+
186+
@discussion Use this function to persist permission of a URL that has already been granted when a user introduced
187+
a file to the calling application. E.g. by dropping the file onto the application window, or dock icon,
188+
or when using an NSOpenPanel.
189+
190+
Note: If the calling application does not have access to this file, this call will do nothing.
191+
192+
@param url The URL with permission that will be persisted.
193+
@return Bookmark data if permission was granted or already available, nil otherwise.
194+
*/
195+
- (NSData *)persistPermissionURL:(NSURL *)url;
196+
197+
@end

0 commit comments

Comments
 (0)