diff options
Diffstat (limited to 'Firestore/Source/Public/FIRDocumentReference.h')
| -rw-r--r-- | Firestore/Source/Public/FIRDocumentReference.h | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/Firestore/Source/Public/FIRDocumentReference.h b/Firestore/Source/Public/FIRDocumentReference.h new file mode 100644 index 0000000..03340c1 --- /dev/null +++ b/Firestore/Source/Public/FIRDocumentReference.h @@ -0,0 +1,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 |