From 68f0e2dafbc99df0789be5fd0aa847ae69940363 Mon Sep 17 00:00:00 2001 From: zxu Date: Fri, 25 May 2018 15:06:19 -0400 Subject: Firestore project: Import of API interfaces. (#1337) - 198063502 Address comment upstream. by zxu - 197942352 Fix style upstream and fix destination depot in copybara. by zxu - 197925542 Fix headers with change from GitHub, see the current diff... by zxu - 197922012 Implement ListenerRegistration::Remove(). by zxu - 197713382 Implement more on listener class and implement ListenerRe... by zxu - 196551381 Implement more on listener class and implement the Docume... by zxu - 196276752 Implement the SnapshotMetadata with inline methods and (n... by zxu - 195841793 Implement the wrapper class for callback (EventListener). by zxu - 194112388 Add Android-Wrapper for DocumentReference's non-callback ... by zxu - 192445183 Add Android-Wrapper for Firestore's remaining methods. by zxu - 190986604 Manually import the public portion of by mcg - 189013767 Add Android-Wrapper for Firestore's method that does not ... by zxu - 188809445 Import of firebase-ios-sdk from Github. by mcg - 187049498 Import of firebase-ios-sdk from Github. by mcg - 184568931 Import of firebase-ios-sdk from Github. by mcg ORIGINAL_AUTHOR=Firebase PiperOrigin-RevId: 198063502 --- .../firebase/firestore/document_reference.h | 101 ++++++++------------- 1 file changed, 40 insertions(+), 61 deletions(-) (limited to 'Firestore/core/include/firebase/firestore/document_reference.h') diff --git a/Firestore/core/include/firebase/firestore/document_reference.h b/Firestore/core/include/firebase/firestore/document_reference.h index d295188..9385ed3 100644 --- a/Firestore/core/include/firebase/firestore/document_reference.h +++ b/Firestore/core/include/firebase/firestore/document_reference.h @@ -29,6 +29,17 @@ #include #endif +#include "firebase/app.h" +#include "firebase/firestore/collection_reference.h" +#include "firebase/firestore/document_snapshot.h" +#include "firebase/firestore/event_listener.h" +#include "firebase/firestore/field_value.h" +#include "firebase/firestore/firestore.h" +#include "firebase/firestore/firestore_errors.h" +#include "firebase/firestore/listener_registration.h" +#include "firebase/firestore/set_options.h" +#include "firebase/future.h" + // TODO(rsgowman): Note that RTDB uses: // #if defined(FIREBASE_USE_MOVE_OPERATORS) || defined(DOXYGEN // to protect move operators from older compilers. But all our supported @@ -36,34 +47,12 @@ // here so we don't forget to mention this during the API review, and should be // removed once this note has migrated to the API review doc. -// TODO(rsgowman): replace these forward decls with appropriate includes (once -// they exist) -namespace firebase { -class App; -template -class Future; -} // namespace firebase - namespace firebase { namespace firestore { -// TODO(rsgowman): replace these forward decls with appropriate includes (once -// they exist) -class FieldValue; -class DocumentSnapshot; +class DocumentReferenceInternal; class Firestore; -class Error; -template -class EventListener; -class ListenerRegistration; -class CollectionReference; -class DocumentListenOptions; -// TODO(rsgowman): not quite a forward decl, but required to make the default -// parameter to Set() "compile". -class SetOptions { - public: - SetOptions(); -}; +class FirestoreInternal; // TODO(rsgowman): move this into the FieldValue header #ifdef STLPORT @@ -80,12 +69,19 @@ using MapFieldValue = std::unordered_map; * * Create a DocumentReference via Firebase::Document(const string& path). * + * NOT thread-safe: an instance should not be used from multiple threads + * * Subclassing Note: Firestore classes are not meant to be subclassed except for * use in test mocks. Subclassing is not supported in production code and new * SDK releases may break code that does so. */ class DocumentReference { public: + enum class MetadataChanges { + kExclude, + kInclude, + }; + /** * @brief Default constructor. This creates an invalid DocumentReference. * Attempting to perform any operations on this reference will fail (and cause @@ -269,28 +265,15 @@ class DocumentReference { * this DocumentReference. (Ownership is not transferred; you are responsible * for making sure that listener is valid as long as this DocumentReference is * valid and the listener is registered.) + * @param[in] metadata_changes Indicates whether metadata-only changes (i.e. + * only DocumentSnapshot.getMetadata() changed) should trigger snapshot + * events. * * @return A registration object that can be used to remove the listener. */ virtual ListenerRegistration AddSnapshotListener( - EventListener* listener); - - /** - * @brief Starts listening to the document referenced by this - * DocumentReference. - * - * @param[in] options The options to use for this listen. - * @param[in] listener The event listener that will be called with the - * snapshots, which must remain in memory until you remove the listener from - * this DocumentReference. (Ownership is not transferred; you are responsible - * for making sure that listener is valid as long as this DocumentReference is - * valid and the listener is registered.) - * - * @return A registration object that can be used to remove the listener. - */ - virtual ListenerRegistration AddSnapshotListener( - const DocumentListenOptions& options, - EventListener* listener); + EventListener* listener, + MetadataChanges metadata_changes = MetadataChanges::kExclude); #if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN) /** @@ -299,6 +282,9 @@ class DocumentReference { * * @param[in] callback function or lambda to call. When this function is * called, exactly one of the parameters will be non-null. + * @param[in] metadata_changes Indicates whether metadata-only changes (i.e. + * only DocumentSnapshot.getMetadata() changed) should trigger snapshot + * events. * * @return A registration object that can be used to remove the listener. * @@ -306,28 +292,21 @@ class DocumentReference { * std::function is not supported on STLPort. */ virtual ListenerRegistration AddSnapshotListener( - std::function callback); - - /** - * @brief Starts listening to the document referenced by this - * DocumentReference. - * - * @param[in] options The options to use for this listen. - * @param[in] callback function or lambda to call. When this function is - * called, exactly one of the parameters will be non-null. - * - * @return A registration object that can be used to remove the listener. - * - * @note This method is not available when using STLPort on Android, as - * std::function is not supported on STLPort. - */ - virtual ListenerRegistration AddSnapshotListener( - const DocumentListenOptions& options, - std::function callback); + std::function callback, + MetadataChanges metadata_changes = MetadataChanges::kExclude); #endif // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN) + + protected: + explicit DocumentReference(DocumentReferenceInternal* internal); + + private: + friend class FirestoreInternal; + + // TODO(zxu123): investigate possibility to use std::unique_ptr or + // firebase::UniquePtr. + DocumentReferenceInternal* internal_ = nullptr; }; -// TODO(rsgowman): probably define and inline here. bool operator==(const DocumentReference& lhs, const DocumentReference& rhs); inline bool operator!=(const DocumentReference& lhs, -- cgit v1.2.3