Firebase Class Reference

Overview

A Firebase reference represents a particular location in your Firebase database and can be used for reading or writing data to that Firebase database location.

This class is the starting point for all Firebase operations. After you’ve initialized it with initWithUrl: you can use it to read data (ie. observeEventType:withBlock:), write data (ie. setValue:), and to create new Firebase references (ie. child:).

Discussion

Declared In

Getting references to children locations

Get a Firebase reference for the database location at the specified relative path. The relative path can either be a simple child key (e.g. ‘fred’) or a deeper slash-separated path (e.g. ‘fred/name/first’).

- (Firebase *)childByAppendingPath:(NSString *)pathString

Parameters

pathString

A relative path from this location to the desired child location.

Return Value

A Firebase reference for the specified relative path.

Discussion

Get a Firebase reference for the database location at the specified relative path. The relative path can either be a simple child key (e.g. ‘fred’) or a deeper slash-separated path (e.g. ‘fred/name/first’).

Discussion

Declared In

Set a priority for the data at this Firebase database location. Priorities can be used to provide a custom ordering for the children at a location (if no priorities are specified, the children are ordered by key).

- (void)setPriority:(id)priority

Parameters

priority

The priority to set at the specified location.

Discussion

Set a priority for the data at this Firebase database location. Priorities can be used to provide a custom ordering for the children at a location (if no priorities are specified, the children are ordered by key).

You cannot set a priority on an empty location. For this reason setValue:andPriority: should be used when setting initial data with a specific priority and setPriority: should be used when updating the priority of existing data.

Children are sorted based on this priority using the following rules:

Children with no priority come first. Children with a number as their priority come next. They are sorted numerically by priority (small to large). Children with a string as their priority come last. They are sorted lexicographically by priority. Whenever two children have the same priority (including no priority), they are sorted by key. Numeric keys come first (sorted numerically), followed by the remaining keys (sorted lexicographically).

Note that priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are treated as numbers only when they can be parsed as a 32-bit integer.

Supported events types for all realtime observers are specified in FEventType as:

typedef NS_ENUM(NSInteger, FEventType) {
FEventTypeChildAdded, // 0, fired when a new child node is added to a location
FEventTypeChildRemoved, // 1, fired when a child node is removed from a location
FEventTypeChildChanged, // 2, fired when a child node at a location changes
FEventTypeChildMoved, // 3, fired when a child node moves relative to the other child nodes at a location
FEventTypeValue // 4, fired when any data changes at a location and, recursively, any children
};

Declared In

observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Return Value

Discussion

observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Declared In

observeEventType:withBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes.

Return Value

Discussion

observeEventType:withBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes.

The cancelBlock will be called if you will no longer receive new events due to no longer having permission.

Declared In

observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Return Value

Discussion

observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. This is the primary way to read data from a Firebase database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

The cancelBlock will be called if you will no longer receive new events due to no longer having permission.

Declared In

This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Parameters

eventType

The type of event to listen for.

block

The block that should be called with initial data and updates as a FDataSnapshot, as well as the previous child’s key.

Discussion

This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Declared In

This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

Parameters

The block that should be called with initial data and updates as a FDataSnapshot, as well as the previous child’s key.

cancelBlock

The block that will be called if you don’t have permission to access this data.

Discussion

This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FEventTypeChildAdded, FEventTypeChildMoved, and FEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

The cancelBlock will be called if you do not have permission to read data at this location.

Discussion

Declared In

By calling keepSynced:YES on a location, the data for that location will automatically be downloaded and kept in sync, even when no listeners are attached for that location. Additionally, while a location is kept synced, it will not be evicted from the persistent disk cache.

- (void)keepSynced:(BOOL)keepSynced

Parameters

keepSynced

Pass YES to keep this location synchronized, pass NO to stop synchronization.

Discussion

By calling keepSynced:YES on a location, the data for that location will automatically be downloaded and kept in sync, even when no listeners are attached for that location. Additionally, while a location is kept synced, it will not be evicted from the persistent disk cache.

Discussion

queryStartingAtPriority: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtPriority: will respond to events at nodes with a priority greater than or equal to startPriority.

Discussion

queryStartingAtPriority:andChildName: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtPriority:andChildName will respond to events at nodes with a priority greater than startPriority, or equal to startPriority and with a name greater than or equal to childName.

Discussion

queryEndingAtPriority: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtPriority: will respond to events at nodes with a priority less than or equal to startPriority and with a name greater than or equal to childName.

Discussion

queryEndingAtPriority:andChildName: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtPriority:andChildName will respond to events at nodes with a priority less than endPriority, or equal to endPriority and with a name less than or equal to childName.

Discussion

queryEqualToPriority: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToPriority: will respond to events at nodes with a priority equal to supplied argument.

Parameters

Return Value

An FQuery instance, limited to data with the supplied priority and the name.

Discussion

This method is deprecated in favor of using queryEqualAtValue:childKey:. This can be used with queryOrderedByPriority to query by priority.

queryEqualToPriority:andChildName: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToPriority:andChildName will respond to events at nodes with a priority equal to the supplied argument with a name equal to childName. There will be at most one node that matches because child names are unique.

Parameters

Return Value

Discussion

This method is deprecated in favor of using queryLimitedToFirst:limit or queryLimitedToLast:limit instead.

queryLimitedToNumberOfChildren: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryLimitedToNumberOfChildren: will respond to events from at most limit child nodes.

Declared In

queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes.

- (FQuery *)queryLimitedToFirst:(NSUInteger)limit

Parameters

limit

The upper bound, inclusive, for the number of child nodes to receive events for.

Return Value

Discussion

queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes.

Declared In

queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes.

- (FQuery *)queryLimitedToLast:(NSUInteger)limit

Parameters

limit

The upper bound, inclusive, for the number of child nodes to receive events for.

Return Value

Discussion

queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes.

Declared In

queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value greater than or equal to startValue.

- (FQuery *)queryStartingAtValue:(id)startValue

Parameters

startValue

The lower bound, inclusive, for the value of data visible to the returned FQuery

Return Value

An FQuery instance, limited to data with value greater than or equal to startValue

Discussion

queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value greater than or equal to startValue.

Declared In

queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtValue:childKey will respond to events at nodes with a value greater than startValue, or equal to startValue and with a key greater than or equal to childKey.

Parameters

The lower bound, inclusive, for the value of data visible to the returned FQuery

childKey

The lower bound, inclusive, for the key of nodes with value equal to startValue.

Return Value

An FQuery instance, limited to data with value greater than or equal to startValue.

Discussion

queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryStartingAtValue:childKey will respond to events at nodes with a value greater than startValue, or equal to startValue and with a key greater than or equal to childKey.

Declared In

queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value less than or equal to endValue.

- (FQuery *)queryEndingAtValue:(id)endValue

Parameters

endValue

The upper bound, inclusive, for the value of data visible to the returned FQuery

Return Value

An FQuery instance, limited to data with value less than or equal to endValue.

Discussion

queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value less than or equal to endValue.

Declared In

queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtValue:childKey will respond to events at nodes with a value less than endValue, or equal to endValue and with a key less than or equal to childKey.

Parameters

The upper bound, inclusive, for the value of data visible to the returned FQuery

childKey

The upper bound, inclusive, for the key of nodes with value equal to endValue.

Return Value

An FQuery instance, limited to data with value less than or equal to endValue.

Discussion

queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEndingAtValue:childKey will respond to events at nodes with a value less than endValue, or equal to endValue and with a key less than or equal to childKey.

Declared In

queryEqualToValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal to the supplied argument.

- (FQuery *)queryEqualToValue:(id)value

Parameters

Return Value

An Fquery instance, limited to data with the supplied value.

Discussion

queryEqualToValue: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal to the supplied argument.

Declared In

queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value equal to the supplied argument with a name equal to childKey. There will be at most one node that matches because child keys are unique.

Parameters

Return Value

An FQuery instance, limited to data with the supplied value and the key.

Discussion

queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. The FQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value equal to the supplied argument with a name equal to childKey. There will be at most one node that matches because child keys are unique.

Declared In

Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:

- (void)cancelDisconnectOperations

Discussion

Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:

Declared In

Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:

Parameters

block

A block that will be triggered once the Firebase database has acknowledged the cancel request.

Discussion

Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:

Parameters

Return Value

Discussion

Observer block will be triggered whenever a user gets authenticated or logged out.

Authentication data is persisted across app restarts. If your have an old authentication, Firebase will attempt to resume your old session. This approach does not wait for a server roundtrip. Rather, it inspects the contents of the persisted JWT and assumes that the Firebase secret used to generate the token has not been revoked.

In the event that the Firebase secret used to generate the token has been revoked, observers will likely see one flicker / rapid flip-flop of authentication state once the server rejects the token.

Declared In

Used to create a new user account with the given email and password combo. The results will be passed to the given block. Note that this method will not log the new user in. On success, invokes the result block with an dictionary of user data, including the user id.

Parameters

email

The email for the account to be created.

password

The password for the account to be created.

block

The block to be called with the results of the operation.

Discussion

Used to create a new user account with the given email and password combo. The results will be passed to the given block. Note that this method will not log the new user in. On success, invokes the result block with an dictionary of user data, including the user id.

Discussion

Authenticate to this Firebase app using the provided credentials. The completion block will be called with the results of the authenticated attempt, and the cancelBlock will be called if the credentials become invalid at some point after authentication has succeeded.

Declared In

Manual Connection Management

Manually disconnect the Firebase client from the database and disable automatic reconnection.

+ (void)goOffline

Discussion

Manually disconnect the Firebase client from the database and disable automatic reconnection.

The Firebase client automatically maintains a persistent connection to the Firebase server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline( ) and goOnline( ) methods may be used to manually control the client connection in cases where a persistent connection is undesirable.

While offline, the Firebase client will no longer receive data updates from the database. However, all Firebase operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Firebase server.

To reconnect to the Firebase server and begin receiving remote events, see goOnline( ). Once the connection is reestablished, the Firebase client will transmit the appropriate data and fire the appropriate events so that your client “catches up” automatically.

Declared In

Manually reestablish a connection to the Firebase database and enable automatic reconnection.

+ (void)goOnline

Discussion

Manually reestablish a connection to the Firebase database and enable automatic reconnection.

The Firebase client automatically maintains a persistent connection to the Firebase server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline( ) and goOnline( ) methods may be used to manually control the client connection in cases where a persistent connection is undesirable.

This method should be used after invoking goOffline( ) to disable the active connection. Once reconnected, the Firebase client will automatically transmit the proper data and fire the appropriate events so that your client “catches up” automatically.

Declared In

Transactions

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

Parameters

block

This block receives the current data at this location and must return an instance of FTransactionResult

Discussion

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

Declared In

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

Parameters

block

This block receives the current data at this location and must return an instance of FTransactionResult

completionBlock

This block will be triggered once the transaction is complete, whether it was successful or not. It will indicate if there was an error, whether or not the data was committed, and what the current value of the data at this location is.

Discussion

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

Declared In

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

Parameters

block

This block receives the current data at this location and must return an instance of FTransactionResult

completionBlock

This block will be triggered once the transaction is complete, whether it was successful or not. It will indicate if there was an error, whether or not the data was committed, and what the current value of the data at this location is.

localEvents

Set this to NO to suppress events raised for intermediate states, and only get events based on the final state of the transaction.

Discussion

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with an FMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FTransactionResult with the new data.

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

Since your block may be run multiple times, this client could see several immediate states that don’t exist on the server. You can suppress those immediate states until the server confirms the final state of the transaction.