diff options
author | Sebastian Schmidt <mrschmidt@google.com> | 2017-12-11 16:05:32 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-12-11 16:05:32 -0800 |
commit | 03c0e9882a87f8b5ac0699d64e7d17f940a4796a (patch) | |
tree | 4463063b03d21f7d63101b6ac36a48ba6f4293dc /Firestore/Source/Public/FIRDocumentSnapshot.h | |
parent | c73770cac8c959d95579e0701791e272cb45ce89 (diff) | |
parent | b8714e3b8977567c7bd7b83163045d145be9ebb5 (diff) |
Merge pull request #537 from firebase/mrschmidt-timestamps
Adding Server Timestamp Options
Diffstat (limited to 'Firestore/Source/Public/FIRDocumentSnapshot.h')
-rw-r--r-- | Firestore/Source/Public/FIRDocumentSnapshot.h | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/Firestore/Source/Public/FIRDocumentSnapshot.h b/Firestore/Source/Public/FIRDocumentSnapshot.h index 3e67c25..994cabf 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. @@ -48,11 +97,56 @@ NS_SWIFT_NAME(DocumentSnapshot) /** * Retrieves all fields in the document as an `NSDictionary`. * + * 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. */ - (NSDictionary<NSString *, id> *)data; /** + * Retrieves all fields in the document as a `Dictionary`. + * + * @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. + */ +- (NSDictionary<NSString *, id> *)dataWithOptions:(FIRSnapshotOptions *)options; + +/** + * Retrieves a specific field from the document. + * + * 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 field doesn't exist. + */ +- (nullable id)valueForField:(id)field NS_SWIFT_NAME(get(_:)); + +/** + * Retrieves a specific field from the document. + * + * 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 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. |