firebase::database::DatabaseReference

#include <database_reference.h>

DatabaseReference represents a particular location in your Database and can be used for reading or writing data to that Database location.

Summary

This class is the starting point for all Database operations. After you've initialized it with a URL, you can use it to read data, write data, and to create new DatabaseReference instances.

Inheritance

Inherits from: firebase::database::Query

Constructors and Destructors
DatabaseReference() Default constructor.
DatabaseReference(const DatabaseReference & reference) Copy constructor.
DatabaseReference(DatabaseReference && reference) Move constructor.
~DatabaseReference() Required virtual destructor.

Public functions
Child(const char *path) const	DatabaseReference Gets a reference to a location relative to this one.
Child(const std::string & path) const	DatabaseReference Gets a reference to a location relative to this one.
GetParent() const	DatabaseReference Gets the parent of this location, or get this location again if IsRoot().
GetRoot() const	DatabaseReference Gets the root of the database.
GoOffline()	void Manually disconnect Firebase Realtime Database from the server, and disable automatic reconnection.
GoOnline()	void Manually reestablish connection to the Firebase Realtime Database server and enable automatic reconnection.
OnDisconnect()	DisconnectionHandler * Get the disconnect handler, which controls what actions the server will perform to this location's data when this client disconnects.
PushChild() const	DatabaseReference Automatically generates a child location, create a reference to it, and returns that reference to it.
RemoveValue()	Future< void > Removes the value at this location from the database.
RemoveValueLastResult()	Future< void > Gets the result of the most recent call to RemoveValue();.
RunTransaction(DoTransactionWithContext transaction_function, void *context, bool trigger_local_events)	Future< DataSnapshot > Run a user-supplied callback function (passing in a context), possibly multiple times, to perform an atomic transaction on the database.
RunTransaction(DoTransactionFunction transaction_function, bool trigger_local_events)	Future< DataSnapshot > Run a user-supplied callback, possibly multiple times, to perform an atomic transaction on the database.
RunTransaction(DoTransaction transaction_function, bool trigger_local_events)	Future< DataSnapshot > Run a user-supplied callback function, possibly multiple times, to perform an atomic transaction on the database.
RunTransactionLastResult()	Future< DataSnapshot > Get the result of the most recent call to RunTransaction().
SetPriority(Variant priority)	Future< void > Sets the priority of this field, which controls its sort order relative to its siblings.
SetPriorityLastResult()	Future< void > Gets the result of the most recent call to SetPriority().
SetValue(Variant value)	Future< void > Sets the data at this location to the given value.
SetValueAndPriority(Variant value, Variant priority)	Future< void > Sets both the data and priority of this location.
SetValueAndPriorityLastResult()	Future< void > Get the result of the most recent call to SetValueAndPriority().
SetValueLastResult()	Future< void > Gets the result of the most recent call to SetValue().
UpdateChildren(Variant values)	Future< void > Updates the specified child keys to the given values.
UpdateChildren(const std::map< std::string, Variant > & values)	Future< void > Updates the specified child keys to the given values.
UpdateChildrenLastResult()	Future< void > Gets the result of the most recent call to either version of UpdateChildren().
database() const	Database * Gets the database to which we refer.
is_root() const	bool Returns true if this reference refers to the root of the database.
is_valid() const override	virtual bool Returns true if this reference is valid, false if it is not valid.
key() const	const char * Gets the string key of this database location.
key_string() const	std::string Gets the string key of this database location.
operator=(const DatabaseReference & reference)	DatabaseReference & Copy assignment operator.
operator=(DatabaseReference && reference)	DatabaseReference & Move assignment operator.
url() const	std::string Get the absolute URL of this reference.

Public functions

Child

DatabaseReference Child(
  const char *path
) const 

Gets a reference to a location relative to this one.

Details
Parameters	path Path relative to this snapshot's location. The pointer only needs to be valid during this call.
Returns	Child relative to this location.

Child

DatabaseReference Child(
  const std::string & path
) const 

Gets a reference to a location relative to this one.

Details
Parameters	path Path relative to this snapshot's location.
Returns	Child relative to this location.

DatabaseReference

 DatabaseReference()

Default constructor.

This creates an invalid DatabaseReference. Attempting to perform any operations on this reference will fail unless a valid DatabaseReference has been assigned to it.

DatabaseReference

 DatabaseReference(
  const DatabaseReference & reference
)

Copy constructor.

It's totally okay (and efficient) to copy DatabaseReference instances, as they simply point to the same location in the database.

Details
Parameters	reference DatabaseReference to copy from.

DatabaseReference

 DatabaseReference(
  DatabaseReference && reference
)

Move constructor.

Moving is an efficient operation for DatabaseReference instances.

Details
Parameters	reference DatabaseReference to move data from.

GetParent

DatabaseReference GetParent() const 

Gets the parent of this location, or get this location again if IsRoot().

Details
Returns	Parent of this location in the database, unless this location is the root, in which case it returns this same location again.

GetRoot

DatabaseReference GetRoot() const 

Gets the root of the database.

Details
Returns	Root of the database.

GoOffline

void GoOffline()

Manually disconnect Firebase Realtime Database from the server, and disable automatic reconnection.

This will affect all other instances of DatabaseReference as well.

GoOnline

void GoOnline()

Manually reestablish connection to the Firebase Realtime Database server and enable automatic reconnection.

This will affect all other instances of DatabaseReference as well.

OnDisconnect

DisconnectionHandler * OnDisconnect()

Get the disconnect handler, which controls what actions the server will perform to this location's data when this client disconnects.

Details
Returns	Disconnection handler for this location. You can use this to queue up operations on the server to be performed when the client disconnects.

PushChild

DatabaseReference PushChild() const 

Automatically generates a child location, create a reference to it, and returns that reference to it.

Details
Returns	A newly created child, with a unique key.

RemoveValue

Future< void > RemoveValue()

Removes the value at this location from the database.

This is an asynchronous operation which takes time to execute, and uses firebase::Future to return its result.

Note: Only one RemoveValue() should be running on a given database location at the same time. If you need to run multiple operations at once, use RunTransaction().

Details
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

RemoveValueLastResult

Future< void > RemoveValueLastResult()

Gets the result of the most recent call to RemoveValue();.

Details
Returns	Result of the most recent call to RemoveValue().

RunTransaction

Future< DataSnapshot > RunTransaction(
  DoTransactionWithContext transaction_function,
  void *context,
  bool trigger_local_events
)

Run a user-supplied callback function (passing in a context), possibly multiple times, to perform an atomic transaction on the database.

See also:firebase::database::DoTransactionWithContext for more information.

Note: Only one RunTransaction() should be running on a given database location at the same time.

Details
Parameters	transaction_function The user-supplied function that will be called, possibly multiple times, to perform the database transaction. context User-supplied context that will be passed to the transaction function. trigger_local_events If true, events will be triggered for intermediate state changes during the transaction. If false, only the final state will cause events to be triggered.
Returns	A Future result, which will complete when the transaction either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the transaction was committed, and the new value of the data will be returned in the DataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned in DataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set and DataSnapshot will be invalid.

RunTransaction

Future< DataSnapshot > RunTransaction(
  DoTransactionFunction transaction_function,
  bool trigger_local_events
)

Run a user-supplied callback, possibly multiple times, to perform an atomic transaction on the database.

See also:firebase::database::DoTransactionFunction for more information.

Note: Only one RunTransaction() should be running on a given database location at the same time.

Note: This version (that accepts an std::function) is not available when using stlport on Android. If you don't wish to use std::function, use the overloaded method that accepts a simple function pointer with a context.

Details
Parameters	transaction_function The user-supplied function or lambda that will be called, possibly multiple times, to perform the database transaction. trigger_local_events If true, events will be triggered for intermediate state changes during the transaction. If false, only the final state will cause events to be triggered.
Returns	A Future result, which will complete when the transaction either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the transaction was committed, and the new value of the data will be returned in the DataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned in DataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set and DataSnapshot will be invalid.

RunTransaction

Future< DataSnapshot > RunTransaction(
  DoTransaction transaction_function,
  bool trigger_local_events
)

Run a user-supplied callback function, possibly multiple times, to perform an atomic transaction on the database.

See also:firebase::database::DoTransaction for more information.

Note: Only one RunTransaction() should be running on a given database location at the same time.

Note: This version (that accepts a simple function pointer) is only available when using stlport and std::function is not available.

Details
Parameters	transaction_function The user-supplied function that will be called, possibly multiple times, to perform the database transaction. trigger_local_events If true, events will be triggered for intermediate state changes during the transaction. If false, only the final state will cause events to be triggered.
Returns	A Future result, which will complete when the transaction either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded and the transaction was committed, and the new value of the data will be returned in the DataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned in DataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set and DataSnapshot will be invalid.

RunTransactionLastResult

Future< DataSnapshot > RunTransactionLastResult()

Get the result of the most recent call to RunTransaction().

Details
Returns	Results of the most recent call to RunTransaction().

SetPriority

Future< void > SetPriority(
  Variant priority
)

Sets the priority of this field, which controls its sort order relative to its siblings.

In Firebase, children are sorted in the following order:

1. First, children with no priority.
2. Then, children with numerical priority, sorted numerically in ascending order.
3. Then, remaining children, sorted lexicographically in ascending order of their text priority.

Children with the same priority (including no priority) are sorted by key: A. First, children with keys that can be parsed as 32-bit integers, sorted in ascending numerical order of their keys. B. Then, remaining children, sorted in ascending lexicographical order of their keys.

This is an asynchronous operation which takes time to execute, and uses firebase::Future to return its result.

Note: Only one SetPriority() should be running on a given database location at the same time. If you need to run multiple operations at once, use RunTransaction().

Details
Parameters	priority Sort priority for this child relative to its siblings. The Variant types accepted are Null, Int64, Double, and String. Other types will return kErrorInvalidVariantType.
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

SetPriorityLastResult

Future< void > SetPriorityLastResult()

Gets the result of the most recent call to SetPriority().

Details
Returns	Result of the most recent call to SetPriority().

SetValue

Future< void > SetValue(
  Variant value
)

Sets the data at this location to the given value.

This is an asynchronous operation which takes time to execute, and uses firebase::Future to return its result.

Note: Only one SetValue() should be running on a given database location at the same time. If you need to run multiple operations at once, use RunTransaction().

Details
Parameters	value The value to set this location to. The Variant's type corresponds to the types accepted by the database JSON: Null: Deletes this location from the database. Int64: Inserts an integer value into this location. Double: Inserts a floating point value into this location. String: Inserts a string into this location. (Accepts both Mutable and Static strings) Vector: Inserts a JSON array into this location. The elements can be any Variant type, including Vector and Map. Map: Inserts a JSON associative array into this location. The keys must be of type String (or Int64/Double which are converted to String). The values can be any Variant type, including Vector and Map.
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

SetValueAndPriority

Future< void > SetValueAndPriority(
  Variant value,
  Variant priority
)

Sets both the data and priority of this location.

See SetValue() and SetPriority() for context on the parameters.

This is an asynchronous operation which takes time to execute, and uses firebase::Future to return its result.

Note: Only one SetValueAndPriority() should be running on a given database location at the same time. SetValueAndPriority() can't be used on the same location at the same time as either SetValue() or SetPriority(), and will return kErrorConflictingOperationInProgress if you try. If you need to run multiple operations at once, use RunTransaction().

Details
Parameters	value The value to set this location to. See SetValue() for information on the types accepted. priority The priority to set this location to. See SetPriority() for information on the types accepted.
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

SetValueAndPriorityLastResult

Future< void > SetValueAndPriorityLastResult()

Get the result of the most recent call to SetValueAndPriority().

Details
Returns	Result of the most recent call to SetValueAndPriority().

SetValueLastResult

Future< void > SetValueLastResult()

Gets the result of the most recent call to SetValue().

Details
Returns	Result of the most recent call to SetValue().

UpdateChildren

Future< void > UpdateChildren(
  Variant values
)

Updates the specified child keys to the given values.

Note: This method will return kErrorConflictingOperationInProgress if it is run at the same time as SetValue(), SetValueAndPriority(), or RemoveValue() in the same location.

Details
Parameters	values A variant of type Map. The keys are the paths to update and must be of type String (or Int64/Double which are converted to String). The values can be any Variant type. A value of Variant type Null will delete the child.
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

UpdateChildren

Future< void > UpdateChildren(
  const std::map< std::string, Variant > & values
)

Updates the specified child keys to the given values.

This is an asynchronous operation which takes time to execute, and uses firebase::Future to return its result.

Details
Parameters	values The paths to update, and their new child values. A value of type Null will delete that particular child.
Returns	A Future result, which will complete when the operation either succeeds or fails. When the Future is completed, if its Error is kErrorNone, the operation succeeded.

UpdateChildrenLastResult

Future< void > UpdateChildrenLastResult()

Gets the result of the most recent call to either version of UpdateChildren().

Details
Returns	Result of the most recent call to UpdateChildren().

database

Database * database() const 

Gets the database to which we refer.

The pointer will remain valid indefinitely.

Details
Returns	Firebase Database instance that this DatabaseReference refers to.

is_root

bool is_root() const 

Returns true if this reference refers to the root of the database.

Details
Returns	true if this reference refers to the root of the database, false otherwise.

is_valid

virtual bool is_valid() const override

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

DatabaseReferences constructed with the default constructor are considered invalid. An invalid reference could be returned by Database::GetReference() or Database::GetReferenceFromUrl() if you specify an incorrect location, or calling Query::GetReference() on an invalid query.

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

key

const char * key() const 

Gets the string key of this database location.

The pointer is only valid while the DatabaseReference remains in memory.

Details
Returns	String key of this database location, which will remain valid in memory until the DatabaseReference itself goes away.

key_string

std::string key_string() const 

Gets the string key of this database location.

Details
Returns	String key of this database location.

operator=

DatabaseReference & operator=(
  const DatabaseReference & reference
)

Copy assignment operator.

It's totally okay (and efficient) to copy DatabaseReference instances, as they simply point to the same location in the database.

Details
Parameters	reference DatabaseReference to copy from.
Returns	Reference to the destination DatabaseReference.

operator=

DatabaseReference & operator=(
  DatabaseReference && reference
)

Move assignment operator.

Moving is an efficient operation for DatabaseReference instances.

Details
Parameters	reference DatabaseReference to move data from.
Returns	Reference to the destination DatabaseReference.

url

std::string url() const 

Get the absolute URL of this reference.

Details
Returns	The absolute URL of the location this reference refers to.

~DatabaseReference

virtual  ~DatabaseReference()

Required virtual destructor.