Merge 19ee487 into 0fe8385

FirebaseFirestoreInternal/FirebaseFirestore/FIRSnapshotListenOptions.h

@@ -0,0 +1,15 @@
+// Copyright 2023 Google LLC
+//
+// 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 <FirebaseFirestoreInternal/FIRSnapshotListenOptions.h>

Firestore/Example/Tests/Integration/API/FIRFirestoreSourceTests.mm

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+#import <FirebaseFirestore/FIRSnapshotListenOptions.h>
 #import <FirebaseFirestore/FirebaseFirestore.h>
 
 #import <XCTest/XCTest.h>
@@ -700,4 +701,106 @@ - (void)testGetNonExistingCollectionWhileOfflineServerOnly {
   [self awaitExpectations];
 }
 
+// Document Reference
+- (void)DocumentReferenceDemo_addSnapshotListenerWithDefaultListenOptions {
+  FIRDocumentReference *doc = [self.db documentWithPath:@"cities/SF"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+
+  [doc addSnapshotListenerWithOptions:options
+                             listener:^(FIRDocumentSnapshot *snapshot, NSError *error) {
+                               XCTAssertNil(error);
+                               XCTAssertTrue(snapshot.exists);
+                             }];
+}
+
+- (void)DocumentReferenceDemo_addSnapshotListenerWithMetadataChanges {
+  FIRDocumentReference *doc = [self.db documentWithPath:@"cities/SF"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsWithMetadata = [options withIncludeMetadataChanges:YES];
+
+  [doc addSnapshotListenerWithOptions:optionsWithMetadata
+                             listener:^(FIRDocumentSnapshot *snapshot, NSError *error) {
+                               XCTAssertNil(error);
+                               XCTAssertTrue(snapshot.exists);
+                             }];
+}
+
+- (void)DocumentReferenceDemo_addSnapshotListenerFromCache {
+  FIRDocumentReference *doc = [self.db documentWithPath:@"cities/SF"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsFromCache = [options withSource:FIRListenSourceCache];
+
+  [doc addSnapshotListenerWithOptions:optionsFromCache
+                             listener:^(FIRDocumentSnapshot *snapshot, NSError *error) {
+                               XCTAssertNil(error);
+                               XCTAssertTrue(snapshot.exists);
+                             }];
+}
+
+- (void)DocumentReferenceDemo_addSnapshotListenerFromCacheAndIncludeMetadataChanges {
+  FIRDocumentReference *doc = [self.db documentWithPath:@"cities/SF"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsFromCacheAndWithMetadata =
+      [[options withIncludeMetadataChanges:YES] withSource:FIRListenSourceCache];
+
+  [doc addSnapshotListenerWithOptions:optionsFromCacheAndWithMetadata
+                             listener:^(FIRDocumentSnapshot *snapshot, NSError *error) {
+                               XCTAssertNil(error);
+                               XCTAssertTrue(snapshot.exists);
+                             }];
+}
+
+// Query
+- (void)QueryDemo_addSnapshotListenerWithDefaultListenOptions {
+  FIRCollectionReference *collection = [self.db collectionWithPath:@"cities"];
+  FIRQuery *query = [collection queryWhereField:@"state" isEqualTo:@ "CA"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+
+  [query addSnapshotListenerWithOptions:options
+                               listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
+                                 XCTAssertNil(error);
+                                 XCTAssertEqual(snapshot.count, 0);
+                               }];
+}
+
+- (void)QueryDemo_addSnapshotListenerWithMetadataChanges {
+  FIRCollectionReference *collection = [self.db collectionWithPath:@"cities"];
+  FIRQuery *query = [collection queryWhereField:@"state" isEqualTo:@ "CA"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsWithMetadata = [options withIncludeMetadataChanges:YES];
+
+  [query addSnapshotListenerWithOptions:optionsWithMetadata
+                               listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
+                                 XCTAssertNil(error);
+                                 XCTAssertEqual(snapshot.count, 0);
+                               }];
+}
+
+- (void)QueryDemo_addSnapshotListenerFromCache {
+  FIRCollectionReference *collection = [self.db collectionWithPath:@"cities"];
+  FIRQuery *query = [collection queryWhereField:@"state" isEqualTo:@ "CA"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsFromCache = [options withSource:FIRListenSourceCache];
+
+  [query addSnapshotListenerWithOptions:optionsFromCache
+                               listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
+                                 XCTAssertNil(error);
+                                 XCTAssertEqual(snapshot.count, 0);
+                               }];
+}
+
+- (void)QueryDemo_addSnapshotListenerFromCacheAndIncludeMetadataChanges {
+  FIRCollectionReference *collection = [self.db collectionWithPath:@"cities"];
+  FIRQuery *query = [collection queryWhereField:@"state" isEqualTo:@ "CA"];
+  FIRSnapshotListenOptions *options = [[FIRSnapshotListenOptions alloc] initWithDefaultOptions];
+  FIRSnapshotListenOptions *optionsFromCacheAndWithMetadata =
+      [[options withIncludeMetadataChanges:YES] withSource:FIRListenSourceCache];
+
+  [query addSnapshotListenerWithOptions:optionsFromCacheAndWithMetadata
+                               listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
+                                 XCTAssertNil(error);
+                                 XCTAssertEqual(snapshot.count, 0);
+                               }];
+}
+
 @end

Firestore/Source/API/FIRDocumentReference.mm

@@ -212,6 +212,12 @@ - (void)getDocumentWithSource:(FIRFirestoreSource)source
   return [self addSnapshotListenerInternalWithOptions:options listener:listener];
 }
 
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:(FIRSnapshotListenOptions *)options
+                                                     listener:(FIRDocumentSnapshotBlock)listener {
+  ListenOptions listenOptions = ListenOptions::FromIncludeMetadataChanges(false);
+  return [self addSnapshotListenerInternalWithOptions:listenOptions listener:listener];
+}
+
 - (id<FIRListenerRegistration>)addSnapshotListenerInternalWithOptions:(ListenOptions)internalOptions
                                                              listener:(FIRDocumentSnapshotBlock)
                                                                           listener {

Firestore/Source/API/FIRQuery.mm

@@ -191,6 +191,12 @@ - (void)getDocumentsWithSource:(FIRFirestoreSource)publicSource
   return [self addSnapshotListenerInternalWithOptions:options listener:listener];
 }
 
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:(FIRSnapshotListenOptions *)options
+                                                     listener:(FIRQuerySnapshotBlock)listener {
+  auto listenOptions = ListenOptions::FromIncludeMetadataChanges(false);
+  return [self addSnapshotListenerInternalWithOptions:listenOptions listener:listener];
+}
+
 - (id<FIRListenerRegistration>)addSnapshotListenerInternalWithOptions:(ListenOptions)internalOptions
                                                              listener:
                                                                  (FIRQuerySnapshotBlock)listener {

Firestore/Source/API/FIRSnapshotListenOptions.mm

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * 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 "FIRSnapshotListenOptions.h"
+
+#import <Foundation/Foundation.h>
+
+#include <cstdint>
+#include <string>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@implementation FIRSnapshotListenOptions
+
+// private method
+- (instancetype)initPrivateWithSource:(FIRListenSource)source
+               includeMetadataChanges:(BOOL)includeMetadataChanges {
+  self = [self initWithDefaultOptions];
+  if (self) {
+    _source = source;
+    _includeMetadataChanges = includeMetadataChanges;
+  }
+  return self;
+}
+
+- (instancetype)initWithDefaultOptions {
+  self = [super init];
+  if (self) {
+    _source = FIRListenSourceDefault;
+    _includeMetadataChanges = NO;
+  }
+  return self;
+}
+
+- (FIRSnapshotListenOptions *)withIncludeMetadataChanges:(BOOL)includeMetadataChanges {
+  FIRSnapshotListenOptions *newOptions =
+      [[FIRSnapshotListenOptions alloc] initPrivateWithSource:self.source
+                                       includeMetadataChanges:includeMetadataChanges];
+  return newOptions;
+}
+
+- (FIRSnapshotListenOptions *)withSource:(FIRListenSource)source {
+  FIRSnapshotListenOptions *newOptions =
+      [[FIRSnapshotListenOptions alloc] initPrivateWithSource:source
+                                       includeMetadataChanges:self.includeMetadataChanges];
+  return newOptions;
+}
+
+@end
+
+NS_ASSUME_NONNULL_END

Firestore/Source/Public/FirebaseFirestore/FIRDocumentReference.h

@@ -18,6 +18,7 @@
 
 #import "FIRFirestoreSource.h"
 #import "FIRListenerRegistration.h"
+#import "FIRSnapshotListenOptions.h"
 
 @class FIRCollectionReference;
 @class FIRDocumentSnapshot;
@@ -268,6 +269,12 @@ addSnapshotListenerWithIncludeMetadataChanges:(BOOL)includeMetadataChanges
                                      listener:(void (^)(FIRDocumentSnapshot *_Nullable snapshot,
                                                         NSError *_Nullable error))listener
     NS_SWIFT_NAME(addSnapshotListener(includeMetadataChanges:listener:));
+
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
+      (FIRSnapshotListenOptions *)options
+      listener:(void (^)(FIRDocumentSnapshot *_Nullable snapshot,NSError *_Nullable error))listener
+      NS_SWIFT_NAME(addSnapshotListener(options:listener:));
+
 // clang-format on
 
 @end

Firestore/Source/Public/FirebaseFirestore/FIRQuery.h

@@ -18,6 +18,7 @@
 
 #import "FIRFirestoreSource.h"
 #import "FIRListenerRegistration.h"
+#import "FIRSnapshotListenOptions.h"
 
 @class FIRAggregateQuery;
 @class FIRAggregateField;
@@ -104,6 +105,12 @@ NS_SWIFT_NAME(Query)
                                                             NSError *_Nullable error))listener
     NS_SWIFT_NAME(addSnapshotListener(includeMetadataChanges:listener:));
 
+- (id<FIRListenerRegistration>)
+    addSnapshotListenerWithOptions:(FIRSnapshotListenOptions *)options
+                          listener:(void (^)(FIRQuerySnapshot *_Nullable snapshot,
+                                             NSError *_Nullable error))listener
+    NS_SWIFT_NAME(addSnapshotListener(options:listener:));
+
 #pragma mark - Filtering Data
 /**
  * Creates and returns a new Query with the additional filter.

Firestore/Source/Public/FirebaseFirestore/FIRSnapshotListenOptions.h

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * 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>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef NS_ENUM(NSUInteger, FIRListenSource) {
+  FIRListenSourceDefault,
+  FIRListenSourceCache
+} NS_SWIFT_NAME(ListenSource);
+
+NS_SWIFT_NAME(SnapshotListenOptions)
+@interface FIRSnapshotListenOptions : NSObject
+
+@property(nonatomic, readonly) FIRListenSource source;
+@property(nonatomic, readonly) BOOL includeMetadataChanges;
+
+- (instancetype)init NS_UNAVAILABLE;
+- (instancetype)initWithDefaultOptions NS_DESIGNATED_INITIALIZER;
+
+- (FIRSnapshotListenOptions *)withIncludeMetadataChanges:(BOOL)includeMetadataChanges;
+- (FIRSnapshotListenOptions *)withSource:(FIRListenSource)source;
+
+@end
+
+NS_ASSUME_NONNULL_END

Firestore/Source/Public/FirebaseFirestore/FirebaseFirestore.h

@@ -34,6 +34,7 @@
 #import "FIRLocalCacheSettings.h"
 #import "FIRQuery.h"
 #import "FIRQuerySnapshot.h"
+#import "FIRSnapshotListenOptions.h"
 #import "FIRSnapshotMetadata.h"
 #import "FIRTimestamp.h"
 #import "FIRTransaction.h"