-
Notifications
You must be signed in to change notification settings - Fork 153
/
storage.kt
369 lines (323 loc) · 13.2 KB
/
storage.kt
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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
package dev.gitlive.firebase.storage
import dev.gitlive.firebase.Firebase
import dev.gitlive.firebase.FirebaseApp
import dev.gitlive.firebase.FirebaseException
import kotlinx.coroutines.flow.Flow
import kotlin.time.Duration
import kotlin.time.Duration.Companion.milliseconds
/** Returns the [FirebaseStorage] instance of the default [FirebaseApp]. */
public expect val Firebase.storage: FirebaseStorage
/** Returns the [FirebaseStorage] instance of the default [FirebaseApp]. */
public expect fun Firebase.storage(url: String): FirebaseStorage
/** Returns the [FirebaseStorage] instance of a given [FirebaseApp]. */
public expect fun Firebase.storage(app: FirebaseApp): FirebaseStorage
/** Returns the [FirebaseStorage] instance of a given [FirebaseApp]. */
public expect fun Firebase.storage(app: FirebaseApp, url: String): FirebaseStorage
/**
* FirebaseStorage is a service that supports uploading and downloading large objects to Google
* Cloud Storage. Pass a custom instance of [FirebaseApp] to [Firebase.storage]
* which will initialize it with a storage location.
*
* Otherwise, if you call [Firebase.storage] without a [FirebaseApp], the
* [FirebaseStorage] instance will initialize with the default [FirebaseApp] obtainable from
* [Firebase.storage]. The storage location in this case will come the JSON
* configuration file downloaded from the web.
*/
public expect class FirebaseStorage {
/**
* Returns the maximum time to retry operations other than upload and download if a failure
* occurs.
*
* @return the maximum time. Defaults to 2 minutes (120,000 milliseconds).
*/
public val maxOperationRetryTime: Duration
/**
* Returns the maximum time to retry an upload if a failure occurs.
*
* @return the maximum time. Defaults to 10 minutes (600,000 milliseconds).
*/
public val maxUploadRetryTime: Duration
/**
* Sets the maximum time to retry operations other than upload and download if a failure occurs.
*
* @param maxOperationRetryTime the maximum time. Defaults to 2 minutes (120,000
* milliseconds).
*/
public fun setMaxOperationRetryTime(maxOperationRetryTime: Duration)
/**
* Sets the maximum time to retry an upload if a failure occurs.
*
* @param maxUploadRetryTime the maximum time in milliseconds. Defaults to 10 minutes (600,000
* milliseconds).
*/
public fun setMaxUploadRetryTime(maxUploadRetryTime: Duration)
/**
* Modifies this FirebaseStorage instance to communicate with the Storage emulator.
*
* Note: Call this method before using the instance to do any storage operations.
*
* @param host the emulator host (for example, 10.0.2.2)
* @param port the emulator port (for example, 9000)
*/
public fun useEmulator(host: String, port: Int)
/**
* Creates a new [StorageReference] initialized at the root Firebase Storage location.
*
* @return An instance of [StorageReference].
*/
public val reference: StorageReference
/**
* Creates a new [StorageReference] initialized with a child Firebase Storage location.
*
* @param location A relative path from the root to initialize the reference with, for instance
* "path/to/object"
* @return An instance of [StorageReference] at the given child path.
*/
public fun reference(location: String): StorageReference
/**
* Creates a [StorageReference] given a gs:// or https:// URL pointing to a Firebase Storage location.
*
* @param fullUrl A gs:// or http[s]:// URL used to initialize the reference. For example, you can pass
* in a download URL retrieved from getDownloadUrl or the uri retrieved from toString An error is
* thrown if fullUrl is not associated with the FirebaseApp used to initialize this FirebaseStorage.
* @return An instance of [StorageReference] at the given url.
*/
public fun getReferenceFromUrl(fullUrl: String): StorageReference
}
@Deprecated("Deprecated to use Kotlin Duration", replaceWith = ReplaceWith("maxOperationRetryTime"))
public val FirebaseStorage.maxOperationRetryTimeMillis: Long get() = maxOperationRetryTime.inWholeMilliseconds
@Deprecated("Deprecated to use Kotlin Duration", replaceWith = ReplaceWith("maxUploadRetryTime"))
public val FirebaseStorage.maxUploadRetryTimeMillis: Long get() = maxUploadRetryTime.inWholeMilliseconds
@Deprecated("Deprecated to use Kotlin Duration", replaceWith = ReplaceWith("setMaxOperationRetryTime(maxOperationRetryTimeMillis.milliseconds)"))
public fun FirebaseStorage.setMaxOperationRetryTimeMillis(maxOperationRetryTimeMillis: Long) {
setMaxOperationRetryTime(maxOperationRetryTimeMillis.milliseconds)
}
@Deprecated("Deprecated to use Kotlin Duration", replaceWith = ReplaceWith("setMaxUploadRetryTime(maxUploadRetryTimeMillis.milliseconds)"))
public fun FirebaseStorage.setMaxUploadRetryTimeMillis(maxUploadRetryTimeMillis: Long) {
setMaxUploadRetryTime(maxUploadRetryTimeMillis.milliseconds)
}
/**
* Represents a reference to a Google Cloud Storage object. Developers can upload and download
* objects, get/set object metadata, and delete an object at a specified path.
*/
public expect class StorageReference {
/**
* Returns the short name of this object.
*
* @return the name.
*/
public val name: String
/**
* Returns the full path to this object, not including the Google Cloud Storage bucket.
*
* @return the path.
*/
public val path: String
/**
* Return the Google Cloud Storage bucket that holds this object.
*
* @return the bucket.
*/
public val bucket: String
/**
* Returns a new instance of [StorageReference] pointing to the parent location or null if
* this instance references the root location. For example:
*
* ```
* path = foo/bar/baz parent = foo/bar
* path = foo parent = (root)
* path = (root) parent = (null)
* ```
*
* @return the parent [StorageReference].
*/
public val parent: StorageReference?
/**
* Returns a new instance of {@link StorageReference} pointing to the root location.
*
* @return the root {@link StorageReference}.
*/
public val root: StorageReference
/**
* Returns the [FirebaseStorage] service which created this reference.
*
* @return The [FirebaseStorage] service.
*/
public val storage: FirebaseStorage
/**
* Retrieves metadata associated with an object at this [StorageReference].
*
* @return the metadata.
*/
public suspend fun getMetadata(): FirebaseStorageMetadata?
/**
* Returns a new instance of [StorageReference] pointing to a child location of the current
* reference. All leading and trailing slashes will be removed, and consecutive slashes will be
* compressed to single slashes. For example:
*
* ```
* child = /foo/bar path = foo/bar
* child = foo/bar/ path = foo/bar
* child = foo///bar path = foo/bar
* ```
*
* @param path The relative path from this reference.
* @return the child [StorageReference].
*/
public fun child(path: String): StorageReference
/**
* Deletes the object at this {@link StorageReference}.
*
* @return A {@link Task} that indicates whether the operation succeeded or failed.
*/
public suspend fun delete()
/**
* 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.
*
* @return The String representing the download URL.
*/
public suspend fun getDownloadUrl(): String
/**
* List all items (files) and prefixes (folders) under this StorageReference.
*
* This is a helper method for calling list() repeatedly until there are no more
* results. Consistency of the result is not guaranteed if objects are inserted or removed while
* this operation is executing.
*
* [listAll] is only available for projects using Firebase Rules Version 2.
*
* @return A [ListResult] that returns all items and prefixes under the current StorageReference.
*/
public suspend fun listAll(): ListResult
/**
* Asynchronously uploads from a content URI to this [StorageReference].
*
* @param file The source of the upload. This is a [File]. A content
* resolver will be used to load the data.
* @param metadata [FirebaseStorageMetadata] containing additional information (MIME type, etc.)
* about the object being uploaded.
*/
public suspend fun putFile(file: File, metadata: FirebaseStorageMetadata? = null)
/**
* Asynchronously uploads byte data to this [StorageReference]. This is not recommended for
* large files. Instead upload a file via [putFile].
*
* @param data The [Data] to upload.
* @param metadata [FirebaseStorageMetadata] containing additional information (MIME type, etc.)
* about the object being uploaded.
*/
public suspend fun putData(data: Data, metadata: FirebaseStorageMetadata? = null)
/**
* Asynchronously uploads from a content URI to this [StorageReference].
*
* @param file The source of the upload. This is a [File]. A content
* resolver will be used to load the data.
* @param metadata [FirebaseStorageMetadata] containing additional information (MIME type, etc.)
* about the object being uploaded.
* @return A [ProgressFlow] that can be used to monitor and manage the upload.
*/
public fun putFileResumable(file: File, metadata: FirebaseStorageMetadata? = null): ProgressFlow
}
public expect class ListResult {
public val prefixes: List<StorageReference>
public val items: List<StorageReference>
public val pageToken: String?
}
/**
* Represents a reference to a local file for all platforms. Every platform has its own constructor.
*/
public expect class File
/**
* Represents a reference to data for all platforms. Every platform has its own constructor.
*/
public expect class Data
/**
* Represents the progress of an operation.
*/
public sealed class Progress(public val bytesTransferred: Number, public val totalByteCount: Number) {
/** Represents the progress of an operation that is still running. */
public class Running internal constructor(bytesTransferred: Number, totalByteCount: Number) : Progress(bytesTransferred, totalByteCount)
/** Represents the progress of an operation that is paused. */
public class Paused internal constructor(bytesTransferred: Number, totalByteCount: Number) : Progress(bytesTransferred, totalByteCount)
}
/**
* A flow that emits [Progress] objects containing the state of an upload.
*/
public interface ProgressFlow : Flow<Progress> {
public fun pause()
public fun resume()
public fun cancel()
}
/**
* Exception that gets thrown when an operation on Firebase Storage fails.
*/
public expect class FirebaseStorageException : FirebaseException
/**
* Metadata for a [StorageReference]. Metadata stores default attributes such as size and
* content type. You may also store custom metadata key value pairs. Metadata values may be used to
* authorize operations using declarative validation rules.
*/
public data class FirebaseStorageMetadata(
/**
* Returns the path of the [StorageReference] object.
*
* @return the MD5Hash of the [StorageReference] object
*/
var md5Hash: String? = null,
/**
* Returns the size of the [StorageReference] object in bytes.
*
* @return the Cache Control header for the [StorageReference]
*/
var cacheControl: String? = null,
/**
* Returns the content disposition of the [StorageReference]
*
* @return the content disposition of the [StorageReference]
*/
var contentDisposition: String? = null,
/**
* Returns the content encoding for the [StorageReference]
*
* @return the content encoding for the [StorageReference]
*/
var contentEncoding: String? = null,
/**
* Returns the content language for the [StorageReference]
*
* @return the content language for the [StorageReference]
*/
var contentLanguage: String? = null,
/**
* Returns the Content Type of this associated [StorageReference]
*
* @return the Content Type of this associated [StorageReference]
*/
var contentType: String? = null,
/**
* Returns custom metadata for a StorageReference
*
* @return the metadata stored in the object.
*/
var customMetadata: MutableMap<String, String> = mutableMapOf(),
) {
/**
* Sets custom metadata
*
* @param key the key of the new value
* @param value the value to set.
*/
public fun setCustomMetadata(key: String, value: String?) {
value?.let {
customMetadata[key] = it
}
}
}
/** Returns a [FirebaseStorageMetadata] object initialized using the [init] function. */
public fun storageMetadata(init: FirebaseStorageMetadata.() -> Unit): FirebaseStorageMetadata {
val metadata = FirebaseStorageMetadata()
metadata.init()
return metadata
}