firebase::firestore::Firestore

#include <firestore.h>

Entry point for the Firebase Firestore C++ SDK.

Summary

To use the SDK, call firebase::firestore::Firestore::GetInstance() to obtain an instance of Firestore, then use Collection() or Document() to obtain references to child paths within the database. From there, you can set data via CollectionReference::Add() and DocumentReference::Set(), or get data via CollectionReference::Get() and DocumentReference::Get(), attach listeners, and more.

Constructors and Destructors
Firestore(const Firestore & src)
Deleted copy constructor; Firestore must be created with Firestore::GetInstance().
~Firestore()
Destructor for the Firestore object.

Friend classes
csharp::ApiHeaders
friend class
csharp::TransactionManager
friend class

Public static functions
GetInstance(::firebase::App *app, InitResult *init_result_out)
Returns an instance of Firestore corresponding to the given App with default database ID.
GetInstance(InitResult *init_result_out)
Returns an instance of Firestore corresponding to the default App with default database ID.
GetInstance(::firebase::App *app, const char *db_name, InitResult *init_result_out)
Returns an instance of Firestore corresponding to the given App with the given database ID.
GetInstance(const char *db_name, InitResult *init_result_out)
Returns an instance of Firestore corresponding to the default App with the given database ID.
set_log_level(LogLevel log_level)
void
Sets the log verbosity of all Firestore instances.

Public functions
AddSnapshotsInSyncListener(std::function< void()> callback)
Attaches a listener for a snapshots-in-sync event.
ClearPersistence()
virtual Future< void >
Clears the persistent storage.
Collection(const char *collection_path) const
Returns a CollectionReference instance that refers to the collection at the specified path within the database.
Collection(const std::string & collection_path) const
Returns a CollectionReference instance that refers to the collection at the specified path within the database.
CollectionGroup(const char *collection_id) const
virtual Query
Returns a Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.
CollectionGroup(const std::string & collection_id) const
virtual Query
Returns a Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.
DisableNetwork()
virtual Future< void >
Disables network access for this instance.
Document(const char *document_path) const
Returns a DocumentReference instance that refers to the document at the specified path within the database.
Document(const std::string & document_path) const
Returns a DocumentReference instance that refers to the document at the specified path within the database.
EnableNetwork()
virtual Future< void >
Re-enables network usage for this instance after a prior call to DisableNetwork().
LoadBundle(const std::string & bundle)
Loads a Firestore bundle into the local cache.
LoadBundle(const std::string & bundle, std::function< void(const LoadBundleTaskProgress &)> progress_callback)
Loads a Firestore bundle into the local cache, with the provided callback executed for progress updates.
NamedQuery(const std::string & query_name)
virtual Future< Query >
Reads a FirestoreQuery from the local cache, identified by the given name.
RunTransaction(std::function< Error(Transaction &, std::string &)> update)
virtual Future< void >
Executes the given update and then attempts to commit the changes applied within the transaction.
RunTransaction(TransactionOptions options, std::function< Error(Transaction &, std::string &)> update)
virtual Future< void >
Executes the given update and then attempts to commit the changes applied within the transaction.
Terminate()
virtual Future< void >
Terminates this Firestore instance.
WaitForPendingWrites()
virtual Future< void >
Waits until all currently pending writes for the active user have been acknowledged by the backend.
app() const
virtual const App *
Returns the firebase::App that this Firestore was created with.
app()
virtual App *
Returns the firebase::App that this Firestore was created with.
batch() const
virtual WriteBatch
Creates a write batch, used for performing multiple writes as a single atomic operation.
operator=(const Firestore & src)=delete
Deleted copy assignment operator; Firestore must be created with Firestore::GetInstance().
set_settings(Settings settings)
virtual void
Sets any custom settings used to configure this Firestore object.
settings() const
virtual Settings
Returns the settings used by this Firestore object.

Protected functions
Firestore()=default
Default constructor, to be used only for mocking Firestore.

Friend classes

csharp::ApiHeaders

friend class csharp::ApiHeaders

csharp::TransactionManager

friend class csharp::TransactionManager

Public static functions

GetInstance

Firestore * GetInstance(
  ::firebase::App *app,
  InitResult *init_result_out
)

Returns an instance of Firestore corresponding to the given App with default database ID.

Firebase Firestore uses firebase::App to communicate with Firebase Authentication to authenticate users to the Firestore server backend.

If you call GetInstance() multiple times with the same App, you will get the same instance of Firestore.

Details
Parameters
app
Your instance of firebase::App. Firebase Firestore will use this to communicate with Firebase Authentication.
init_result_out
If provided, the initialization result will be written here. Will be set to firebase::kInitResultSuccess if initialization succeeded, or firebase::kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.
Returns
An instance of Firestore corresponding to the given App with default database ID.

GetInstance

Firestore * GetInstance(
  InitResult *init_result_out
)

Returns an instance of Firestore corresponding to the default App with default database ID.

Firebase Firestore uses the default App to communicate with Firebase Authentication to authenticate users to the Firestore server backend.

If you call GetInstance() multiple times, you will get the same instance.

Details
Parameters
init_result_out
If provided, the initialization result will be written here. Will be set to firebase::kInitResultSuccess if initialization succeeded, or firebase::kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.
Returns
An instance of Firestore corresponding to the default App with default database ID.

GetInstance

Firestore * GetInstance(
  ::firebase::App *app,
  const char *db_name,
  InitResult *init_result_out
)

Returns an instance of Firestore corresponding to the given App with the given database ID.

Firebase Firestore uses firebase::App to communicate with Firebase Authentication to authenticate users to the Firestore server backend.

If you call GetInstance() multiple times with the same App, you will get the same instance of Firestore.

Details
Parameters
app
Your instance of firebase::App. Firebase Firestore will use this to communicate with Firebase Authentication.
db_name
Name of the database. Firebase Firestore will use this to communicate with Firebase Authentication.
init_result_out
If provided, the initialization result will be written here. Will be set to firebase::kInitResultSuccess if initialization succeeded, or firebase::kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.
Returns
An instance of Firestore corresponding to the given App with the given database ID.

GetInstance

Firestore * GetInstance(
  const char *db_name,
  InitResult *init_result_out
)

Returns an instance of Firestore corresponding to the default App with the given database ID.

Firebase Firestore uses firebase::App to communicate with Firebase Authentication to authenticate users to the Firestore server backend.

If you call GetInstance() multiple times with the same App, you will get the same instance of Firestore.

Details
Parameters
db_name
Name of the database. Firebase Firestore will use this to communicate with Firebase Authentication.
init_result_out
If provided, the initialization result will be written here. Will be set to firebase::kInitResultSuccess if initialization succeeded, or firebase::kInitResultFailedMissingDependency on Android if Google Play services is not available on the current device.
Returns
An instance of Firestore corresponding to the default App with the given database ID.

set_log_level

void set_log_level(
  LogLevel log_level
)

Sets the log verbosity of all Firestore instances.

The default verbosity level is kLogLevelInfo.

Details
Parameters
log_level
The desired verbosity.

Public functions

AddSnapshotsInSyncListener

virtual ListenerRegistration AddSnapshotsInSyncListener(
  std::function< void()> callback
)

Attaches a listener for a snapshots-in-sync event.

Server-generated updates and local changes can affect multiple snapshot listeners. The snapshots-in-sync event indicates that all listeners affected by a given change have fired.

NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server.

Details
Parameters
callback
A callback to be called every time all snapshot listeners are in sync with each other.
Returns
A ListenerRegistration object that can be used to remove the listener.

ClearPersistence

virtual Future< void > ClearPersistence()

Clears the persistent storage.

This includes pending writes and cached documents.

Must be called while the Firestore instance is not started (after the app is shut down or when the app is first initialized). On startup, this method must be called before other methods (other than settings() and set_settings()). If the Firestore instance is still running, the function will complete with an error code of FailedPrecondition.

Note: ClearPersistence() is primarily intended to help write reliable tests that use Firestore. It uses the most efficient mechanism possible for dropping existing data but does not attempt to securely overwrite or otherwise make cached data unrecoverable. For applications that are sensitive to the disclosure of cache data in between user sessions we strongly recommend not to enable persistence in the first place.

Collection

virtual CollectionReference Collection(
  const char *collection_path
) const

Returns a CollectionReference instance that refers to the collection at the specified path within the database.

Details
Parameters
collection_path
A slash-separated path to a collection.
Returns
The CollectionReference instance.

Collection

virtual CollectionReference Collection(
  const std::string & collection_path
) const

Returns a CollectionReference instance that refers to the collection at the specified path within the database.

Details
Parameters
collection_path
A slash-separated path to a collection.
Returns
The CollectionReference instance.

CollectionGroup

virtual Query CollectionGroup(
  const char *collection_id
) const

Returns a Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.

Details
Parameters
collection_id
Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash.
Returns
The Query instance.

CollectionGroup

virtual Query CollectionGroup(
  const std::string & collection_id
) const

Returns a Query instance that includes all documents in the database that are contained in a collection or subcollection with the given collection_id.

Details
Parameters
collection_id
Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash.
Returns
The Query instance.

DisableNetwork

virtual Future< void > DisableNetwork()

Disables network access for this instance.

While the network is disabled, any snapshot listeners or Get() calls will return results from cache, and any write operations will be queued until network usage is re-enabled via a call to EnableNetwork().

If the network was already disabled, calling DisableNetwork() again is a no-op.

Document

virtual DocumentReference Document(
  const char *document_path
) const

Returns a DocumentReference instance that refers to the document at the specified path within the database.

Details
Parameters
document_path
A slash-separated path to a document.
Returns
The DocumentReference instance.

Document

virtual DocumentReference Document(
  const std::string & document_path
) const

Returns a DocumentReference instance that refers to the document at the specified path within the database.

Details
Parameters
document_path
A slash-separated path to a document.
Returns
The DocumentReference instance.

EnableNetwork

virtual Future< void > EnableNetwork()

Re-enables network usage for this instance after a prior call to DisableNetwork().

If the network is currently enabled, calling EnableNetwork() is a no-op.

Firestore

 Firestore(
  const Firestore & src
)=delete

Deleted copy constructor; Firestore must be created with Firestore::GetInstance().

LoadBundle

virtual Future< LoadBundleTaskProgress > LoadBundle(
  const std::string & bundle
)

Loads a Firestore bundle into the local cache.

Details
Parameters
bundle
A string containing the bundle to be loaded.
Returns
A Future that is resolved when the loading is either completed or aborted due to an error.

LoadBundle

virtual Future< LoadBundleTaskProgress > LoadBundle(
  const std::string & bundle,
  std::function< void(const LoadBundleTaskProgress &)> progress_callback
)

Loads a Firestore bundle into the local cache, with the provided callback executed for progress updates.

Details
Parameters
bundle
A string containing the bundle to be loaded.
progress_callback
A callback that is called with progress updates, and completion or error updates.
Returns
A Future that is resolved when the loading is either completed or aborted due to an error.

NamedQuery

virtual Future< Query > NamedQuery(
  const std::string & query_name
)

Reads a FirestoreQuery from the local cache, identified by the given name.

Named queries are packaged into bundles on the server side (along with the resulting documents) and loaded into local cache using LoadBundle. Once in the local cache, you can use this method to extract a query by name.

If a query cannot be found, the returned future will complete with its error() set to a non-zero error code.

Details
Parameters
query_name
The name of the query to read from saved bundles.

RunTransaction

virtual Future< void > RunTransaction(
  std::function< Error(Transaction &, std::string &)> update
)

Executes the given update and then attempts to commit the changes applied within the transaction.

If any document read within the transaction has changed, the update function will be retried. If it fails to commit after 5 attempts, the transaction will fail.

Details
Parameters
update
function or lambda to execute within the transaction context. The string reference parameter can be used to set the error message.
Returns
A Future that will be resolved when the transaction finishes.

RunTransaction

virtual Future< void > RunTransaction(
  TransactionOptions options,
  std::function< Error(Transaction &, std::string &)> update
)

Executes the given update and then attempts to commit the changes applied within the transaction.

If any document read within the transaction has changed, the update function will be retried. If it fails to commit after the max_attempts specified in the given TransactionOptions, the transaction will fail.

Details
Parameters
options
The transaction options for controlling execution.
update
function or lambda to execute within the transaction context. The string reference parameter can be used to set the error message.
Returns
A Future that will be resolved when the transaction finishes.

Terminate

virtual Future< void > Terminate()

Terminates this Firestore instance.

After calling Terminate(), only the ClearPersistence() method may be used. Calling any other methods will result in an error.

To restart after termination, simply create a new instance of Firestore with Firestore::GetInstance().

Terminate() does not cancel any pending writes and any tasks that are awaiting a response from the server will not be resolved. The next time you start this instance, it will resume attempting to send these writes to the server.

Note: under normal circumstances, calling Terminate() is not required. This method is useful only when you want to force this instance to release all of its resources or in combination with ClearPersistence() to ensure that all local state is destroyed between test runs.

Details
Returns
A Future that is resolved when the instance has been successfully terminated.

WaitForPendingWrites

virtual Future< void > WaitForPendingWrites()

Waits until all currently pending writes for the active user have been acknowledged by the backend.

The returned future is resolved immediately without error if there are no outstanding writes. Otherwise, the future is resolved when all previously issued writes (including those written in a previous app session) have been acknowledged by the backend. The future does not wait for writes that were added after the method is called. If you wish to wait for additional writes, you have to call WaitForPendingWrites again.

Any outstanding WaitForPendingWrites futures are resolved with an error during user change.

app

virtual const App * app() const

Returns the firebase::App that this Firestore was created with.

Details
Returns
The firebase::App this Firestore was created with.

app

virtual App * app()

Returns the firebase::App that this Firestore was created with.

Details
Returns
The firebase::App this Firestore was created with.

batch

virtual WriteBatch batch() const

Creates a write batch, used for performing multiple writes as a single atomic operation.

Unlike transactions, write batches are persisted offline and therefore are preferable when you don't need to condition your writes on read data.

Details
Returns
The created WriteBatch object.

operator=

Firestore & operator=(
  const Firestore & src
)=delete

Deleted copy assignment operator; Firestore must be created with Firestore::GetInstance().

set_settings

virtual void set_settings(
  Settings settings
)

Sets any custom settings used to configure this Firestore object.

settings

virtual Settings settings() const

Returns the settings used by this Firestore object.

~Firestore

virtual  ~Firestore()

Destructor for the Firestore object.

When deleted, this instance will be removed from the cache of Firestore objects. If you call GetInstance() in the future with the same App, a new Firestore instance will be created.

Protected functions

Firestore

 Firestore()=default

Default constructor, to be used only for mocking Firestore.