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
|
/*
* Copyright 2017 Google
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#import <Foundation/Foundation.h>
#import "FIRStorage.h"
#import "FIRStorageConstants.h"
#import "FIRStorageDownloadTask.h"
#import "FIRStorageMetadata.h"
#import "FIRStorageTask.h"
#import "FIRStorageUploadTask.h"
NS_ASSUME_NONNULL_BEGIN
/**
* FIRStorageReference represents a reference to a Google Cloud Storage object. Developers can
* upload and download objects, as well as get/set object metadata, and delete an object at the
* path.
* @see https://cloud.google.com/storage/
*/
NS_SWIFT_NAME(StorageReference)
@interface FIRStorageReference : NSObject
/**
* The FIRStorage service object which created this reference.
*/
@property(nonatomic, readonly) FIRStorage *storage;
/**
* The name of the Google Cloud Storage bucket associated with this reference,
* in gs://bucket/path/to/object.txt, the bucket would be: 'bucket'
*/
@property(nonatomic, readonly) NSString *bucket;
/**
* The full path to this object, not including the Google Cloud Storage bucket.
* In gs://bucket/path/to/object.txt, the full path would be: 'path/to/object.txt'
*/
@property(nonatomic, readonly) NSString *fullPath;
/**
* The short name of the object associated with this reference,
* in gs://bucket/path/to/object.txt, the name of the object would be: 'object.txt'
*/
@property(nonatomic, readonly) NSString *name;
#pragma mark - Path Operations
/**
* Creates a new FIRStorageReference pointing to the root object.
* @return A new FIRStorageReference pointing to the root object.
*/
- (FIRStorageReference *)root;
/**
* Creates a new FIRStorageReference pointing to the parent of the current reference
* or nil if this instance references the root location.
* For example:
* path = foo/bar/baz parent = foo/bar
* path = foo parent = (root)
* path = (root) parent = nil
* @return A new FIRStorageReference pointing to the parent of the current reference.
*/
- (nullable FIRStorageReference *)parent;
/**
* Creates a new FIRStorageReference pointing to a child object of the current reference.
* path = foo child = bar newPath = foo/bar
* path = foo/bar child = baz newPath = foo/bar/baz
* All leading and trailing slashes will be removed, and consecutive slashes will be
* compressed to single slashes. For example:
* child = /foo/bar newPath = foo/bar
* child = foo/bar/ newPath = foo/bar
* child = foo///bar newPath = foo/bar
* @param path Path to append to the current path.
* @return A new FIRStorageReference pointing to a child location of the current reference.
*/
- (FIRStorageReference *)child:(NSString *)path;
#pragma mark - Uploads
/**
* Asynchronously uploads data to the currently specified FIRStorageReference,
* without additional metadata.
* This is not recommended for large files, and one should instead upload a file from disk.
* @param uploadData The NSData to upload.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
- (FIRStorageUploadTask *)putData:(NSData *)uploadData NS_SWIFT_NAME(putData(_:));
/**
* Asynchronously uploads data to the currently specified FIRStorageReference.
* This is not recommended for large files, and one should instead upload a file from disk.
* @param uploadData The NSData to upload.
* @param metadata FIRStorageMetadata containing additional information (MIME type, etc.)
* about the object being uploaded.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
// clang-format off
- (FIRStorageUploadTask *)putData:(NSData *)uploadData
metadata:(nullable FIRStorageMetadata *)metadata
NS_SWIFT_NAME(putData(_:metadata:));
// clang-format on
/**
* Asynchronously uploads data to the currently specified FIRStorageReference.
* This is not recommended for large files, and one should instead upload a file from disk.
* @param uploadData The NSData to upload.
* @param metadata FIRStorageMetadata containing additional information (MIME type, etc.)
* about the object being uploaded.
* @param completion A completion block that either returns the object metadata on success,
* or an error on failure.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
// clang-format off
- (FIRStorageUploadTask *)putData:(NSData *)uploadData
metadata:(nullable FIRStorageMetadata *)metadata
completion:(nullable void (^)(FIRStorageMetadata *_Nullable metadata,
NSError *_Nullable error))completion
NS_SWIFT_NAME(putData(_:metadata:completion:));
// clang-format on
/**
* Asynchronously uploads a file to the currently specified FIRStorageReference,
* without additional metadata.
* @param fileURL A URL representing the system file path of the object to be uploaded.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
- (FIRStorageUploadTask *)putFile:(NSURL *)fileURL NS_SWIFT_NAME(putFile(from:));
/**
* Asynchronously uploads a file to the currently specified FIRStorageReference.
* @param fileURL A URL representing the system file path of the object to be uploaded.
* @param metadata FIRStorageMetadata containing additional information (MIME type, etc.)
* about the object being uploaded.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
// clang-format off
- (FIRStorageUploadTask *)putFile:(NSURL *)fileURL
metadata:(nullable FIRStorageMetadata *)metadata
NS_SWIFT_NAME(putFile(from:metadata:));
// clang-format on
/**
* Asynchronously uploads a file to the currently specified FIRStorageReference.
* @param fileURL A URL representing the system file path of the object to be uploaded.
* @param metadata FIRStorageMetadata containing additional information (MIME type, etc.)
* about the object being uploaded.
* @param completion A completion block that either returns the object metadata on success,
* or an error on failure.
* @return An instance of FIRStorageUploadTask, which can be used to monitor or manage the upload.
*/
// clang-format off
- (FIRStorageUploadTask *)putFile:(NSURL *)fileURL
metadata:(nullable FIRStorageMetadata *)metadata
completion:(nullable void (^)(FIRStorageMetadata *_Nullable metadata,
NSError *_Nullable error))completion
NS_SWIFT_NAME(putFile(from:metadata:completion:));
// clang-format on
#pragma mark - Downloads
/**
* Asynchronously downloads the object at the FIRStorageReference to an NSData object in memory.
* An NSData of the provided max size will be allocated, so ensure that the device has enough free
* memory to complete the download. For downloading large files, writeToFile may be a better option.
* @param size The maximum size in bytes to download. If the download exceeds this size
* the task will be cancelled and an error will be returned.
* @param completion A completion block that either returns the object data on success,
* or an error on failure.
* @return An FIRStorageDownloadTask that can be used to monitor or manage the download.
*/
// clang-format off
- (FIRStorageDownloadTask *)dataWithMaxSize:(int64_t)size
completion:(void (^)(NSData *_Nullable data,
NSError *_Nullable error))completion
NS_SWIFT_NAME(getData(maxSize:completion:));
// clang-format on
/**
* Asynchronously retrieves a long lived download URL with a revokable token.
* This can be used to share the file with others, but can be revoked by a developer
* in the Firebase Console if desired.
* @param completion A completion block that either returns the URL on success,
* or an error on failure.
*/
- (void)downloadURLWithCompletion:(void (^)(NSURL *_Nullable URL,
NSError *_Nullable error))completion;
/**
* Asynchronously downloads the object at the current path to a specified system filepath.
* @param fileURL A file system URL representing the path the object should be downloaded to.
* @return An FIRStorageDownloadTask that can be used to monitor or manage the download.
*/
- (FIRStorageDownloadTask *)writeToFile:(NSURL *)fileURL;
/**
* Asynchronously downloads the object at the current path to a specified system filepath.
* @param fileURL A file system URL representing the path the object should be downloaded to.
* @param completion A completion block that fires when the file download completes.
* Returns an NSURL pointing to the file path of the downloaded file on success,
* or an error on failure.
* @return An FIRStorageDownloadTask that can be used to monitor or manage the download.
*/
- (FIRStorageDownloadTask *)writeToFile:(NSURL *)fileURL
completion:(nullable void (^)(NSURL *_Nullable URL,
NSError *_Nullable error))completion;
#pragma mark - Metadata Operations
/**
* Retrieves metadata associated with an object at the current path.
* @param completion A completion block which returns the object metadata on success,
* or an error on failure.
*/
- (void)metadataWithCompletion:
(void (^)(FIRStorageMetadata *_Nullable metadata, NSError *_Nullable error))completion
NS_SWIFT_NAME(getMetadata(completion:));
/**
* Updates the metadata associated with an object at the current path.
* @param metadata An FIRStorageMetadata object with the metadata to update.
* @param completion A completion block which returns the FIRStorageMetadata on success,
* or an error on failure.
*/
// clang-format off
- (void)updateMetadata:(FIRStorageMetadata *)metadata
completion:(nullable void (^)(FIRStorageMetadata *_Nullable metadata,
NSError *_Nullable error))completion
NS_SWIFT_NAME(updateMetadata(_:completion:));
// clang-format on
#pragma mark - Delete
/**
* Deletes the object at the current path.
* @param completion A completion block which returns nil on success, or an error on failure.
*/
- (void)deleteWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
@end
NS_ASSUME_NONNULL_END
|
