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
|
/*
* 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>
@class FIRApp;
@class FIRCollectionReference;
@class FIRDocumentReference;
@class FIRFirestoreSettings;
@class FIRTransaction;
@class FIRWriteBatch;
NS_ASSUME_NONNULL_BEGIN
/**
* `FIRFirestore` represents a Firestore Database and is the entry point for all Firestore
* operations.
*/
NS_SWIFT_NAME(Firestore)
@interface FIRFirestore : NSObject
#pragma mark - Initializing
/** */
- (instancetype)init __attribute__((unavailable("Use a static constructor method.")));
/**
* Creates, caches, and returns a `FIRFirestore` using the default `FIRApp`. Each subsequent
* invocation returns the same `FIRFirestore` object.
*
* @return The `FIRFirestore` instance.
*/
+ (instancetype)firestore NS_SWIFT_NAME(firestore());
/**
* Creates, caches, and returns a `FIRFirestore` object for the specified _app_. Each subsequent
* invocation returns the same `FIRFirestore` object.
*
* @param app The `FIRApp` instance to use for authentication and as a source of the Google Cloud
* Project ID for your Firestore Database. If you want the default instance, you should explicitly
* set it to `[FIRApp defaultApp]`.
*
* @return The `FIRFirestore` instance.
*/
+ (instancetype)firestoreForApp:(FIRApp *)app NS_SWIFT_NAME(firestore(app:));
/**
* Custom settings used to configure this `FIRFirestore` object.
*/
@property(nonatomic, copy) FIRFirestoreSettings *settings;
/**
* The Firebase App associated with this Firestore instance.
*/
@property(strong, nonatomic, readonly) FIRApp *app;
#pragma mark - Collections and Documents
/**
* Gets a `FIRCollectionReference` referring to the collection at the specified path within the
* database.
*
* @param collectionPath The slash-separated path of the collection for which to get a
* `FIRCollectionReference`.
*
* @return The `FIRCollectionReference` at the specified _collectionPath_.
*/
- (FIRCollectionReference *)collectionWithPath:(NSString *)collectionPath
NS_SWIFT_NAME(collection(_:));
/**
* Gets a `FIRDocumentReference` referring to the document at the specified path within the
* database.
*
* @param documentPath The slash-separated path of the document for which to get a
* `FIRDocumentReference`.
*
* @return The `FIRDocumentReference` for the specified _documentPath_.
*/
- (FIRDocumentReference *)documentWithPath:(NSString *)documentPath NS_SWIFT_NAME(document(_:));
#pragma mark - Transactions and Write Batches
/**
* Executes the given updateBlock and then attempts to commit the changes applied within an atomic
* transaction.
*
* In the updateBlock, a set of reads and writes can be performed atomically using the
* `FIRTransaction` object passed to the block. After the updateBlock is run, Firestore will attempt
* to apply the changes to the server. If any of the data read has been modified outside of this
* transaction since being read, then the transaction will be retried by executing the updateBlock
* again. If the transaction still fails after 5 retries, then the transaction will fail.
*
* Since the updateBlock may be executed multiple times, it should avoiding doing anything that
* would cause side effects.
*
* Any value maybe be returned from the updateBlock. If the transaction is successfully committed,
* then the completion block will be passed that value. The updateBlock also has an `NSError` out
* parameter. If this is set, then the transaction will not attempt to commit, and the given error
* will be passed to the completion block.
*
* The `FIRTransaction` object passed to the updateBlock contains methods for accessing documents
* and collections. Unlike other firestore access, data accessed with the transaction will not
* reflect local changes that have not been committed. For this reason, it is required that all
* reads are performed before any writes. Transactions must be performed while online. Otherwise,
* reads will fail, the final commit will fail, and the completion block will return an error.
*
* @param updateBlock The block to execute within the transaction context.
* @param completion The block to call with the result or error of the transaction. This
* block will run even if the client is offline, unless the process is killed.
*/
- (void)runTransactionWithBlock:(id _Nullable (^)(FIRTransaction *, NSError **))updateBlock
completion:(void (^)(id _Nullable result, NSError *_Nullable error))completion;
/**
* Creates a write batch, used for performing multiple writes as a single
* atomic operation.
*
* Unlike transactions, write batches are persisted offline and therefore are preferable when you
* don't need to condition your writes on read data.
*/
- (FIRWriteBatch *)batch;
#pragma mark - Logging
/** Enables or disables logging from the Firestore client. */
+ (void)enableLogging:(BOOL)logging DEPRECATED_MSG_ATTRIBUTE(
"Use FirebaseConfiguration.shared.setLoggerLevel(.debug) to enable "
"logging.");
#pragma mark - Network
/**
* Re-enables usage of the network by this Firestore instance after a prior call to
* `disableNetworkWithCompletion`. Completion block, if provided, will be called once network uasge
* has been enabled.
*/
- (void)enableNetworkWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
/**
* Disables usage of the network by this Firestore instance. It can be re-enabled by via
* `enableNetworkWithCompletion`. While the network is disabled, any snapshot listeners or get calls
* will return results from cache and any write operations will be queued until the network is
* restored. The completion block, if provided, will be called once network usage has been disabled.
*/
- (void)disableNetworkWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
@end
NS_ASSUME_NONNULL_END
|
