1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
|
-
+
+
-
-
+
+
-
+
-
+
-
+
-
+
-
+
-
+
-
-
+
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
-
+
+
+
+
+
+
-
+
-
+
-
-
+
+
+
+
+
+
+
+
+
-
+
-
+
-
-
+
+
+
+
-
+
-
+
-
-
+
+
+
+
-
+
-
+
-
+
+
+
+
-
+
-
+
-
-
+
+
+
+
+
+
-
+
-
+
-
+
-
+
+
+
+
-
+
-
+
-
+
-
-
+
+
+
+
+
+
+
-
+
-
+
-
+
-
+
+
+
+
-
+
-
+
-
+
+
+
+
-
+
-
+
+
+
+
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
/*
* Copyright (c) 2008-2022 Jonathan Schleifer <js@nil.im>
* Copyright (c) 2008-2023 Jonathan Schleifer <js@nil.im>
*
* All rights reserved.
*
* This file is part of ObjFW. It may be distributed under the terms of the
* Q Public License 1.0, which can be found in the file LICENSE.QPL included in
* the packaging of this file.
*
* Alternatively, it may be distributed under the terms of the GNU General
* Public License, either version 2 or 3, which can be found in the file
* LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
* file.
*/
#import "OFFileManager.h"
#import "OFObject.h"
#import "OFString.h"
OF_ASSUME_NONNULL_BEGIN
@class OFArray OF_GENERIC(ObjectType);
@class OFData;
@class OFDate;
@class OFStream;
@class OFURI;
@class OFIRI;
@class OFStream;
/**
* @class OFURIHandler OFURIHandler.h ObjFW/OFURIHandler.h
* @class OFIRIHandler OFIRIHandler.h ObjFW/OFIRIHandler.h
*
* @brief A handler for a URI scheme.
* @brief A handler for an IRI scheme.
*/
@interface OFURIHandler: OFObject
@interface OFIRIHandler: OFObject
{
OFString *_scheme;
OF_RESERVE_IVARS(OFURIHandler, 4)
OF_RESERVE_IVARS(OFIRIHandler, 4)
}
/**
* @brief The scheme this OFURIHandler handles.
* @brief The scheme this OFIRIHandler handles.
*/
@property (readonly, nonatomic) OFString *scheme;
/**
* @brief Registers the specified class as the handler for the specified scheme.
*
* If the same class is specified for two schemes, one instance of it is
* created per scheme.
*
* @param class_ The class to register as the handler for the specified scheme
* @param scheme The scheme for which to register the handler
* @return Whether the class was successfully registered. If a handler for the
* same scheme is already registered, registration fails.
*/
+ (bool)registerClass: (Class)class_ forScheme: (OFString *)scheme;
/**
* @brief Returns the handler for the specified URI.
* @brief Returns the handler for the specified IRI.
*
* @return The handler for the specified URI.
* @throw OFUnsupportedProtocolException The specified URI is not supported
* @return The handler for the specified IRI.
* @throw OFUnsupportedProtocolException The specified IRI is not supported
*/
+ (OFURIHandler *)handlerForURI: (OFURI *)URI;
+ (OFIRIHandler *)handlerForIRI: (OFIRI *)IRI;
/**
* @brief Opens the item at the specified URI.
* @brief Opens the item at the specified IRI.
*
* @param URI The URI of the item which should be opened
* @param IRI The IRI of the item which should be opened
* @param mode The mode in which the file should be opened.@n
* Possible modes are:
* @n
* Mode | Description
* ---------------|-------------------------------------
* `r` | Read-only
* `r+` | Read-write
* `w` | Write-only, create or truncate
* `wx` | Write-only, create or fail, exclusive
* `w+` | Read-write, create or truncate
* `w+x` | Read-write, create or fail, exclusive
* `a` | Write-only, create or append
* `a+` | Read-write, create or append
* @n
* The handler is allowed to not implement all modes and is also
* allowed to implement additional, scheme-specific modes.
* @return The opened stream if it was successfully opened
* @throw OFOpenItemFailedException Opening the item failed
* @throw OFUnsupportedProtocolException The specified URI is not supported
* @throw OFUnsupportedProtocolException The specified IRI is not supported
*/
+ (OFStream *)openItemAtURI: (OFURI *)URI mode: (OFString *)mode;
+ (OFStream *)openItemAtIRI: (OFIRI *)IRI mode: (OFString *)mode;
- (instancetype)init OF_UNAVAILABLE;
/**
* @brief Initializes the handler for the specified scheme.
*
* @param scheme The scheme to initialize for
* @return An initialized URI handler
* @return An initialized IRI handler
*/
- (instancetype)initWithScheme: (OFString *)scheme OF_DESIGNATED_INITIALIZER;
/**
* @brief Opens the item at the specified URI.
* @brief Opens the item at the specified IRI.
*
* @param URI The URI of the item which should be opened
* @param IRI The IRI of the item which should be opened
* @param mode The mode in which the file should be opened.@n
* Possible modes are:
* @n
* Mode | Description
* ---------------|-------------------------------------
* `r` | Read-only
* `r+` | Read-write
* `w` | Write-only, create or truncate
* `wx` | Write-only, create or fail, exclusive
* `w+` | Read-write, create or truncate
* `w+x` | Read-write, create or fail, exclusive
* `a` | Write-only, create or append
* `a+` | Read-write, create or append
* @n
* The handler is allowed to not implement all modes and is also
* allowed to implement additional, scheme-specific modes.
* @return The opened stream if it was successfully opened
* @throw OFOpenItemFailedException Opening the item failed
* @throw OFUnsupportedProtocolException The specified URI is not supported by
* @throw OFUnsupportedProtocolException The specified IRI is not supported by
* the handler
*/
- (OFStream *)openItemAtURI: (OFURI *)URI mode: (OFString *)mode;
- (OFStream *)openItemAtIRI: (OFIRI *)IRI mode: (OFString *)mode;
/**
* @brief Returns the attributes for the item at the specified URI.
* @brief Returns the attributes for the item at the specified IRI.
*
* @param URI The URI to return the attributes for
* @return A dictionary of attributes for the specified URI, with the keys of
* @param IRI The IRI to return the attributes for
* @return A dictionary of attributes for the specified IRI, with the keys of
* type @ref OFFileAttributeKey
* @throw OFGetItemAttributesFailedException Failed to get the attributes of
* the item
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (OFFileAttributes)attributesOfItemAtURI: (OFURI *)URI;
- (OFFileAttributes)attributesOfItemAtIRI: (OFIRI *)IRI;
/**
* @brief Sets the attributes for the item at the specified URI.
* @brief Sets the attributes for the item at the specified IRI.
*
* All attributes not part of the dictionary are left unchanged.
*
* @param attributes The attributes to set for the specified URI
* @param URI The URI of the item to set the attributes for
* @param attributes The attributes to set for the specified IRI
* @param IRI The IRI of the item to set the attributes for
* @@throw OFSetItemAttributesFailedException Failed to set the attributes of
* the item
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
* @throw OFNotImplementedException Setting one or more of the specified
* attributes is not implemented for the
* specified item
*/
- (void)setAttributes: (OFFileAttributes)attributes ofItemAtURI: (OFURI *)URI;
- (void)setAttributes: (OFFileAttributes)attributes ofItemAtIRI: (OFIRI *)IRI;
/**
* @brief Checks whether a file exists at the specified URI.
* @brief Checks whether a file exists at the specified IRI.
*
* @param URI The URI to check
* @return A boolean whether there is a file at the specified URI
* @param IRI The IRI to check
* @return A boolean whether there is a file at the specified IRI
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (bool)fileExistsAtURI: (OFURI *)URI;
- (bool)fileExistsAtIRI: (OFIRI *)IRI;
/**
* @brief Checks whether a directory exists at the specified URI.
* @brief Checks whether a directory exists at the specified IRI.
*
* @param URI The URI to check
* @return A boolean whether there is a directory at the specified URI
* @param IRI The IRI to check
* @return A boolean whether there is a directory at the specified IRI
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (bool)directoryExistsAtURI: (OFURI *)URI;
- (bool)directoryExistsAtIRI: (OFIRI *)IRI;
/**
* @brief Creates a directory at the specified URI.
* @brief Creates a directory at the specified IRI.
*
* @param URI The URI of the directory to create
* @param IRI The IRI of the directory to create
* @throw OFCreateDirectoryFailedException Creating the directory failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (void)createDirectoryAtURI: (OFURI *)URI;
- (void)createDirectoryAtIRI: (OFIRI *)IRI;
/**
* @brief Returns an array with the URIs of the items in the specified
* @brief Returns an array with the IRIs of the items in the specified
* directory.
*
* @note `.` and `..` are not part of the returned array.
*
* @param URI The URI to the directory whose items should be returned
* @return An array with the URIs of the items in the specified directory
* @param IRI The IRI to the directory whose items should be returned
* @return An array with the IRIs of the items in the specified directory
* @throw OFOpenItemFailedException Opening the directory failed
* @throw OFReadFailedException Reading from the directory failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (OFArray OF_GENERIC(OFURI *) *)contentsOfDirectoryAtURI: (OFURI *)URI;
- (OFArray OF_GENERIC(OFIRI *) *)contentsOfDirectoryAtIRI: (OFIRI *)IRI;
/**
* @brief Removes the item at the specified URI.
* @brief Removes the item at the specified IRI.
*
* If the item at the specified URI is a directory, it is removed recursively.
* If the item at the specified IRI is a directory, it is removed recursively.
*
* @param URI The URI to the item which should be removed
* @param IRI The IRI to the item which should be removed
* @throw OFRemoveItemFailedException Removing the item failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (void)removeItemAtURI: (OFURI *)URI;
- (void)removeItemAtIRI: (OFIRI *)IRI;
/**
* @brief Creates a hard link for the specified item.
*
* The destination URI must have a full path, which means it must include the
* The destination IRI must have a full path, which means it must include the
* name of the item.
*
* This method is not available for all URIs.
* This method is not available for all IRIs.
*
* @param source The URI to the item for which a link should be created
* @param destination The URI to the item which should link to the source
* @param source The IRI to the item for which a link should be created
* @param destination The IRI to the item which should link to the source
* @throw OFLinkItemFailedException Linking the item failed
* @throw OFUnsupportedProtocolException The handler cannot handle the scheme
* of one of the IRIs
* @throw OFNotImplementedException Hardlinks are not implemented for the
* specified IRI
*/
- (void)linkItemAtURI: (OFURI *)source toURI: (OFURI *)destination;
- (void)linkItemAtIRI: (OFIRI *)source toIRI: (OFIRI *)destination;
/**
* @brief Creates a symbolic link for an item.
*
* The destination URI must have a full path, which means it must include the
* The destination IRI must have a full path, which means it must include the
* name of the item.
*
* This method is not available for all URIs.
* This method is not available for all IRIs.
*
* @note On Windows, this requires at least Windows Vista and administrator
* privileges!
*
* @param URI The URI to the item which should symbolically link to the target
* @param IRI The IRI to the item which should symbolically link to the target
* @param target The target of the symbolic link
* @throw OFCreateSymbolicLinkFailed Creating a symbolic link failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (void)createSymbolicLinkAtURI: (OFURI *)URI
- (void)createSymbolicLinkAtIRI: (OFIRI *)IRI
withDestinationPath: (OFString *)target;
/**
* @brief Tries to efficiently copy an item. If a copy would only be possible
* by reading the entire item and then writing it, it returns false.
*
* The destination URI must have a full path, which means it must include the
* The destination IRI must have a full path, which means it must include the
* name of the item.
*
* If an item already exists, the copy operation fails. This is also the case
* if a directory is copied and an item already exists in the destination
* directory.
*
* @param source The file, directory or symbolic link to copy
* @param destination The destination URI
* @param destination The destination IRI
* @return True if an efficient copy was performed, false if an efficient copy
* was not possible. Note that errors while performing a copy are
* reported via exceptions and not by returning false!
* @throw OFCopyItemFailedException Copying failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (bool)copyItemAtURI: (OFURI *)source toURI: (OFURI *)destination;
- (bool)copyItemAtIRI: (OFIRI *)source toIRI: (OFIRI *)destination;
/**
* @brief Tries to efficiently move an item. If a move would only be possible
* by copying the source and deleting it, it returns false.
*
* The destination URI must have a full path, which means it must include the
* The destination IRI must have a full path, which means it must include the
* name of the item.
*
* If the destination is on a different logical device or uses a different
* scheme, an efficient move is not possible and false is returned.
*
* @param source The item to rename
* @param destination The new name for the item
* @return True if an efficient move was performed, false if an efficient move
* was not possible. Note that errors while performing a move are
* reported via exceptions and not by returning false!
* @throw OFMoveItemFailedException Moving failed
* @throw OFUnsupportedProtocolException The handler cannot handle the IRI's
* scheme
*/
- (bool)moveItemAtIRI: (OFIRI *)source toIRI: (OFIRI *)destination;
- (bool)moveItemAtURI: (OFURI *)source toURI: (OFURI *)destination;
|