firebase::firestore::DocumentReference

#include <document_reference.h>

A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location.

Summary

There may or may not exist a document at the referenced location. A DocumentReference can also be used to create a CollectionReference to a subcollection.

Create a DocumentReference via Firestore::Document(const std::string& path).

Constructors and Destructors

DocumentReference()
Creates an invalid DocumentReference that has to be reassigned before it can be used.
DocumentReference(const DocumentReference & other)
Copy constructor.
DocumentReference(DocumentReference && other)
Move constructor.
~DocumentReference()

Friend classes

operator<<
friend std::ostream &
Outputs the string representation of this DocumentReference to the given stream.

Public functions

AddSnapshotListener(std::function< void(const DocumentSnapshot &, Error, const std::string &)> callback)
Starts listening to the document referenced by this DocumentReference.
AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(const DocumentSnapshot &, Error, const std::string &)> callback)
Starts listening to the document referenced by this DocumentReference.
Collection(const char *collection_path) const
Returns a CollectionReference instance that refers to the subcollection at the specified path relative to this document.
Collection(const std::string & collection_path) const
Returns a CollectionReference instance that refers to the subcollection at the specified path relative to this document.
Delete()
virtual Future< void >
Removes the document referred to by this DocumentReference.
Get(Source source) const
Reads the document referenced by this DocumentReference.
Parent() const
Returns a CollectionReference to the collection that contains this document.
Set(const MapFieldValue & data, const SetOptions & options)
virtual Future< void >
Writes to the document referred to by this DocumentReference.
ToString() const
std::string
Returns a string representation of this DocumentReference for logging/debugging purposes.
Update(const MapFieldValue & data)
virtual Future< void >
Updates fields in the document referred to by this DocumentReference.
Update(const MapFieldPathValue & data)
virtual Future< void >
Updates fields in the document referred to by this DocumentReference.
firestore() const
virtual const Firestore *
Returns the Firestore instance associated with this document reference.
firestore()
virtual Firestore *
Returns the Firestore instance associated with this document reference.
id() const
virtual const std::string &
Returns the string ID of this document location.
is_valid() const
bool
Returns true if this DocumentReference is valid, false if it is not valid.
operator=(const DocumentReference & other)
Copy assignment operator.
operator=(DocumentReference && other)
Move assignment operator.
path() const
virtual std::string
Returns the path of this document (relative to the root of the database) as a slash-separated string.

Friend classes

operator<<

friend std::ostream & operator<<(std::ostream &out, const DocumentReference &reference)

Outputs the string representation of this DocumentReference to the given stream.

See also:ToString() for comments on the representation format.

Public functions

AddSnapshotListener

virtual ListenerRegistration AddSnapshotListener(
  std::function< void(const DocumentSnapshot &, Error, const std::string &)> callback
)

Starts listening to the document referenced by this DocumentReference.

Details
Parameters
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

AddSnapshotListener

virtual ListenerRegistration AddSnapshotListener(
  MetadataChanges metadata_changes,
  std::function< void(const DocumentSnapshot &, Error, const std::string &)> callback
)

Starts listening to the document referenced by this DocumentReference.

Details
Parameters
metadata_changes
Indicates whether metadata-only changes (that is, only DocumentSnapshot::metadata() changed) should trigger snapshot events.
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

Collection

virtual CollectionReference Collection(
  const char *collection_path
) const 

Returns a CollectionReference instance that refers to the subcollection at the specified path relative to this document.

Details
Parameters
collection_path
A slash-separated relative path to a subcollection. The pointer only needs to be valid during this call.
Returns
The CollectionReference instance.

Collection

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

Returns a CollectionReference instance that refers to the subcollection at the specified path relative to this document.

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

Delete

virtual Future< void > Delete()

Removes the document referred to by this DocumentReference.

Details
Returns
A Future that will be resolved when the delete completes.

DocumentReference

 DocumentReference()

Creates an invalid DocumentReference that has to be reassigned before it can be used.

Calling any member function on an invalid DocumentReference will be a no-op. If the function returns a value, it will return a zero, empty, or invalid value, depending on the type of the value.

DocumentReference

 DocumentReference(
  const DocumentReference & other
)

Copy constructor.

DocumentReference can be efficiently copied because it simply refers to a location in the database.

Details
Parameters
other
DocumentReference to copy from.

DocumentReference

 DocumentReference(
  DocumentReference && other
)

Move constructor.

Moving is more efficient than copying for a DocumentReference. After being moved from, a DocumentReference is equivalent to its default-constructed state.

Details
Parameters
other
DocumentReference to move data from.

Get

virtual Future< DocumentSnapshot > Get(
  Source source
) const 

Reads the document referenced by this DocumentReference.

By default, Get() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. This behavior can be altered via the Source parameter.

Details
Parameters
source
A value to configure the get behavior (optional).
Returns
A Future that will be resolved with the contents of the Document at this DocumentReference.

Parent

virtual CollectionReference Parent() const 

Returns a CollectionReference to the collection that contains this document.

Set

virtual Future< void > Set(
  const MapFieldValue & data,
  const SetOptions & options
)

Writes to the document referred to by this DocumentReference.

If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.

Details
Parameters
data
A map of the fields and values to write to the document.
options
An object to configure the Set() behavior (optional).
Returns
A Future that will be resolved when the write finishes.

ToString

std::string ToString() const 

Returns a string representation of this DocumentReference for logging/debugging purposes.

Update

virtual Future< void > Update(
  const MapFieldValue & data
)

Updates fields in the document referred to by this DocumentReference.

If no document exists yet, the update will fail.

Details
Parameters
data
A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.
Returns
A Future that will be resolved when the client is online and the commit has completed against the server. The future will not resolve when the device is offline, though local changes will be visible immediately.

Update

virtual Future< void > Update(
  const MapFieldPathValue & data
)

Updates fields in the document referred to by this DocumentReference.

If no document exists yet, the update will fail.

Details
Parameters
data
A map from FieldPath to FieldValue to update.
Returns
A Future that will be resolved when the client is online and the commit has completed against the server. The future will not resolve when the device is offline, though local changes will be visible immediately.

firestore

virtual const Firestore * firestore() const 

Returns the Firestore instance associated with this document reference.

The pointer will remain valid indefinitely.

Details
Returns
Firebase Firestore instance that this DocumentReference refers to.

firestore

virtual Firestore * firestore()

Returns the Firestore instance associated with this document reference.

The pointer will remain valid indefinitely.

Details
Returns
Firebase Firestore instance that this DocumentReference refers to.

id

virtual const std::string & id() const 

Returns the string ID of this document location.

Details
Returns
String ID of this document location.

is_valid

bool is_valid() const 

Returns true if this DocumentReference is valid, false if it is not valid.

An invalid DocumentReference could be the result of:

Details
Returns
true if this DocumentReference is valid, false if this DocumentReference is invalid.

operator=

DocumentReference & operator=(
  const DocumentReference & other
)

Copy assignment operator.

DocumentReference can be efficiently copied because it simply refers to a location in the database.

Details
Parameters
other
DocumentReference to copy from.
Returns
Reference to the destination DocumentReference.

operator=

DocumentReference & operator=(
  DocumentReference && other
)

Move assignment operator.

Moving is more efficient than copying for a DocumentReference. After being moved from, a DocumentReference is equivalent to its default-constructed state.

Details
Parameters
other
DocumentReference to move data from.
Returns
Reference to the destination DocumentReference.

path

virtual std::string path() const 

Returns the path of this document (relative to the root of the database) as a slash-separated string.

Details
Returns
String path of this document location.

~DocumentReference

virtual  ~DocumentReference()