Firebase
view | history | commit | commitdiff
lpw
2020-09-01 a6c01451f65c7fc139844333f37345283d5f4354
commit | author | age
a6c014 1 /*
L 2  * Copyright 2020 Google LLC
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #import <Foundation/Foundation.h>
18
19 #import "GDTCORLifecycle.h"
20 #import "GDTCORStorageEventSelector.h"
21 #import "GDTCORTargets.h"
22
23 @class GDTCOREvent;
24 @class GDTCORClock;
25
26 NS_ASSUME_NONNULL_BEGIN
27
28 typedef void (^GDTCORStorageBatchBlock)(NSNumber *_Nullable newBatchID,
29                                         NSSet<GDTCOREvent *> *_Nullable batchEvents);
30
31 /** Defines the interface a storage subsystem is expected to implement. */
32 @protocol GDTCORStorageProtocol <NSObject, GDTCORLifecycleProtocol>
33
34 @required
35
36 /** Stores an event and calls onComplete with a non-nil error if anything went wrong.
37  *
38  * @param event The event to store
39  * @param completion The completion block to call after an attempt to store the event has been made.
40  */
41 - (void)storeEvent:(GDTCOREvent *)event
42         onComplete:(void (^_Nullable)(BOOL wasWritten, NSError *_Nullable error))completion;
43
44 /** Returns YES if some events have been stored for the given target, NO otherwise.
45  *
46  * @param onComplete The completion block to invoke when determining if there are events is done.
47  */
48 - (void)hasEventsForTarget:(GDTCORTarget)target onComplete:(void (^)(BOOL hasEvents))onComplete;
49
50 /** Constructs an event batch with the given event selector. Events in this batch will not be
51  * returned in any queries or other batches until the batch is removed.
52  *
53  * @param eventSelector The event selector used to find the events.
54  * @param expiration The expiration time of the batch. If removeBatchWithID:deleteEvents:onComplete:
55  * is not called within this time frame, the batch will be removed with its events deleted.
56  * @param onComplete The completion handler to be called when the events have been fetched.
57  */
58 - (void)batchWithEventSelector:(nonnull GDTCORStorageEventSelector *)eventSelector
59                batchExpiration:(nonnull NSDate *)expiration
60                     onComplete:(nonnull GDTCORStorageBatchBlock)onComplete;
61
62 /** Removes the event batch.
63  *
64  * @param batchID The batchID to remove.
65  * @param deleteEvents If YES, the events in this batch are deleted.
66  * @param onComplete The completion handler to call when the batch removal process has completed.
67  */
68 - (void)removeBatchWithID:(NSNumber *)batchID
69              deleteEvents:(BOOL)deleteEvents
70                onComplete:(void (^_Nullable)(void))onComplete;
71
72 /** Finds the batchIDs for the given target and calls the callback block.
73  *
74  * @param target The target.
75  * @param onComplete The block to invoke with the set of current batchIDs.
76  */
77 - (void)batchIDsForTarget:(GDTCORTarget)target
78                onComplete:(void (^)(NSSet<NSNumber *> *_Nullable batchIDs))onComplete;
79
80 /** Checks the storage for expired events and batches, deletes them if they're expired. */
81 - (void)checkForExpirations;
82
83 /** Persists the given data with the given key.
84  *
85  * @param data The data to store.
86  * @param key The unique key to store it to.
87  * @param onComplete An block to be run when storage of the data is complete.
88  */
89 - (void)storeLibraryData:(NSData *)data
90                   forKey:(NSString *)key
91               onComplete:(nullable void (^)(NSError *_Nullable error))onComplete;
92
93 /** Retrieves the stored data for the given key and optionally sets a new value.
94  *
95  * @param key The key corresponding to the desired data.
96  * @param onFetchComplete The callback to invoke with the data once it's retrieved.
97  * @param setValueBlock This optional block can provide a new value to set.
98  */
99 - (void)libraryDataForKey:(nonnull NSString *)key
100           onFetchComplete:(nonnull void (^)(NSData *_Nullable data,
101                                             NSError *_Nullable error))onFetchComplete
102               setNewValue:(NSData *_Nullable (^_Nullable)(void))setValueBlock;
103
104 /** Removes data from storage and calls the callback when complete.
105  *
106  * @param key The key of the data to remove.
107  * @param onComplete The callback that will be invoked when removing the data is complete.
108  */
109 - (void)removeLibraryDataForKey:(NSString *)key
110                      onComplete:(void (^)(NSError *_Nullable error))onComplete;
111
112 /** Calculates and returns the total disk size that this storage consumes.
113  *
114  * @param onComplete The callback that will be invoked once storage size calculation is complete.
115  */
116 - (void)storageSizeWithCallback:(void (^)(uint64_t storageSize))onComplete;
117
118 @end
119
120 /** Retrieves the storage instance for the given target.
121  *
122  * @param target The target.
123  * * @return The storage instance registered for the target, or nil if there is none.
124  */
125 FOUNDATION_EXPORT
126 id<GDTCORStorageProtocol> _Nullable GDTCORStorageInstanceForTarget(GDTCORTarget target);
127
128 NS_ASSUME_NONNULL_END