firebase:: database:: DatabaseReference
#include <database_reference.h>
DatabaseReference represents a particular location in yourDatabase and can be used for reading or writing data to thatDatabase location.
Summary
This class is the starting point for allDatabase operations. After you've initialized it with a URL, you can use it to read data, write data, and to create newDatabaseReference instances.
Inheritance
Inherits from:firebase::database::QueryConstructors and Destructors | |
|---|---|
DatabaseReference()Default constructor. | |
DatabaseReference(constDatabaseReference & 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. |
GetParent() const | Gets the parent of this location, or get this location again if IsRoot(). |
GetRoot() const | Gets the root of the database. |
GoOffline() | voidManually disconnect Firebase RealtimeDatabase from the server, and disable automatic reconnection. |
GoOnline() | voidManually reestablish connection to the Firebase RealtimeDatabase server and enable automatic reconnection. |
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 toRemoveValue();. |
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. |
RunTransaction(DoTransactionFunction transaction_function, bool trigger_local_events) | Run a user-supplied callback, possibly multiple times, to perform an atomic transaction on the database. |
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 toRunTransaction(). |
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 toSetPriority(). |
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 toSetValueAndPriority(). |
SetValueLastResult() | Future< void >Gets the result of the most recent call toSetValue(). |
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 ofUpdateChildren(). |
database() const | Database *Gets the database to which we refer. |
is_root() const | boolReturns true if this reference refers to the root of the database. |
is_valid() const override | virtual boolReturns 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::stringGets the string key of this database location. |
operator=(constDatabaseReference & reference) | Copy assignment operator. |
operator=(DatabaseReference && reference) | Move assignment operator. |
url() const | std::stringGet the absolute URL of this reference. |
Public functions
Child
DatabaseReferenceChild(constchar*path)const
Gets a reference to a location relative to this one.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns | Child relative to this location. |
Child
DatabaseReferenceChild(conststd::string&path)const
Gets a reference to a location relative to this one.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns | Child relative to this location. |
DatabaseReference
DatabaseReference()
Default constructor.
This creates an invalidDatabaseReference. Attempting to perform any operations on this reference will fail unless a validDatabaseReference has been assigned to it.
DatabaseReference
DatabaseReference(constDatabaseReference&reference)
Copy constructor.
It's totally okay (and efficient) to copyDatabaseReference instances, as they simply point to the same location in the database.
| Details | |||
|---|---|---|---|
| Parameters |
|
DatabaseReference
DatabaseReference(DatabaseReference&&reference)
Move constructor.
Moving is an efficient operation forDatabaseReference instances.
| Details | |||
|---|---|---|---|
| Parameters |
|
GetParent
DatabaseReferenceGetParent()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
DatabaseReferenceGetRoot()const
Gets the root of the database.
| Details | |
|---|---|
| Returns | Root of the database. |
GoOffline
voidGoOffline()
Manually disconnect Firebase RealtimeDatabase from the server, and disable automatic reconnection.
This will affect all other instances ofDatabaseReference as well.
GoOnline
voidGoOnline()
Manually reestablish connection to the Firebase RealtimeDatabase server and enable automatic reconnection.
This will affect all other instances ofDatabaseReference 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
DatabaseReferencePushChild()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 usesfirebase::Future to return its result.
Note: Only oneRemoveValue() should be running on a given database location at the same time. If you need to run multiple operations at once, useRunTransaction().
| Details | |
|---|---|
| Returns |
RemoveValueLastResult
Future<void>RemoveValueLastResult()
Gets the result of the most recent call toRemoveValue();.
| Details | |
|---|---|
| Returns | Result of the most recent call toRemoveValue(). |
RunTransaction
Future<DataSnapshot>RunTransaction(DoTransactionWithContexttransaction_function,void*context,booltrigger_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 oneRunTransaction() should be running on a given database location at the same time.
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
| ||||||
| Returns | AFuture result, which will complete when the transaction either succeeds or fails. When theFuture 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 theDataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned inDataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set andDataSnapshot will be invalid. |
RunTransaction
Future<DataSnapshot>RunTransaction(DoTransactionFunctiontransaction_function,booltrigger_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 oneRunTransaction() 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 |
| ||||
| Returns | AFuture result, which will complete when the transaction either succeeds or fails. When theFuture 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 theDataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned inDataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set andDataSnapshot will be invalid. |
RunTransaction
Future<DataSnapshot>RunTransaction(DoTransactiontransaction_function,booltrigger_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 oneRunTransaction() 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 |
| ||||
| Returns | AFuture result, which will complete when the transaction either succeeds or fails. When theFuture 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 theDataSnapshot result. If the Error is kErrorTransactionAbortedByUser, the transaction was aborted because the transaction function returned kTransactionResultAbort, and the old value will be returned inDataSnapshot. Otherwise, if some other error occurred, Error and ErrorMessage will be set andDataSnapshot will be invalid. |
RunTransactionLastResult
Future<DataSnapshot>RunTransactionLastResult()
Get the result of the most recent call toRunTransaction().
| Details | |
|---|---|
| Returns | Results of the most recent call toRunTransaction(). |
SetPriority
Future<void>SetPriority(Variantpriority)
Sets the priority of this field, which controls its sort order relative to its siblings.
In Firebase, children are sorted in the following order:
- First, children with no priority.
- Then, children with numerical priority, sorted numerically in ascending order.
- 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 usesfirebase::Future to return its result.
Note: Only oneSetPriority() should be running on a given database location at the same time. If you need to run multiple operations at once, useRunTransaction().
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns |
SetPriorityLastResult
Future<void>SetPriorityLastResult()
Gets the result of the most recent call toSetPriority().
| Details | |
|---|---|
| Returns | Result of the most recent call toSetPriority(). |
SetValue
Future<void>SetValue(Variantvalue)
Sets the data at this location to the given value.
This is an asynchronous operation which takes time to execute, and usesfirebase::Future to return its result.
Note: Only oneSetValue() should be running on a given database location at the same time. If you need to run multiple operations at once, useRunTransaction().
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns |
SetValueAndPriority
Future<void>SetValueAndPriority(Variantvalue,Variantpriority)
Sets both the data and priority of this location.
SeeSetValue() andSetPriority() for context on the parameters.
This is an asynchronous operation which takes time to execute, and usesfirebase::Future to return its result.
Note: Only oneSetValueAndPriority() 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 eitherSetValue() orSetPriority(), and will return kErrorConflictingOperationInProgress if you try. If you need to run multiple operations at once, useRunTransaction().
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
| ||||
| Returns |
SetValueAndPriorityLastResult
Future<void>SetValueAndPriorityLastResult()
Get the result of the most recent call toSetValueAndPriority().
| Details | |
|---|---|
| Returns | Result of the most recent call toSetValueAndPriority(). |
SetValueLastResult
Future<void>SetValueLastResult()
Gets the result of the most recent call toSetValue().
| Details | |
|---|---|
| Returns | Result of the most recent call toSetValue(). |
UpdateChildren
Future<void>UpdateChildren(Variantvalues)
Updates the specified child keys to the given values.
Note: This method will return kErrorConflictingOperationInProgress if it is run at the same time asSetValue(),SetValueAndPriority(), orRemoveValue() in the same location.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns |
UpdateChildren
Future<void>UpdateChildren(conststd::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 usesfirebase::Future to return its result.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns |
UpdateChildrenLastResult
Future<void>UpdateChildrenLastResult()
Gets the result of the most recent call to either version ofUpdateChildren().
| Details | |
|---|---|
| Returns | Result of the most recent call toUpdateChildren(). |
database
Database*database()const
Gets the database to which we refer.
The pointer will remain valid indefinitely.
| Details | |
|---|---|
| Returns | FirebaseDatabase instance that thisDatabaseReference refers to. |
is_root
boolis_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
virtualboolis_valid()constoverride
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 byDatabase::GetReference() orDatabase::GetReferenceFromUrl() if you specify an incorrect location, or callingQuery::GetReference() on an invalid query.
| Details | |
|---|---|
| Returns | true if this reference is valid, false if this reference is invalid. |
key
constchar*key()const
Gets the string key of this database location.
The pointer is only valid while theDatabaseReference remains in memory.
| Details | |
|---|---|
| Returns | String key of this database location, which will remain valid in memory until theDatabaseReference itself goes away. |
key_string
std::stringkey_string()const
Gets the string key of this database location.
| Details | |
|---|---|
| Returns | String key of this database location. |
operator=
DatabaseReference&operator=(constDatabaseReference&reference)
Copy assignment operator.
It's totally okay (and efficient) to copyDatabaseReference instances, as they simply point to the same location in the database.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns | Reference to the destinationDatabaseReference. |
operator=
DatabaseReference&operator=(DatabaseReference&&reference)
Move assignment operator.
Moving is an efficient operation forDatabaseReference instances.
| Details | |||
|---|---|---|---|
| Parameters |
| ||
| Returns | Reference to the destinationDatabaseReference. |
url
std::stringurl()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.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-01-23 UTC.