change api interface

FirebaseFirestoreInternal/FirebaseFirestore/FIRSnapshotListenOptions.h

@@ -0,0 +1,15 @@
+// Copyright 2024 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/Source/API/FIRDocumentReference.mm

@@ -212,6 +212,13 @@ - (void)getDocumentWithSource:(FIRFirestoreSource)source
   return [self addSnapshotListenerInternalWithOptions:options listener:listener];
 }
 
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:(FIRSnapshotListenOptions *)options
+                                                     listener:(FIRDocumentSnapshotBlock)listener {
+  // Mila
+  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 init];
+  if (self) {
+    _source = source;
+    _includeMetadataChanges = includeMetadataChanges;
+  }
+  return self;
+}
+
+- (instancetype)init {
+  self = [super init];
+  if (self) {
+    _source = FIRListenSourceDefault;
+    _includeMetadataChanges = NO;
+  }
+  return self;
+}
+
+- (FIRSnapshotListenOptions *)optionsWithIncludeMetadataChanges:(BOOL)includeMetadataChanges {
+  FIRSnapshotListenOptions *newOptions =
+      [[FIRSnapshotListenOptions alloc] initPrivateWithSource:self.source
+                                       includeMetadataChanges:includeMetadataChanges];
+  return newOptions;
+}
+
+- (FIRSnapshotListenOptions *)optionsWithSource:(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;
@@ -270,6 +271,23 @@ addSnapshotListenerWithIncludeMetadataChanges:(BOOL)includeMetadataChanges
     NS_SWIFT_NAME(addSnapshotListener(includeMetadataChanges:listener:));
 // clang-format on
 
+/**
+ * Attaches a listener for `DocumentSnapshot` events.
+ *
+ * @param options Sets snapshot listen options, including whether metadata-only changes should
+ *     trigger snapshot events, the source that listens to, the executor to use to call the
+ *     listener, or the activity to scope the listener to.
+ * @param listener The listener to attach.
+ *
+ * @return A `ListenerRegistration` that can be used to remove this listener.
+ */
+// clang-format off
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
+                                   (FIRSnapshotListenOptions *)options
+                                                     listener:(void (^)(FIRDocumentSnapshot *_Nullable snapshot,NSError *_Nullable error))listener
+    NS_SWIFT_NAME(addSnapshotListener(options:listener:));
+// clang-format on
+
 @end
 
 NS_ASSUME_NONNULL_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,21 @@ NS_SWIFT_NAME(Query)
                                                             NSError *_Nullable error))listener
     NS_SWIFT_NAME(addSnapshotListener(includeMetadataChanges:listener:));
 
+/**
+ * Attaches a listener for `QuerySnapshot` events.
+ * @param options Sets snapshot listen options, including whether metadata-only changes should
+ *     trigger snapshot events, the source that listens to, the executor to use to call the
+ *     listener, or the activity to scope the listener to.
+ * @param listener The listener to attach.
+ *
+ * @return A `ListenerRegistration` that can be used to remove this 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,39 @@
+/*
+ * Copyright 2024 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_DESIGNATED_INITIALIZER;
+
+- (FIRSnapshotListenOptions *)optionsWithIncludeMetadataChanges:(BOOL)includeMetadataChanges;
+- (FIRSnapshotListenOptions *)optionsWithSource:(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"