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)`	`virtual ListenerRegistration` Starts listening to the document referenced by this DocumentReference.
`AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(const DocumentSnapshot &, Error, const std::string &)> callback)`	`virtual ListenerRegistration` Starts listening to the document referenced by this DocumentReference.
`Collection(const char *collection_path) const`	`virtual CollectionReference` Returns a CollectionReference instance that refers to the subcollection at the specified path relative to this document.
`Collection(const std::string & collection_path) const`	`virtual CollectionReference` 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`	`virtual Future< DocumentSnapshot >` Reads the document referenced by this DocumentReference.
`Parent() const`	`virtual CollectionReference` 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)`	`DocumentReference &` Copy assignment operator.
`operator=(DocumentReference && other)`	`DocumentReference &` 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

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:

Creating a DocumentReference using the default constructor.
Moving from the DocumentReference.
Calling CollectionReference::Parent() on a CollectionReference that is not a subcollection.
Deleting your Firestore instance, which will invalidate all the DocumentReference instances associated with it.

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()

firebase::firestore::DocumentReference

Summary

Constructors and Destructors

Friend classes

Public functions

Friend classes

operator<<

Public functions

AddSnapshotListener

AddSnapshotListener

Collection

Collection

Delete

DocumentReference

DocumentReference

DocumentReference

Get

Parent

Set

ToString

Update

Update

firestore

firestore

id

is_valid

operator=

operator=

path

~DocumentReference