diff options
Diffstat (limited to 'Firestore/Source/Public/FIRDocumentSnapshot.h')
-rw-r--r-- | Firestore/Source/Public/FIRDocumentSnapshot.h | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/Firestore/Source/Public/FIRDocumentSnapshot.h b/Firestore/Source/Public/FIRDocumentSnapshot.h index 6ae0199..9a095a5 100644 --- a/Firestore/Source/Public/FIRDocumentSnapshot.h +++ b/Firestore/Source/Public/FIRDocumentSnapshot.h @@ -22,6 +22,55 @@ NS_ASSUME_NONNULL_BEGIN /** + * Controls the return value for server timestamps that have not yet been set to + * their final value. + */ +typedef NS_ENUM(NSInteger, FIRServerTimestampBehavior) { + /** + * Return `NSNull` for `FieldValue.serverTimestamp()` fields that have not yet + * been set to their final value. + */ + FIRServerTimestampBehaviorNone, + + /** + * Return a local estimates for `FieldValue.serverTimestamp()` + * fields that have not yet been set to their final value. This estimate will + * likely differ from the final value and may cause these pending values to + * change once the server result becomes available. + */ + FIRServerTimestampBehaviorEstimate, + + /** + * Return the previous value for `FieldValue.serverTimestamp()` fields that + * have not yet been set to their final value. + */ + FIRServerTimestampBehaviorPrevious +}; + +/** + * Options that configure how data is retrieved from a `DocumentSnapshot` + * (e.g. the desired behavior for server timestamps that have not yet been set + * to their final value). + */ +NS_SWIFT_NAME(SnapshotOptions) +@interface FIRSnapshotOptions : NSObject + +/** */ +- (instancetype)init __attribute__((unavailable("FIRSnapshotOptions cannot be created directly."))); + +/** + * If set, controls the return value for `FieldValue.serverTimestamp()` + * fields that have not yet been set to their final value. + * + * If omitted, `NSNull` will be returned by default. + * + * @return The created `FIRSnapshotOptions` object. + */ ++ (instancetype)serverTimestampBehavior:(FIRServerTimestampBehavior)serverTimestampBehavior; + +@end + +/** * A `FIRDocumentSnapshot` contains data read from a document in your Firestore database. The data * can be extracted with the `data` property or by using subscript syntax to access a specific * field. @@ -52,12 +101,61 @@ NS_SWIFT_NAME(DocumentSnapshot) * Retrieves all fields in the document as an `NSDictionary`. Returns `nil` if the document doesn't * exist. * + * Server-provided timestamps that have not yet been set to their final value + * will be returned as `NSNull`. You can use `dataWithOptions()` to configure this + * behavior. + * * @return An `NSDictionary` containing all fields in the document or `nil` if the document doesn't * exist. */ - (nullable NSDictionary<NSString *, id> *)data; /** + * Retrieves all fields in the document as a `Dictionary`. Returns `nil` if the document doesn't + * exist. + * + * @param options `SnapshotOptions` to configure how data is returned from the + * snapshot (e.g. the desired behavior for server timestamps that have not + * yet been set to their final value). + * @return A `Dictionary` containing all fields in the document or `nil` if the document doesn't + * exist. + */ +- (nullable NSDictionary<NSString *, id> *)dataWithOptions:(FIRSnapshotOptions *)options; + +/** + * Retrieves a specific field from the document. Returns `nil` if the document or the + * field doesn't exist. + * + * The timestamps that have not yet been set to their final value + * will be returned as `NSNull`. The can use `get(_:options:)` to + * configure this behavior. + * + * @param field The field to retrieve. + * @return The value contained in the field or `nil` if the document or field doesn't exist. + */ +- (nullable id)valueForField:(id)field NS_SWIFT_NAME(get(_:)); + +/** + * Retrieves a specific field from the document. Returns `nil` if the document or the + * field doesn't exist. + * + * The timestamps that have not yet been set to their final value + * will be returned as `NSNull`. The can use `get(_:options:)` to + * configure this behavior. + * + * @param field The field to retrieve. + * @param options `SnapshotOptions` to configure how data is returned from the + * snapshot (e.g. the desired behavior for server timestamps that have not + * yet been set to their final value). + * @return The value contained in the field or `nil` if the document or field doesn't exist. + */ +// clang-format off +- (nullable id)valueForField:(id)field + options:(FIRSnapshotOptions *)options + NS_SWIFT_NAME(get(_:options:)); +// clang-format on + +/** * Retrieves a specific field from the document. * * @param key The field to retrieve. |