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
Gets a reference to a location relative to this one.
Child(const std::string & path) const
Gets a reference to a location relative to this one.
GetDatabase() const
FIREBASE_DEPRECATED Database *
Deprecated. Renamed to database().
Gets the database to which we refer.
GetKey() const
FIREBASE_DEPRECATED const char *
Gets the string key of this database location.
GetKeyString() const
FIREBASE_DEPRECATED std::string
Deprecated. Renamed to key_string().
Gets the string key of this database location.
GetParent() const
Gets the parent of this location, or get this location again if IsRoot().
GetRoot() const
Gets the root of the database.
GetUrl() const
FIREBASE_DEPRECATED std::string
Deprecated. Renamed to url().
Get the absolute URL of this reference.
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.
IsRoot() const
FIREBASE_DEPRECATED bool
Deprecated. Renamed to is_root().
Returns true if this reference refers to the root of the database.
IsValid() const
virtual FIREBASE_DEPRECATED bool
Deprecated. Renamed to is_valid().
Returns true if this reference is valid, false if it is not valid.
OnDisconnect()
Get the disconnect handler, which controls what actions the server will perform to this location's data when this client disconnects.
PushChild() const
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(DoTransaction *transaction_function, bool trigger_local_events)
Run a user-supplied callback function, possibly multiple times, to perform an atomic transaction on the database.
RunTransactionLastResult()
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
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
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)
Copy assignment operator.
operator=(DatabaseReference && reference)
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.

GetDatabase

FIREBASE_DEPRECATED Database * GetDatabase() const 

Gets the database to which we refer.

The pointer will remain valid indefinitely.

Deprecated. Renamed to database().

Details
Returns
Firebase Database instance that this DatabaseReference refers to.

GetKey

FIREBASE_DEPRECATED const char * GetKey() 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.

GetKeyString

FIREBASE_DEPRECATED std::string GetKeyString() const 

Gets the string key of this database location.

Deprecated. Renamed to key_string().

Details
Returns
String key of this database location.

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.

GetUrl

FIREBASE_DEPRECATED std::string GetUrl() const 

Get the absolute URL of this reference.

Deprecated. Renamed to url().

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

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.

IsRoot

FIREBASE_DEPRECATED bool IsRoot() const 

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

Deprecated. Renamed to is_root().

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

IsValid

virtual FIREBASE_DEPRECATED bool IsValid() const 

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

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.

Deprecated. Renamed to is_valid().

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

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(
  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. param[in] transaction_function The user-supplied function that will be called, possibly multiple times, to perform the database transaction. param[in] fire_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.

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

Details
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.