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
|
/*
* 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 "FIRFirestoreSwiftNameSupport.h"
#import "FIRListenerRegistration.h"
@class FIRFirestore;
@class FIRCollectionReference;
@class FIRDocumentSnapshot;
@class FIRSetOptions;
NS_ASSUME_NONNULL_BEGIN
/**
* Options for use with `[FIRDocumentReference addSnapshotListener]` to control the behavior of the
* snapshot listener.
*/
FIR_SWIFT_NAME(DocumentListenOptions)
@interface FIRDocumentListenOptions : NSObject
+ (instancetype)options NS_SWIFT_UNAVAILABLE("Use initializer");
- (instancetype)init;
@property(nonatomic, assign, readonly) BOOL includeMetadataChanges;
/**
* Sets the includeMetadataChanges option which controls whether metadata-only changes (i.e. only
* `FIRDocumentSnapshot.metadata` changed) should trigger snapshot events. Default is NO.
*
* @param includeMetadataChanges Whether to raise events for metadata-only changes.
* @return The receiver is returned for optional method chaining.
*/
- (instancetype)includeMetadataChanges:(BOOL)includeMetadataChanges
FIR_SWIFT_NAME(includeMetadataChanges(_:));
@end
typedef void (^FIRDocumentSnapshotBlock)(FIRDocumentSnapshot *_Nullable snapshot,
NSError *_Nullable error);
/**
* A `FIRDocumentReference` refers to a document location in a Firestore database and can be
* used to write, read, or listen to the location. The document at the referenced location
* may or may not exist. A `FIRDocumentReference` can also be used to create a
* `FIRCollectionReference` to a subcollection.
*/
FIR_SWIFT_NAME(DocumentReference)
@interface FIRDocumentReference : NSObject
/** */
- (instancetype)init
__attribute__((unavailable("FIRDocumentReference cannot be created directly.")));
/** The ID of the document referred to. */
@property(nonatomic, strong, readonly) NSString *documentID;
/** A reference to the collection to which this `DocumentReference` belongs. */
@property(nonatomic, strong, readonly) FIRCollectionReference *parent;
/** The `FIRFirestore` for the Firestore database (useful for performing transactions, etc.). */
@property(nonatomic, strong, readonly) FIRFirestore *firestore;
/**
* A string representing the path of the referenced document (relative to the root of the
* database).
*/
@property(nonatomic, strong, readonly) NSString *path;
/**
* Gets a `FIRCollectionReference` referring to the collection at the specified
* path, relative to this document.
*
* @param collectionPath The slash-separated relative path of the collection for which to get a
* `FIRCollectionReference`.
*
* @return The `FIRCollectionReference` at the specified _collectionPath_.
*/
- (FIRCollectionReference *)collectionWithPath:(NSString *)collectionPath
FIR_SWIFT_NAME(collection(_:));
#pragma mark - Writing Data
/**
* Writes to the document referred to by `FIRDocumentReference`. If the document doesn't yet exist,
* this method creates it and then sets the data. If the document exists, this method overwrites
* the document data with the new values.
*
* @param documentData An `NSDictionary` that contains the fields and data to write to the
* document.
*/
- (void)setData:(NSDictionary<NSString *, id> *)documentData;
/**
* Writes to the document referred to by this DocumentReference. If the document does not yet
* exist, it will be created. If you pass `FIRSetOptions`, the provided data will be merged into
* an existing document.
*
* @param documentData An `NSDictionary` that contains the fields and data to write to the
* document.
* @param options A `FIRSetOptions` used to configure the set behavior.
*/
- (void)setData:(NSDictionary<NSString *, id> *)documentData options:(FIRSetOptions *)options;
/**
* Overwrites the document referred to by this `FIRDocumentReference`. If no document exists, it
* is created. If a document already exists, it is overwritten.
*
* @param documentData An `NSDictionary` containing the fields that make up the document
* to be written.
* @param completion A block to execute once the document has been successfully written.
*/
- (void)setData:(NSDictionary<NSString *, id> *)documentData
completion:(nullable void (^)(NSError *_Nullable error))completion;
/**
* Writes to the document referred to by this DocumentReference. If the document does not yet
* exist, it will be created. If you pass `FIRSetOptions`, the provided data will be merged into
* an existing document.
*
* @param documentData An `NSDictionary` containing the fields that make up the document
* to be written.
* @param options A `FIRSetOptions` used to configure the set behavior.
* @param completion A block to execute once the document has been successfully written.
*/
- (void)setData:(NSDictionary<NSString *, id> *)documentData
options:(FIRSetOptions *)options
completion:(nullable void (^)(NSError *_Nullable error))completion;
/**
* Updates fields in the document referred to by this `FIRDocumentReference`.
* If the document does not exist, the update fails (specify a completion block to be notified).
*
* @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or
* `FIRFieldPath`) and values with which to update the document.
*/
- (void)updateData:(NSDictionary<id, id> *)fields;
/**
* Updates fields in the document referred to by this `FIRDocumentReference`. If the document
* does not exist, the update fails and the specified completion block receives an error.
*
* @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or
* `FIRFieldPath`) and values with which to update the document.
* @param completion A block to execute when the update is complete. If the update is successful the
* error parameter will be nil, otherwise it will give an indication of how the update failed.
*/
- (void)updateData:(NSDictionary<id, id> *)fields
completion:(nullable void (^)(NSError *_Nullable error))completion;
// NOTE: this is named 'deleteDocument' because 'delete' is a keyword in Objective-C++.
/** Deletes the document referred to by this `FIRDocumentReference`. */
// clang-format off
- (void)deleteDocument FIR_SWIFT_NAME(delete());
// clang-format on
/**
* Deletes the document referred to by this `FIRDocumentReference`.
*
* @param completion A block to execute once the document has been successfully deleted.
*/
// clang-format off
- (void)deleteDocumentWithCompletion:(nullable void (^)(NSError *_Nullable error))completion
FIR_SWIFT_NAME(delete(completion:));
// clang-format on
#pragma mark - Retrieving Data
/**
* Reads the document referenced by this `FIRDocumentReference`.
*
* @param completion a block to execute once the document has been successfully read.
*/
- (void)getDocumentWithCompletion:(FIRDocumentSnapshotBlock)completion
FIR_SWIFT_NAME(getDocument(completion:));
/**
* Attaches a listener for DocumentSnapshot events.
*
* @param listener The listener to attach.
*
* @return A FIRListenerRegistration that can be used to remove this listener.
*/
- (id<FIRListenerRegistration>)addSnapshotListener:(FIRDocumentSnapshotBlock)listener
FIR_SWIFT_NAME(addSnapshotListener(_:));
/**
* Attaches a listener for DocumentSnapshot events.
*
* @param options Options controlling the listener behavior.
* @param listener The listener to attach.
*
* @return A FIRListenerRegistration that can be used to remove this listener.
*/
// clang-format off
- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
(nullable FIRDocumentListenOptions *)options
listener:(FIRDocumentSnapshotBlock)listener
FIR_SWIFT_NAME(addSnapshotListener(options:listener:));
// clang-format on
@end
NS_ASSUME_NONNULL_END
|
