From c33bdff405b988ffa4e894809db73ade0f21e658 Mon Sep 17 00:00:00 2001 From: Paul Beusterien Date: Thu, 29 Jun 2017 12:03:45 -0700 Subject: Group public headers into Public directories (#112) --- Firebase/Database/Api/FIRDataEventType.h | 39 -- Firebase/Database/Api/FIRDataSnapshot.h | 148 ----- Firebase/Database/Api/FIRDatabase.h | 148 ----- Firebase/Database/Api/FIRDatabaseQuery.h | 315 --------- .../Database/Api/FIRDatabaseSwiftNameSupport.h | 29 - Firebase/Database/Api/FIRMutableData.h | 130 ---- Firebase/Database/Api/FIRServerValue.h | 35 - Firebase/Database/Api/FIRTransactionResult.h | 47 -- Firebase/Database/Api/FirebaseDatabase.h | 29 - Firebase/Database/FIRDatabaseReference.h | 719 --------------------- Firebase/Database/FirebaseDatabase.podspec | 12 +- Firebase/Database/Public/FIRDataEventType.h | 39 ++ Firebase/Database/Public/FIRDataSnapshot.h | 148 +++++ Firebase/Database/Public/FIRDatabase.h | 148 +++++ Firebase/Database/Public/FIRDatabaseQuery.h | 315 +++++++++ Firebase/Database/Public/FIRDatabaseReference.h | 719 +++++++++++++++++++++ .../Database/Public/FIRDatabaseSwiftNameSupport.h | 29 + Firebase/Database/Public/FIRMutableData.h | 130 ++++ Firebase/Database/Public/FIRServerValue.h | 35 + Firebase/Database/Public/FIRTransactionResult.h | 47 ++ Firebase/Database/Public/FirebaseDatabase.h | 29 + 21 files changed, 1640 insertions(+), 1650 deletions(-) delete mode 100644 Firebase/Database/Api/FIRDataEventType.h delete mode 100644 Firebase/Database/Api/FIRDataSnapshot.h delete mode 100644 Firebase/Database/Api/FIRDatabase.h delete mode 100644 Firebase/Database/Api/FIRDatabaseQuery.h delete mode 100644 Firebase/Database/Api/FIRDatabaseSwiftNameSupport.h delete mode 100644 Firebase/Database/Api/FIRMutableData.h delete mode 100644 Firebase/Database/Api/FIRServerValue.h delete mode 100644 Firebase/Database/Api/FIRTransactionResult.h delete mode 100644 Firebase/Database/Api/FirebaseDatabase.h delete mode 100644 Firebase/Database/FIRDatabaseReference.h create mode 100644 Firebase/Database/Public/FIRDataEventType.h create mode 100644 Firebase/Database/Public/FIRDataSnapshot.h create mode 100644 Firebase/Database/Public/FIRDatabase.h create mode 100644 Firebase/Database/Public/FIRDatabaseQuery.h create mode 100644 Firebase/Database/Public/FIRDatabaseReference.h create mode 100644 Firebase/Database/Public/FIRDatabaseSwiftNameSupport.h create mode 100644 Firebase/Database/Public/FIRMutableData.h create mode 100644 Firebase/Database/Public/FIRServerValue.h create mode 100644 Firebase/Database/Public/FIRTransactionResult.h create mode 100644 Firebase/Database/Public/FirebaseDatabase.h (limited to 'Firebase/Database') diff --git a/Firebase/Database/Api/FIRDataEventType.h b/Firebase/Database/Api/FIRDataEventType.h deleted file mode 100644 index fccc98a..0000000 --- a/Firebase/Database/Api/FIRDataEventType.h +++ /dev/null @@ -1,39 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#ifndef Firebase_FIRDataEventType_h -#define Firebase_FIRDataEventType_h - -#import -#import "FIRDatabaseSwiftNameSupport.h" - -/** - * This enum is the set of events that you can observe at a Firebase Database location. - */ -typedef NS_ENUM(NSInteger, FIRDataEventType) { - /// A new child node is added to a location. - FIRDataEventTypeChildAdded, - /// A child node is removed from a location. - FIRDataEventTypeChildRemoved, - /// A child node at a location changes. - FIRDataEventTypeChildChanged, - /// A child node moves relative to the other child nodes at a location. - FIRDataEventTypeChildMoved, - /// Any data changes at a location or, recursively, at any child node. - FIRDataEventTypeValue -} FIR_SWIFT_NAME(DataEventType); - -#endif diff --git a/Firebase/Database/Api/FIRDataSnapshot.h b/Firebase/Database/Api/FIRDataSnapshot.h deleted file mode 100644 index e615260..0000000 --- a/Firebase/Database/Api/FIRDataSnapshot.h +++ /dev/null @@ -1,148 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseSwiftNameSupport.h" - -NS_ASSUME_NONNULL_BEGIN - -@class FIRDatabaseReference; - -/** - * A FIRDataSnapshot contains data from a Firebase Database location. Any time you read - * Firebase data, you receive the data as a FIRDataSnapshot. - * - * FIRDataSnapshots are passed to the blocks you attach with observeEventType:withBlock: or observeSingleEvent:withBlock:. - * They are efficiently-generated immutable copies of the data at a Firebase Database location. - * They can't be modified and will never change. To modify data at a location, - * use a FIRDatabaseReference (e.g. with setValue:). - */ -FIR_SWIFT_NAME(DataSnapshot) -@interface FIRDataSnapshot : NSObject - - -#pragma mark - Navigating and inspecting a snapshot - -/** - * Gets a FIRDataSnapshot for the 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'). If the child - * location has no data, an empty FIRDataSnapshot is returned. - * - * @param childPathString A relative path to the location of child data. - * @return The FIRDataSnapshot for the child location. - */ -- (FIRDataSnapshot *)childSnapshotForPath:(NSString *)childPathString; - - -/** - * Return YES if the specified child exists. - * - * @param childPathString A relative path to the location of a potential child. - * @return YES if data exists at the specified childPathString, else NO. - */ -- (BOOL) hasChild:(NSString *)childPathString; - - -/** - * Return YES if the DataSnapshot has any children. - * - * @return YES if this snapshot has any children, else NO. - */ -- (BOOL) hasChildren; - - -/** - * Return YES if the DataSnapshot contains a non-null value. - * - * @return YES if this snapshot contains a non-null value, else NO. - */ -- (BOOL) exists; - - -#pragma mark - Data export - -/** - * Returns the raw value at this location, coupled with any metadata, such as priority. - * - * Priorities, where they exist, are accessible under the ".priority" key in instances of NSDictionary. - * For leaf locations with priorities, the value will be under the ".value" key. - */ -- (id __nullable) valueInExportFormat; - - -#pragma mark - Properties - -/** - * Returns the contents of this data snapshot as native types. - * - * Data types returned: - * + NSDictionary - * + NSArray - * + NSNumber (also includes booleans) - * + NSString - * - * @return The data as a native object. - */ -@property (strong, readonly, nonatomic, nullable) id value; - - -/** - * Gets the number of children for this DataSnapshot. - * - * @return An integer indicating the number of children. - */ -@property (readonly, nonatomic) NSUInteger childrenCount; - - -/** - * Gets a FIRDatabaseReference for the location that this data came from. - * - * @return A FIRDatabaseReference instance for the location of this data. - */ -@property (nonatomic, readonly, strong) FIRDatabaseReference * ref; - - -/** - * The key of the location that generated this FIRDataSnapshot. - * - * @return An NSString containing the key for the location of this FIRDataSnapshot. - */ -@property (strong, readonly, nonatomic) NSString* key; - - -/** - * An iterator for snapshots of the child nodes in this snapshot. - * You can use the native for..in syntax: - * - * for (FIRDataSnapshot* child in snapshot.children) { - * ... - * } - * - * @return An NSEnumerator of the children. - */ -@property (strong, readonly, nonatomic) NSEnumerator* children; - -/** - * The priority of the data in this FIRDataSnapshot. - * - * @return The priority as a string, or nil if no priority was set. - */ -@property (strong, readonly, nonatomic, nullable) id priority; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FIRDatabase.h b/Firebase/Database/Api/FIRDatabase.h deleted file mode 100644 index ebdbf8a..0000000 --- a/Firebase/Database/Api/FIRDatabase.h +++ /dev/null @@ -1,148 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseReference.h" -#import "FIRDatabaseSwiftNameSupport.h" - -@class FIRApp; - -NS_ASSUME_NONNULL_BEGIN - -/** - * The entry point for accessing a Firebase Database. You can get an instance by calling - * [FIRDatabase database]. To access a location in the database and read or write data, - * use [FIRDatabase reference]. - */ -FIR_SWIFT_NAME(Database) -@interface FIRDatabase : NSObject - -/** - * The NSObject initializer that has been marked as unavailable. Use the `database` - * method instead - * - * @return An instancetype instance -*/ -+ (instancetype) init __attribute__((unavailable("use the database method instead"))); - -/** - * Gets the instance of FIRDatabase for the default FIRApp. - * - * @return A FIRDatabase instance. - */ -+ (FIRDatabase *) database FIR_SWIFT_NAME(database()); - -/** - * Gets an instance of FIRDatabase for a specific FIRApp. - * - * @param app The FIRApp to get a FIRDatabase for. - * @return A FIRDatabase instance. - */ -+ (FIRDatabase *) databaseForApp:(FIRApp*)app FIR_SWIFT_NAME(database(app:)); - -/** The FIRApp instance to which this FIRDatabase belongs. */ -@property (weak, readonly, nonatomic) FIRApp *app; - -/** - * Gets a FIRDatabaseReference for the root of your Firebase Database. - */ -- (FIRDatabaseReference *) reference; - -/** - * Gets a FIRDatabaseReference for the provided path. - * - * @param path Path to a location in your Firebase Database. - * @return A FIRDatabaseReference pointing to the specified path. - */ -- (FIRDatabaseReference *) referenceWithPath:(NSString *)path; - -/** - * Gets a FIRDatabaseReference for the provided URL. The URL must be a URL to a path - * within this Firebase Database. To create a FIRDatabaseReference to a different database, - * create a FIRApp} with a FIROptions object configured with the appropriate database URL. - * - * @param databaseUrl A URL to a path within your database. - * @return A FIRDatabaseReference for the provided URL. -*/ -- (FIRDatabaseReference *) referenceFromURL:(NSString *)databaseUrl; - -/** - * The Firebase Database client automatically queues writes and sends them to the server at the earliest opportunity, - * depending on network connectivity. In some cases (e.g. offline usage) there may be a large number of writes - * waiting to be sent. Calling this method will purge all outstanding writes so they are abandoned. - * - * All writes will be purged, including transactions and onDisconnect writes. The writes will - * be rolled back locally, perhaps triggering events for affected event listeners, and the client will not - * (re-)send them to the Firebase Database backend. - */ -- (void)purgeOutstandingWrites; - -/** - * Shuts down our connection to the Firebase Database backend until goOnline is called. - */ -- (void)goOffline; - -/** - * Resumes our connection to the Firebase Database backend after a previous goOffline call. - */ -- (void)goOnline; - -/** - * The Firebase Database client will cache synchronized data and keep track of all writes you've - * initiated while your application is running. It seamlessly handles intermittent network - * connections and re-sends write operations when the network connection is restored. - * - * However by default your write operations and cached data are only stored in-memory and will - * be lost when your app restarts. By setting this value to `YES`, the data will be persisted - * to on-device (disk) storage and will thus be available again when the app is restarted - * (even when there is no network connectivity at that time). Note that this property must be - * set before creating your first Database reference and only needs to be called once per - * application. - * - */ -@property (nonatomic) BOOL persistenceEnabled FIR_SWIFT_NAME(isPersistenceEnabled); - -/** - * By default the Firebase Database client will use up to 10MB of disk space to cache data. If the cache grows beyond - * this size, the client will start removing data that hasn't been recently used. If you find that your application - * caches too little or too much data, call this method to change the cache size. This property must be set before - * creating your first FIRDatabaseReference and only needs to be called once per application. - * - * Note that the specified cache size is only an approximation and the size on disk may temporarily exceed it - * at times. Cache sizes smaller than 1 MB or greater than 100 MB are not supported. - */ -@property (nonatomic) NSUInteger persistenceCacheSizeBytes; - -/** - * Sets the dispatch queue on which all events are raised. The default queue is the main queue. - * - * Note that this must be set before creating your first Database reference. - */ -@property (nonatomic, strong) dispatch_queue_t callbackQueue; - -/** - * Enables verbose diagnostic logging. - * - * @param enabled YES to enable logging, NO to disable. - */ -+ (void) setLoggingEnabled:(BOOL)enabled; - -/** Retrieve the Firebase Database SDK version. */ -+ (NSString *) sdkVersion; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FIRDatabaseQuery.h b/Firebase/Database/Api/FIRDatabaseQuery.h deleted file mode 100644 index be4ad27..0000000 --- a/Firebase/Database/Api/FIRDatabaseQuery.h +++ /dev/null @@ -1,315 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseSwiftNameSupport.h" -#import "FIRDataEventType.h" -#import "FIRDataSnapshot.h" - -NS_ASSUME_NONNULL_BEGIN - -/** - * A FIRDatabaseHandle is used to identify listeners of Firebase Database events. These handles - * are returned by observeEventType: and and can later be passed to removeObserverWithHandle: to - * stop receiving updates. - */ -typedef NSUInteger FIRDatabaseHandle FIR_SWIFT_NAME(DatabaseHandle); - -/** - * A FIRDatabaseQuery instance represents a query over the data at a particular location. - * - * You create one by calling one of the query methods (queryOrderedByChild:, queryStartingAtValue:, etc.) - * on a FIRDatabaseReference. The query methods can be chained to further specify the data you are interested in - * observing - */ -FIR_SWIFT_NAME(DatabaseQuery) -@interface FIRDatabaseQuery : NSObject - - -#pragma mark - Attach observers to read data - -/** - * observeEventType:withBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; - - -/** - * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot - * and the previous child's key. - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; - - -/** - * observeEventType:withBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the 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. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. - * @param cancelBlock The block that should be called if this client no longer has permission to receive these events - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged 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. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot - * and the previous child's key. - * @param cancelBlock The block that should be called if this client no longer has permission to receive these events - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. - * - * The cancelBlock will be called if you do not have permission to read data at this location. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. - * @param cancelBlock The block that will be called if you don't have permission to access this data - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged 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. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. - * @param cancelBlock The block that will be called if you don't have permission to access this data - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -#pragma mark - Detaching observers - -/** - * Detach a block previously attached with observeEventType:withBlock:. - * - * @param handle The handle returned by the call to observeEventType:withBlock: which we are trying to remove. - */ -- (void) removeObserverWithHandle:(FIRDatabaseHandle)handle; - - -/** - * Detach all blocks previously attached to this Firebase Database location with observeEventType:withBlock: - */ -- (void) removeAllObservers; - -/** - * 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. - * - * @param keepSynced Pass YES to keep this location synchronized, pass NO to stop synchronization. -*/ - - (void) keepSynced:(BOOL)keepSynced; - - -#pragma mark - Querying and limiting - -/** -* queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. -* The FIRDatabaseQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes. -* -* @param limit The upper bound, inclusive, for the number of child nodes to receive events for -* @return A FIRDatabaseQuery instance, limited to at most limit child nodes. -*/ -- (FIRDatabaseQuery *)queryLimitedToFirst:(NSUInteger)limit; - - -/** -* queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. -* The FIRDatabaseQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes. -* -* @param limit The upper bound, inclusive, for the number of child nodes to receive events for -* @return A FIRDatabaseQuery instance, limited to at most limit child nodes. -*/ -- (FIRDatabaseQuery *)queryLimitedToLast:(NSUInteger)limit; - -/** - * queryOrderBy: is used to generate a reference to a view of the data that's been sorted by the values of - * a particular child key. This method is intended to be used in combination with queryStartingAtValue:, - * queryEndingAtValue:, or queryEqualToValue:. - * - * @param key The child key to use in ordering data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, ordered by the values of the specified child key. -*/ -- (FIRDatabaseQuery *)queryOrderedByChild:(NSString *)key; - -/** - * queryOrderedByKey: is used to generate a reference to a view of the data that's been sorted by child key. - * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, - * or queryEqualToValue:. - * - * @return A FIRDatabaseQuery instance, ordered by child keys. - */ -- (FIRDatabaseQuery *) queryOrderedByKey; - -/** - * queryOrderedByValue: is used to generate a reference to a view of the data that's been sorted by child value. - * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, - * or queryEqualToValue:. - * - * @return A FIRDatabaseQuery instance, ordered by child value. - */ -- (FIRDatabaseQuery *) queryOrderedByValue; - -/** - * queryOrderedByPriority: is used to generate a reference to a view of the data that's been sorted by child - * priority. This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, - * or queryEqualToValue:. - * - * @return A FIRDatabaseQuery instance, ordered by child priorities. - */ -- (FIRDatabaseQuery *) queryOrderedByPriority; - -/** - * queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value - * greater than or equal to startValue. - * - * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue - */ -- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue; - -/** - * queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery 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. This is most - * useful when implementing pagination in a case where multiple nodes can match the startValue. - * - * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @param childKey The lower bound, inclusive, for the key of nodes with value equal to startValue - * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue - */ -- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue childKey:(nullable NSString *)childKey; - -/** - * queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value - * less than or equal to endValue. - * - * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue - */ -- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue; - -/** - * queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery 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. This is most useful when - * implementing pagination in a case where multiple nodes can match the endValue. - * - * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @param childKey The upper bound, inclusive, for the key of nodes with value equal to endValue - * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue - */ -- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue childKey:(nullable NSString *)childKey; - -/** - * queryEqualToValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal - * to the supplied argument. - * - * @param value The value that the data returned by this FIRDatabaseQuery will have - * @return A FIRDatabaseQuery instance, limited to data with the supplied value. - */ -- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value; - -/** - * queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value - * equal to the supplied argument and with their key equal to childKey. There will be at most one node that matches - * because child keys are unique. - * - * @param value The value that the data returned by this FIRDatabaseQuery will have - * @param childKey The name of nodes with the right value - * @return A FIRDatabaseQuery instance, limited to data with the supplied value and the key. - */ -- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value childKey:(nullable NSString *)childKey; - - -#pragma mark - Properties - -/** -* Gets a FIRDatabaseReference for the location of this query. -* -* @return A FIRDatabaseReference for the location of this query. -*/ -@property (nonatomic, readonly, strong) FIRDatabaseReference * ref; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FIRDatabaseSwiftNameSupport.h b/Firebase/Database/Api/FIRDatabaseSwiftNameSupport.h deleted file mode 100644 index 55e1bcc..0000000 --- a/Firebase/Database/Api/FIRDatabaseSwiftNameSupport.h +++ /dev/null @@ -1,29 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#ifndef FIR_SWIFT_NAME - -#import - -// NS_SWIFT_NAME can only translate factory methods before the iOS 9.3 SDK. -// Wrap it in our own macro if it's a non-compatible SDK. -#ifdef __IPHONE_9_3 -#define FIR_SWIFT_NAME(X) NS_SWIFT_NAME(X) -#else -#define FIR_SWIFT_NAME(X) // Intentionally blank. -#endif // #ifdef __IPHONE_9_3 - -#endif // FIR_SWIFT_NAME diff --git a/Firebase/Database/Api/FIRMutableData.h b/Firebase/Database/Api/FIRMutableData.h deleted file mode 100644 index 5c26024..0000000 --- a/Firebase/Database/Api/FIRMutableData.h +++ /dev/null @@ -1,130 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseSwiftNameSupport.h" - -NS_ASSUME_NONNULL_BEGIN - -/** - * A FIRMutableData instance is populated with data from a Firebase Database location. - * When you are using runTransactionBlock:, you will be given an instance containing the current - * data at that location. Your block will be responsible for updating that instance to the data - * you wish to save at that location, and then returning using [FIRTransactionResult successWithValue:]. - * - * To modify the data, set its value property to any of the native types support by Firebase Database: - * - * + NSNumber (includes BOOL) - * + NSDictionary - * + NSArray - * + NSString - * + nil / NSNull to remove the data - * - * Note that changes made to a child FIRMutableData instance will be visible to the parent. - */ -FIR_SWIFT_NAME(MutableData) -@interface FIRMutableData : NSObject - - -#pragma mark - Inspecting and navigating the data - - -/** - * Returns boolean indicating whether this mutable data has children. - * - * @return YES if this data contains child nodes. - */ -- (BOOL) hasChildren; - - -/** - * Indicates whether this mutable data has a child at the given path. - * - * @param path A path string, consisting either of a single segment, like 'child', or multiple segments, 'a/deeper/child' - * @return YES if this data contains a child at the specified relative path - */ -- (BOOL) hasChildAtPath:(NSString *)path; - - -/** - * Used to obtain a FIRMutableData instance that encapsulates the data at the given relative path. - * Note that changes made to the child will be visible to the parent. - * - * @param path A path string, consisting either of a single segment, like 'child', or multiple segments, 'a/deeper/child' - * @return A FIRMutableData instance containing the data at the given path - */ -- (FIRMutableData *)childDataByAppendingPath:(NSString *)path; - - -#pragma mark - Properties - - -/** - * To modify the data contained by this instance of FIRMutableData, set this to any of the native types supported by Firebase Database: - * - * + NSNumber (includes BOOL) - * + NSDictionary - * + NSArray - * + NSString - * + nil / NSNull to remove the data - * - * Note that setting this value will override the priority at this location. - * - * @return The current data at this location as a native object - */ -@property (strong, nonatomic, nullable) id value; - - -/** - * Set this property to update the priority of the data at this location. Can be set to the following types: - * - * + NSNumber - * + NSString - * + nil / NSNull to remove the priority - * - * @return The priority of the data at this location - */ -@property (strong, nonatomic, nullable) id priority; - - -/** - * @return The number of child nodes at this location - */ -@property (readonly, nonatomic) NSUInteger childrenCount; - - -/** - * Used to iterate over the children at this location. You can use the native for .. in syntax: - * - * for (FIRMutableData* child in data.children) { - * ... - * } - * - * Note that this enumerator operates on an immutable copy of the child list. So, you can modify the instance - * during iteration, but the new additions will not be visible until you get a new enumerator. - */ -@property (readonly, nonatomic, strong) NSEnumerator* children; - - -/** - * @return The key name of this node, or nil if it is the top-most location - */ -@property (readonly, nonatomic, strong, nullable) NSString* key; - - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FIRServerValue.h b/Firebase/Database/Api/FIRServerValue.h deleted file mode 100644 index f5eadd5..0000000 --- a/Firebase/Database/Api/FIRServerValue.h +++ /dev/null @@ -1,35 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import "FIRDatabaseSwiftNameSupport.h" - -NS_ASSUME_NONNULL_BEGIN - -/** - * Placeholder values you may write into Firebase Database as a value or priority - * that will automatically be populated by the Firebase Database server. - */ -FIR_SWIFT_NAME(ServerValue) -@interface FIRServerValue : NSObject - -/** - * Placeholder value for the number of milliseconds since the Unix epoch - */ -+ (NSDictionary *) timestamp; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FIRTransactionResult.h b/Firebase/Database/Api/FIRTransactionResult.h deleted file mode 100644 index 3c2d39a..0000000 --- a/Firebase/Database/Api/FIRTransactionResult.h +++ /dev/null @@ -1,47 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseSwiftNameSupport.h" -#import "FIRMutableData.h" - -NS_ASSUME_NONNULL_BEGIN - -/** - * Used for runTransactionBlock:. An FIRTransactionResult instance is a container for the results of the transaction. - */ -FIR_SWIFT_NAME(TransactionResult) -@interface FIRTransactionResult : NSObject - -/** - * Used for runTransactionBlock:. Indicates that the new value should be saved at this location - * - * @param value A FIRMutableData instance containing the new value to be set - * @return An FIRTransactionResult instance that can be used as a return value from the block given to runTransactionBlock: - */ -+ (FIRTransactionResult *)successWithValue:(FIRMutableData *)value; - - -/** - * Used for runTransactionBlock:. Indicates that the current transaction should no longer proceed. - * - * @return An FIRTransactionResult instance that can be used as a return value from the block given to runTransactionBlock: - */ -+ (FIRTransactionResult *) abort; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Api/FirebaseDatabase.h b/Firebase/Database/Api/FirebaseDatabase.h deleted file mode 100644 index e52f5d6..0000000 --- a/Firebase/Database/Api/FirebaseDatabase.h +++ /dev/null @@ -1,29 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#ifndef FirebaseDatabase_h -#define FirebaseDatabase_h - -#import "FIRDatabase.h" -#import "FIRDatabaseQuery.h" -#import "FIRDatabaseReference.h" -#import "FIRDataEventType.h" -#import "FIRDataSnapshot.h" -#import "FIRMutableData.h" -#import "FIRServerValue.h" -#import "FIRTransactionResult.h" - -#endif /* FirebaseDatabase_h */ diff --git a/Firebase/Database/FIRDatabaseReference.h b/Firebase/Database/FIRDatabaseReference.h deleted file mode 100644 index eb3fecd..0000000 --- a/Firebase/Database/FIRDatabaseReference.h +++ /dev/null @@ -1,719 +0,0 @@ -/* - * Copyright 2017 Google - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#import -#import "FIRDatabaseQuery.h" -#import "FIRDatabase.h" -#import "FIRDatabaseSwiftNameSupport.h" -#import "FIRDataSnapshot.h" -#import "FIRMutableData.h" -#import "FIRTransactionResult.h" -#import "FIRServerValue.h" - -NS_ASSUME_NONNULL_BEGIN - -@class FIRDatabase; - -/** - * A FIRDatabaseReference 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 Database operations. After you've - * obtained your first FIRDatabaseReference via [FIRDatabase reference], you can use it - * to read data (ie. observeEventType:withBlock:), write data (ie. setValue:), and to - * create new FIRDatabaseReferences (ie. child:). - */ -FIR_SWIFT_NAME(DatabaseReference) -@interface FIRDatabaseReference : FIRDatabaseQuery - - -#pragma mark - Getting references to children locations - -/** - * Gets a FIRDatabaseReference for the 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'). - * - * @param pathString A relative path from this location to the desired child location. - * @return A FIRDatabaseReference for the specified relative path. - */ -- (FIRDatabaseReference *)child:(NSString *)pathString; - -/** - * childByAppendingPath: is deprecated, use child: instead. - */ -- (FIRDatabaseReference *)childByAppendingPath:(NSString *)pathString __deprecated_msg("use child: instead"); - -/** - * childByAutoId generates a new child location using a unique key and returns a - * FIRDatabaseReference to it. This is useful when the children of a Firebase Database - * location represent a list of items. - * - * The unique key generated by childByAutoId: is prefixed with a client-generated - * timestamp so that the resulting list will be chronologically-sorted. - * - * @return A FIRDatabaseReference for the generated location. - */ -- (FIRDatabaseReference *) childByAutoId; - - -#pragma mark - Writing data - -/** Write data to this Firebase Database location. - -This will overwrite any data at this location and all child locations. - -Data types that can be set are: - -- NSString -- @"Hello World" -- NSNumber (also includes boolean) -- @YES, @43, @4.333 -- NSDictionary -- @{@"key": @"value", @"nested": @{@"another": @"value"} } -- NSArray - -The effect of the write will be visible immediately and the corresponding -events will be triggered. Synchronization of the data to the Firebase Database -servers will also be started. - -Passing null for the new value is equivalent to calling remove:; -all data at this location or any child location will be deleted. - -Note that setValue: will remove any priority stored at this location, so if priority -is meant to be preserved, you should use setValue:andPriority: instead. - -@param value The value to be written. - */ -- (void) setValue:(nullable id)value; - - -/** - * The same as setValue: with a block that gets triggered after the write operation has - * been committed to the Firebase Database servers. - * - * @param value The value to be written. - * @param block The block to be called after the write has been committed to the Firebase Database servers. - */ -- (void) setValue:(nullable id)value withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -/** - * The same as setValue: with an additional priority to be attached to the data being written. - * Priorities are used to order items. - * - * @param value The value to be written. - * @param priority The priority to be attached to that data. - */ -- (void) setValue:(nullable id)value andPriority:(nullable id)priority; - - -/** - * The same as setValue:andPriority: with a block that gets triggered after the write operation has - * been committed to the Firebase Database servers. - * - * @param value The value to be written. - * @param priority The priority to be attached to that data. - * @param block The block to be called after the write has been committed to the Firebase Database servers. - */ -- (void) setValue:(nullable id)value andPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -/** - * Remove the data at this Firebase Database location. Any data at child locations will also be deleted. - * - * The effect of the delete will be visible immediately and the corresponding events - * will be triggered. Synchronization of the delete to the Firebase Database servers will - * also be started. - * - * remove: is equivalent to calling setValue:nil - */ -- (void) removeValue; - - -/** - * The same as remove: with a block that gets triggered after the remove operation has - * been committed to the Firebase Database servers. - * - * @param block The block to be called after the remove has been committed to the Firebase Database servers. - */ -- (void) removeValueWithCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - -/** - * Sets 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 - * - * @param priority The priority to set at the specified location. - */ -- (void) setPriority:(nullable id)priority; - - -/** - * The same as setPriority: with a block that is called once the priority has - * been committed to the Firebase Database servers. - * - * @param priority The priority to set at the specified location. - * @param block The block that is triggered after the priority has been written on the servers. - */ -- (void) setPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - -/** - * Updates the values at the specified paths in the dictionary without overwriting other - * keys at this location. - * - * @param values A dictionary of the keys to change and their new values - */ -- (void) updateChildValues:(NSDictionary *)values; - -/** - * The same as update: with a block that is called once the update has been committed to the - * Firebase Database servers - * - * @param values A dictionary of the keys to change and their new values - * @param block The block that is triggered after the update has been written on the Firebase Database servers - */ -- (void) updateChildValues:(NSDictionary *)values withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -#pragma mark - Attaching observers to read data - -/** - * observeEventType:withBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. - * - * Use removeObserverWithHandle: to stop receiving updates. - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; - - -/** - * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot - * and the previous child's key. - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; - - -/** - * observeEventType:withBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the 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. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. - * @param cancelBlock The block that should be called if this client no longer has permission to receive these events - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. - * This is the primary way to read data from the Firebase Database. Your block will be triggered - * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged 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. - * - * Use removeObserverWithHandle: to stop receiving updates. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot - * and the previous child's key. - * @param cancelBlock The block that should be called if this client no longer has permission to receive these events - * @return A handle used to unregister this block later using removeObserverWithHandle: - */ -- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. - * - * The cancelBlock will be called if you do not have permission to read data at this location. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. - * @param cancelBlock The block that will be called if you don't have permission to access this data - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - - -/** - * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and - * FIRDataEventTypeChildChanged 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. - * - * @param eventType The type of event to listen for. - * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. - * @param cancelBlock The block that will be called if you don't have permission to access this data - */ -- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; - -#pragma mark - Detaching observers - -/** - * Detach a block previously attached with observeEventType:withBlock:. - * - * @param handle The handle returned by the call to observeEventType:withBlock: which we are trying to remove. - */ -- (void) removeObserverWithHandle:(FIRDatabaseHandle)handle; - -/** - * 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. - * - * @param keepSynced Pass YES to keep this location synchronized, pass NO to stop synchronization. - */ -- (void) keepSynced:(BOOL)keepSynced; - - -/** - * Removes all observers at the current reference, but does not remove any observers at child references. - * removeAllObservers must be called again for each child reference where a listener was established to remove the observers. - */ -- (void) removeAllObservers; - -#pragma mark - Querying and limiting - - -/** - * queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes. - * - * @param limit The upper bound, inclusive, for the number of child nodes to receive events for - * @return A FIRDatabaseQuery instance, limited to at most limit child nodes. - */ -- (FIRDatabaseQuery *)queryLimitedToFirst:(NSUInteger)limit; - - -/** - * queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes. - * - * @param limit The upper bound, inclusive, for the number of child nodes to receive events for - * @return A FIRDatabaseQuery instance, limited to at most limit child nodes. - */ -- (FIRDatabaseQuery *)queryLimitedToLast:(NSUInteger)limit; - -/** - * queryOrderBy: is used to generate a reference to a view of the data that's been sorted by the values of - * a particular child key. This method is intended to be used in combination with queryStartingAtValue:, - * queryEndingAtValue:, or queryEqualToValue:. - * - * @param key The child key to use in ordering data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, ordered by the values of the specified child key. - */ -- (FIRDatabaseQuery *)queryOrderedByChild:(NSString *)key; - -/** - * queryOrderedByKey: is used to generate a reference to a view of the data that's been sorted by child key. - * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, - * or queryEqualToValue:. - * - * @return A FIRDatabaseQuery instance, ordered by child keys. - */ -- (FIRDatabaseQuery *) queryOrderedByKey; - -/** - * queryOrderedByPriority: is used to generate a reference to a view of the data that's been sorted by child - * priority. This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, - * or queryEqualToValue:. - * - * @return A FIRDatabaseQuery instance, ordered by child priorities. - */ -- (FIRDatabaseQuery *) queryOrderedByPriority; - -/** - * queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value - * greater than or equal to startValue. - * - * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue - */ -- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue; - -/** - * queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery 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. - * - * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @param childKey The lower bound, inclusive, for the key of nodes with value equal to startValue - * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue - */ -- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue childKey:(nullable NSString *)childKey; - -/** - * queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value - * less than or equal to endValue. - * - * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue - */ -- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue; - -/** - * queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery 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. - * - * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery - * @param childKey The upper bound, inclusive, for the key of nodes with value equal to endValue - * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue - */ -- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue childKey:(nullable NSString *)childKey; - -/** - * queryEqualToValue: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal - * to the supplied argument. - * - * @param value The value that the data returned by this FIRDatabaseQuery will have - * @return A FIRDatabaseQuery instance, limited to data with the supplied value. - */ -- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value; - -/** - * queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. - * The FIRDatabaseQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value - * equal to the supplied argument with a key equal to childKey. There will be at most one node that matches because - * child keys are unique. - * - * @param value The value that the data returned by this FIRDatabaseQuery will have - * @param childKey The key of nodes with the right value - * @return A FIRDatabaseQuery instance, limited to data with the supplied value and the key. - */ -- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value childKey:(nullable NSString *)childKey; - -#pragma mark - Managing presence - -/** - * Ensure the data at this location is set to the specified value when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * onDisconnectSetValue: is especially useful for implementing "presence" systems, - * where a value should be changed or cleared when a user disconnects - * so that he appears "offline" to other users. - * - * @param value The value to be set after the connection is lost. - */ -- (void) onDisconnectSetValue:(nullable id)value; - - -/** - * Ensure the data at this location is set to the specified value when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers - * - * @param value The value to be set after the connection is lost. - * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers - */ -- (void) onDisconnectSetValue:(nullable id)value withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -/** - * Ensure the data at this location is set to the specified value and priority when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * @param value The value to be set after the connection is lost. - * @param priority The priority to be set after the connection is lost. - */ -- (void) onDisconnectSetValue:(nullable id)value andPriority:(id)priority; - - -/** - * Ensure the data at this location is set to the specified value and priority when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers - * - * @param value The value to be set after the connection is lost. - * @param priority The priority to be set after the connection is lost. - * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers - */ -- (void) onDisconnectSetValue:(nullable id)value andPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -/** - * Ensure the data at this location is removed when - * the client is disconnected (due to closing the app, navigating - * to a new page, or network issues). - * - * onDisconnectRemoveValue is especially useful for implementing "presence" systems. - */ -- (void) onDisconnectRemoveValue; - - -/** - * Ensure the data at this location is removed when - * the client is disconnected (due to closing the app, navigating - * to a new page, or network issues). - * - * onDisconnectRemoveValueWithCompletionBlock: is especially useful for implementing "presence" systems. - * - * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers - */ -- (void) onDisconnectRemoveValueWithCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - - -/** - * Ensure the data has the specified child values updated when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * - * @param values A dictionary of child node keys and the values to set them to after the connection is lost. - */ -- (void) onDisconnectUpdateChildValues:(NSDictionary *)values; - - -/** - * Ensure the data has the specified child values updated when - * the client is disconnected (due to closing the browser, navigating - * to a new page, or network issues). - * - * - * @param values A dictionary of child node keys and the values to set them to after the connection is lost. - * @param block A block that will be called once the operation has been queued up on the Firebase Database servers - */ -- (void) onDisconnectUpdateChildValues:(NSDictionary *)values withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -/** - * 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; - - -/** - * 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: - * - * @param block A block that will be triggered once the Firebase Database servers have acknowledged the cancel request. - */ -- (void) cancelDisconnectOperationsWithCompletionBlock:(nullable void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; - - -#pragma mark - Manual Connection Management - -/** - * Manually disconnect the Firebase Database client from the server and disable automatic reconnection. - * - * The Firebase Database client automatically maintains a persistent connection to the Firebase Database 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 Database client will no longer receive data updates from the server. However, - * all database 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 Database server. - * - * To reconnect to the Firebase Database server and begin receiving remote events, see goOnline( ). - * Once the connection is reestablished, the Firebase Database client will transmit the appropriate data - * and fire the appropriate events so that your client "catches up" automatically. - * - * Note: Invoking this method will impact all Firebase Database connections. - */ -+ (void) goOffline; - -/** - * Manually reestablish a connection to the Firebase Database server and enable automatic reconnection. - * - * The Firebase Database client automatically maintains a persistent connection to the Firebase Database 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 Database client will automatically transmit the proper data and fire - * the appropriate events so that your client "catches up" automatically. - * - * To disconnect from the Firebase Database server, see goOffline( ). - * - * Note: Invoking this method will impact all Firebase Database connections. - */ -+ (void) goOnline; - - -#pragma mark - Transactions - -/** - * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData - * 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 FIRTransactionResult 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. - * - * When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort]. - * - * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult - */ -- (void) runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block; - - -/** - * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData - * 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 FIRTransactionResult 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. - * - * When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort]. - * - * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult - * @param 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. - */ -- (void)runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block andCompletionBlock:(void (^) (NSError *__nullable error, BOOL committed, FIRDataSnapshot *__nullable snapshot))completionBlock; - - - -/** - * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData - * 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 FIRTransactionResult 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. - * - * When your block is run, you may decide to abort the transaction by return [FIRTransactionResult abort]. - * - * 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. - * - * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult - * @param 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. - * @param localEvents Set this to NO to suppress events raised for intermediate states, and only get events based on the final state of the transaction. - */ -- (void)runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block andCompletionBlock:(nullable void (^) (NSError *__nullable error, BOOL committed, FIRDataSnapshot *__nullable snapshot))completionBlock withLocalEvents:(BOOL)localEvents; - - -#pragma mark - Retrieving String Representation - -/** - * Gets the absolute URL of this Firebase Database location. - * - * @return The absolute URL of the referenced Firebase Database location. - */ -- (NSString *) description; - -#pragma mark - Properties - -/** - * Gets a FIRDatabaseReference for the parent location. - * If this instance refers to the root of your Firebase Database, it has no parent, - * and therefore parent( ) will return null. - * - * @return A FIRDatabaseReference for the parent location. - */ -@property (strong, readonly, nonatomic, nullable) FIRDatabaseReference * parent; - - -/** - * Gets a FIRDatabaseReference for the root location - * - * @return A new FIRDatabaseReference to root location. - */ -@property (strong, readonly, nonatomic) FIRDatabaseReference * root; - - -/** - * Gets the last token in a Firebase Database location (e.g. 'fred' in https://SampleChat.firebaseIO-demo.com/users/fred) - * - * @return The key of the location this reference points to. - */ -@property (strong, readonly, nonatomic) NSString* key; - -/** - * Gets the URL for the Firebase Database location referenced by this FIRDatabaseReference. - * - * @return The url of the location this reference points to. - */ -@property (strong, readonly, nonatomic) NSString* URL; - -/** - * Gets the FIRDatabase instance associated with this reference. - * - * @return The FIRDatabase object for this reference. - */ -@property (strong, readonly, nonatomic) FIRDatabase *database; - -@end - -NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/FirebaseDatabase.podspec b/Firebase/Database/FirebaseDatabase.podspec index e41e7a5..758556b 100644 --- a/Firebase/Database/FirebaseDatabase.podspec +++ b/Firebase/Database/FirebaseDatabase.podspec @@ -25,17 +25,7 @@ Simplify your iOS development, grow your user base, and monetize more effectivel s.source_files = '**/*.[mh]', 'third_party/Wrap-leveldb/APLevelDB.mm', 'third_party/SocketRocket/fbase64.c' - s.public_header_files = - 'Api/FirebaseDatabase.h', - 'Api/FIRDataEventType.h', - 'Api/FIRDataSnapshot.h', - 'Api/FIRDatabaseQuery.h', - 'Api/FIRDatabaseSwiftNameSupport.h', - 'Api/FIRMutableData.h', - 'Api/FIRServerValue.h', - 'Api/FIRTransactionResult.h', - 'Api/FIRDatabase.h', - 'FIRDatabaseReference.h' + s.public_header_files = 'Public/*.h' s.library = 'c++' s.library = 'icucore' s.framework = 'CFNetwork' diff --git a/Firebase/Database/Public/FIRDataEventType.h b/Firebase/Database/Public/FIRDataEventType.h new file mode 100644 index 0000000..fccc98a --- /dev/null +++ b/Firebase/Database/Public/FIRDataEventType.h @@ -0,0 +1,39 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef Firebase_FIRDataEventType_h +#define Firebase_FIRDataEventType_h + +#import +#import "FIRDatabaseSwiftNameSupport.h" + +/** + * This enum is the set of events that you can observe at a Firebase Database location. + */ +typedef NS_ENUM(NSInteger, FIRDataEventType) { + /// A new child node is added to a location. + FIRDataEventTypeChildAdded, + /// A child node is removed from a location. + FIRDataEventTypeChildRemoved, + /// A child node at a location changes. + FIRDataEventTypeChildChanged, + /// A child node moves relative to the other child nodes at a location. + FIRDataEventTypeChildMoved, + /// Any data changes at a location or, recursively, at any child node. + FIRDataEventTypeValue +} FIR_SWIFT_NAME(DataEventType); + +#endif diff --git a/Firebase/Database/Public/FIRDataSnapshot.h b/Firebase/Database/Public/FIRDataSnapshot.h new file mode 100644 index 0000000..e615260 --- /dev/null +++ b/Firebase/Database/Public/FIRDataSnapshot.h @@ -0,0 +1,148 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseSwiftNameSupport.h" + +NS_ASSUME_NONNULL_BEGIN + +@class FIRDatabaseReference; + +/** + * A FIRDataSnapshot contains data from a Firebase Database location. Any time you read + * Firebase data, you receive the data as a FIRDataSnapshot. + * + * FIRDataSnapshots are passed to the blocks you attach with observeEventType:withBlock: or observeSingleEvent:withBlock:. + * They are efficiently-generated immutable copies of the data at a Firebase Database location. + * They can't be modified and will never change. To modify data at a location, + * use a FIRDatabaseReference (e.g. with setValue:). + */ +FIR_SWIFT_NAME(DataSnapshot) +@interface FIRDataSnapshot : NSObject + + +#pragma mark - Navigating and inspecting a snapshot + +/** + * Gets a FIRDataSnapshot for the 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'). If the child + * location has no data, an empty FIRDataSnapshot is returned. + * + * @param childPathString A relative path to the location of child data. + * @return The FIRDataSnapshot for the child location. + */ +- (FIRDataSnapshot *)childSnapshotForPath:(NSString *)childPathString; + + +/** + * Return YES if the specified child exists. + * + * @param childPathString A relative path to the location of a potential child. + * @return YES if data exists at the specified childPathString, else NO. + */ +- (BOOL) hasChild:(NSString *)childPathString; + + +/** + * Return YES if the DataSnapshot has any children. + * + * @return YES if this snapshot has any children, else NO. + */ +- (BOOL) hasChildren; + + +/** + * Return YES if the DataSnapshot contains a non-null value. + * + * @return YES if this snapshot contains a non-null value, else NO. + */ +- (BOOL) exists; + + +#pragma mark - Data export + +/** + * Returns the raw value at this location, coupled with any metadata, such as priority. + * + * Priorities, where they exist, are accessible under the ".priority" key in instances of NSDictionary. + * For leaf locations with priorities, the value will be under the ".value" key. + */ +- (id __nullable) valueInExportFormat; + + +#pragma mark - Properties + +/** + * Returns the contents of this data snapshot as native types. + * + * Data types returned: + * + NSDictionary + * + NSArray + * + NSNumber (also includes booleans) + * + NSString + * + * @return The data as a native object. + */ +@property (strong, readonly, nonatomic, nullable) id value; + + +/** + * Gets the number of children for this DataSnapshot. + * + * @return An integer indicating the number of children. + */ +@property (readonly, nonatomic) NSUInteger childrenCount; + + +/** + * Gets a FIRDatabaseReference for the location that this data came from. + * + * @return A FIRDatabaseReference instance for the location of this data. + */ +@property (nonatomic, readonly, strong) FIRDatabaseReference * ref; + + +/** + * The key of the location that generated this FIRDataSnapshot. + * + * @return An NSString containing the key for the location of this FIRDataSnapshot. + */ +@property (strong, readonly, nonatomic) NSString* key; + + +/** + * An iterator for snapshots of the child nodes in this snapshot. + * You can use the native for..in syntax: + * + * for (FIRDataSnapshot* child in snapshot.children) { + * ... + * } + * + * @return An NSEnumerator of the children. + */ +@property (strong, readonly, nonatomic) NSEnumerator* children; + +/** + * The priority of the data in this FIRDataSnapshot. + * + * @return The priority as a string, or nil if no priority was set. + */ +@property (strong, readonly, nonatomic, nullable) id priority; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRDatabase.h b/Firebase/Database/Public/FIRDatabase.h new file mode 100644 index 0000000..ebdbf8a --- /dev/null +++ b/Firebase/Database/Public/FIRDatabase.h @@ -0,0 +1,148 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseReference.h" +#import "FIRDatabaseSwiftNameSupport.h" + +@class FIRApp; + +NS_ASSUME_NONNULL_BEGIN + +/** + * The entry point for accessing a Firebase Database. You can get an instance by calling + * [FIRDatabase database]. To access a location in the database and read or write data, + * use [FIRDatabase reference]. + */ +FIR_SWIFT_NAME(Database) +@interface FIRDatabase : NSObject + +/** + * The NSObject initializer that has been marked as unavailable. Use the `database` + * method instead + * + * @return An instancetype instance +*/ ++ (instancetype) init __attribute__((unavailable("use the database method instead"))); + +/** + * Gets the instance of FIRDatabase for the default FIRApp. + * + * @return A FIRDatabase instance. + */ ++ (FIRDatabase *) database FIR_SWIFT_NAME(database()); + +/** + * Gets an instance of FIRDatabase for a specific FIRApp. + * + * @param app The FIRApp to get a FIRDatabase for. + * @return A FIRDatabase instance. + */ ++ (FIRDatabase *) databaseForApp:(FIRApp*)app FIR_SWIFT_NAME(database(app:)); + +/** The FIRApp instance to which this FIRDatabase belongs. */ +@property (weak, readonly, nonatomic) FIRApp *app; + +/** + * Gets a FIRDatabaseReference for the root of your Firebase Database. + */ +- (FIRDatabaseReference *) reference; + +/** + * Gets a FIRDatabaseReference for the provided path. + * + * @param path Path to a location in your Firebase Database. + * @return A FIRDatabaseReference pointing to the specified path. + */ +- (FIRDatabaseReference *) referenceWithPath:(NSString *)path; + +/** + * Gets a FIRDatabaseReference for the provided URL. The URL must be a URL to a path + * within this Firebase Database. To create a FIRDatabaseReference to a different database, + * create a FIRApp} with a FIROptions object configured with the appropriate database URL. + * + * @param databaseUrl A URL to a path within your database. + * @return A FIRDatabaseReference for the provided URL. +*/ +- (FIRDatabaseReference *) referenceFromURL:(NSString *)databaseUrl; + +/** + * The Firebase Database client automatically queues writes and sends them to the server at the earliest opportunity, + * depending on network connectivity. In some cases (e.g. offline usage) there may be a large number of writes + * waiting to be sent. Calling this method will purge all outstanding writes so they are abandoned. + * + * All writes will be purged, including transactions and onDisconnect writes. The writes will + * be rolled back locally, perhaps triggering events for affected event listeners, and the client will not + * (re-)send them to the Firebase Database backend. + */ +- (void)purgeOutstandingWrites; + +/** + * Shuts down our connection to the Firebase Database backend until goOnline is called. + */ +- (void)goOffline; + +/** + * Resumes our connection to the Firebase Database backend after a previous goOffline call. + */ +- (void)goOnline; + +/** + * The Firebase Database client will cache synchronized data and keep track of all writes you've + * initiated while your application is running. It seamlessly handles intermittent network + * connections and re-sends write operations when the network connection is restored. + * + * However by default your write operations and cached data are only stored in-memory and will + * be lost when your app restarts. By setting this value to `YES`, the data will be persisted + * to on-device (disk) storage and will thus be available again when the app is restarted + * (even when there is no network connectivity at that time). Note that this property must be + * set before creating your first Database reference and only needs to be called once per + * application. + * + */ +@property (nonatomic) BOOL persistenceEnabled FIR_SWIFT_NAME(isPersistenceEnabled); + +/** + * By default the Firebase Database client will use up to 10MB of disk space to cache data. If the cache grows beyond + * this size, the client will start removing data that hasn't been recently used. If you find that your application + * caches too little or too much data, call this method to change the cache size. This property must be set before + * creating your first FIRDatabaseReference and only needs to be called once per application. + * + * Note that the specified cache size is only an approximation and the size on disk may temporarily exceed it + * at times. Cache sizes smaller than 1 MB or greater than 100 MB are not supported. + */ +@property (nonatomic) NSUInteger persistenceCacheSizeBytes; + +/** + * Sets the dispatch queue on which all events are raised. The default queue is the main queue. + * + * Note that this must be set before creating your first Database reference. + */ +@property (nonatomic, strong) dispatch_queue_t callbackQueue; + +/** + * Enables verbose diagnostic logging. + * + * @param enabled YES to enable logging, NO to disable. + */ ++ (void) setLoggingEnabled:(BOOL)enabled; + +/** Retrieve the Firebase Database SDK version. */ ++ (NSString *) sdkVersion; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRDatabaseQuery.h b/Firebase/Database/Public/FIRDatabaseQuery.h new file mode 100644 index 0000000..be4ad27 --- /dev/null +++ b/Firebase/Database/Public/FIRDatabaseQuery.h @@ -0,0 +1,315 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseSwiftNameSupport.h" +#import "FIRDataEventType.h" +#import "FIRDataSnapshot.h" + +NS_ASSUME_NONNULL_BEGIN + +/** + * A FIRDatabaseHandle is used to identify listeners of Firebase Database events. These handles + * are returned by observeEventType: and and can later be passed to removeObserverWithHandle: to + * stop receiving updates. + */ +typedef NSUInteger FIRDatabaseHandle FIR_SWIFT_NAME(DatabaseHandle); + +/** + * A FIRDatabaseQuery instance represents a query over the data at a particular location. + * + * You create one by calling one of the query methods (queryOrderedByChild:, queryStartingAtValue:, etc.) + * on a FIRDatabaseReference. The query methods can be chained to further specify the data you are interested in + * observing + */ +FIR_SWIFT_NAME(DatabaseQuery) +@interface FIRDatabaseQuery : NSObject + + +#pragma mark - Attach observers to read data + +/** + * observeEventType:withBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; + + +/** + * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot + * and the previous child's key. + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; + + +/** + * observeEventType:withBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the 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. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. + * @param cancelBlock The block that should be called if this client no longer has permission to receive these events + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged 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. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot + * and the previous child's key. + * @param cancelBlock The block that should be called if this client no longer has permission to receive these events + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. + * + * The cancelBlock will be called if you do not have permission to read data at this location. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. + * @param cancelBlock The block that will be called if you don't have permission to access this data + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged 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. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. + * @param cancelBlock The block that will be called if you don't have permission to access this data + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +#pragma mark - Detaching observers + +/** + * Detach a block previously attached with observeEventType:withBlock:. + * + * @param handle The handle returned by the call to observeEventType:withBlock: which we are trying to remove. + */ +- (void) removeObserverWithHandle:(FIRDatabaseHandle)handle; + + +/** + * Detach all blocks previously attached to this Firebase Database location with observeEventType:withBlock: + */ +- (void) removeAllObservers; + +/** + * 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. + * + * @param keepSynced Pass YES to keep this location synchronized, pass NO to stop synchronization. +*/ + - (void) keepSynced:(BOOL)keepSynced; + + +#pragma mark - Querying and limiting + +/** +* queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. +* The FIRDatabaseQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes. +* +* @param limit The upper bound, inclusive, for the number of child nodes to receive events for +* @return A FIRDatabaseQuery instance, limited to at most limit child nodes. +*/ +- (FIRDatabaseQuery *)queryLimitedToFirst:(NSUInteger)limit; + + +/** +* queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. +* The FIRDatabaseQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes. +* +* @param limit The upper bound, inclusive, for the number of child nodes to receive events for +* @return A FIRDatabaseQuery instance, limited to at most limit child nodes. +*/ +- (FIRDatabaseQuery *)queryLimitedToLast:(NSUInteger)limit; + +/** + * queryOrderBy: is used to generate a reference to a view of the data that's been sorted by the values of + * a particular child key. This method is intended to be used in combination with queryStartingAtValue:, + * queryEndingAtValue:, or queryEqualToValue:. + * + * @param key The child key to use in ordering data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, ordered by the values of the specified child key. +*/ +- (FIRDatabaseQuery *)queryOrderedByChild:(NSString *)key; + +/** + * queryOrderedByKey: is used to generate a reference to a view of the data that's been sorted by child key. + * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, + * or queryEqualToValue:. + * + * @return A FIRDatabaseQuery instance, ordered by child keys. + */ +- (FIRDatabaseQuery *) queryOrderedByKey; + +/** + * queryOrderedByValue: is used to generate a reference to a view of the data that's been sorted by child value. + * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, + * or queryEqualToValue:. + * + * @return A FIRDatabaseQuery instance, ordered by child value. + */ +- (FIRDatabaseQuery *) queryOrderedByValue; + +/** + * queryOrderedByPriority: is used to generate a reference to a view of the data that's been sorted by child + * priority. This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, + * or queryEqualToValue:. + * + * @return A FIRDatabaseQuery instance, ordered by child priorities. + */ +- (FIRDatabaseQuery *) queryOrderedByPriority; + +/** + * queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value + * greater than or equal to startValue. + * + * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue + */ +- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue; + +/** + * queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery 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. This is most + * useful when implementing pagination in a case where multiple nodes can match the startValue. + * + * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @param childKey The lower bound, inclusive, for the key of nodes with value equal to startValue + * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue + */ +- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue childKey:(nullable NSString *)childKey; + +/** + * queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value + * less than or equal to endValue. + * + * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue + */ +- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue; + +/** + * queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery 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. This is most useful when + * implementing pagination in a case where multiple nodes can match the endValue. + * + * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @param childKey The upper bound, inclusive, for the key of nodes with value equal to endValue + * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue + */ +- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue childKey:(nullable NSString *)childKey; + +/** + * queryEqualToValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal + * to the supplied argument. + * + * @param value The value that the data returned by this FIRDatabaseQuery will have + * @return A FIRDatabaseQuery instance, limited to data with the supplied value. + */ +- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value; + +/** + * queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value + * equal to the supplied argument and with their key equal to childKey. There will be at most one node that matches + * because child keys are unique. + * + * @param value The value that the data returned by this FIRDatabaseQuery will have + * @param childKey The name of nodes with the right value + * @return A FIRDatabaseQuery instance, limited to data with the supplied value and the key. + */ +- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value childKey:(nullable NSString *)childKey; + + +#pragma mark - Properties + +/** +* Gets a FIRDatabaseReference for the location of this query. +* +* @return A FIRDatabaseReference for the location of this query. +*/ +@property (nonatomic, readonly, strong) FIRDatabaseReference * ref; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRDatabaseReference.h b/Firebase/Database/Public/FIRDatabaseReference.h new file mode 100644 index 0000000..eb3fecd --- /dev/null +++ b/Firebase/Database/Public/FIRDatabaseReference.h @@ -0,0 +1,719 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseQuery.h" +#import "FIRDatabase.h" +#import "FIRDatabaseSwiftNameSupport.h" +#import "FIRDataSnapshot.h" +#import "FIRMutableData.h" +#import "FIRTransactionResult.h" +#import "FIRServerValue.h" + +NS_ASSUME_NONNULL_BEGIN + +@class FIRDatabase; + +/** + * A FIRDatabaseReference 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 Database operations. After you've + * obtained your first FIRDatabaseReference via [FIRDatabase reference], you can use it + * to read data (ie. observeEventType:withBlock:), write data (ie. setValue:), and to + * create new FIRDatabaseReferences (ie. child:). + */ +FIR_SWIFT_NAME(DatabaseReference) +@interface FIRDatabaseReference : FIRDatabaseQuery + + +#pragma mark - Getting references to children locations + +/** + * Gets a FIRDatabaseReference for the 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'). + * + * @param pathString A relative path from this location to the desired child location. + * @return A FIRDatabaseReference for the specified relative path. + */ +- (FIRDatabaseReference *)child:(NSString *)pathString; + +/** + * childByAppendingPath: is deprecated, use child: instead. + */ +- (FIRDatabaseReference *)childByAppendingPath:(NSString *)pathString __deprecated_msg("use child: instead"); + +/** + * childByAutoId generates a new child location using a unique key and returns a + * FIRDatabaseReference to it. This is useful when the children of a Firebase Database + * location represent a list of items. + * + * The unique key generated by childByAutoId: is prefixed with a client-generated + * timestamp so that the resulting list will be chronologically-sorted. + * + * @return A FIRDatabaseReference for the generated location. + */ +- (FIRDatabaseReference *) childByAutoId; + + +#pragma mark - Writing data + +/** Write data to this Firebase Database location. + +This will overwrite any data at this location and all child locations. + +Data types that can be set are: + +- NSString -- @"Hello World" +- NSNumber (also includes boolean) -- @YES, @43, @4.333 +- NSDictionary -- @{@"key": @"value", @"nested": @{@"another": @"value"} } +- NSArray + +The effect of the write will be visible immediately and the corresponding +events will be triggered. Synchronization of the data to the Firebase Database +servers will also be started. + +Passing null for the new value is equivalent to calling remove:; +all data at this location or any child location will be deleted. + +Note that setValue: will remove any priority stored at this location, so if priority +is meant to be preserved, you should use setValue:andPriority: instead. + +@param value The value to be written. + */ +- (void) setValue:(nullable id)value; + + +/** + * The same as setValue: with a block that gets triggered after the write operation has + * been committed to the Firebase Database servers. + * + * @param value The value to be written. + * @param block The block to be called after the write has been committed to the Firebase Database servers. + */ +- (void) setValue:(nullable id)value withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +/** + * The same as setValue: with an additional priority to be attached to the data being written. + * Priorities are used to order items. + * + * @param value The value to be written. + * @param priority The priority to be attached to that data. + */ +- (void) setValue:(nullable id)value andPriority:(nullable id)priority; + + +/** + * The same as setValue:andPriority: with a block that gets triggered after the write operation has + * been committed to the Firebase Database servers. + * + * @param value The value to be written. + * @param priority The priority to be attached to that data. + * @param block The block to be called after the write has been committed to the Firebase Database servers. + */ +- (void) setValue:(nullable id)value andPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +/** + * Remove the data at this Firebase Database location. Any data at child locations will also be deleted. + * + * The effect of the delete will be visible immediately and the corresponding events + * will be triggered. Synchronization of the delete to the Firebase Database servers will + * also be started. + * + * remove: is equivalent to calling setValue:nil + */ +- (void) removeValue; + + +/** + * The same as remove: with a block that gets triggered after the remove operation has + * been committed to the Firebase Database servers. + * + * @param block The block to be called after the remove has been committed to the Firebase Database servers. + */ +- (void) removeValueWithCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + +/** + * Sets 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 + * + * @param priority The priority to set at the specified location. + */ +- (void) setPriority:(nullable id)priority; + + +/** + * The same as setPriority: with a block that is called once the priority has + * been committed to the Firebase Database servers. + * + * @param priority The priority to set at the specified location. + * @param block The block that is triggered after the priority has been written on the servers. + */ +- (void) setPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + +/** + * Updates the values at the specified paths in the dictionary without overwriting other + * keys at this location. + * + * @param values A dictionary of the keys to change and their new values + */ +- (void) updateChildValues:(NSDictionary *)values; + +/** + * The same as update: with a block that is called once the update has been committed to the + * Firebase Database servers + * + * @param values A dictionary of the keys to change and their new values + * @param block The block that is triggered after the update has been written on the Firebase Database servers + */ +- (void) updateChildValues:(NSDictionary *)values withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +#pragma mark - Attaching observers to read data + +/** + * observeEventType:withBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. + * + * Use removeObserverWithHandle: to stop receiving updates. + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; + + +/** + * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot + * and the previous child's key. + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; + + +/** + * observeEventType:withBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the 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. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. + * @param cancelBlock The block that should be called if this client no longer has permission to receive these events + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * observeEventType:andPreviousSiblingKeyWithBlock: is used to listen for data changes at a particular location. + * This is the primary way to read data from the Firebase Database. Your block will be triggered + * for the initial data and again whenever the data changes. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged 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. + * + * Use removeObserverWithHandle: to stop receiving updates. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot + * and the previous child's key. + * @param cancelBlock The block that should be called if this client no longer has permission to receive these events + * @return A handle used to unregister this block later using removeObserverWithHandle: + */ +- (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. + * + * The cancelBlock will be called if you do not have permission to read data at this location. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot. + * @param cancelBlock The block that will be called if you don't have permission to access this data + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType withBlock:(void (^)(FIRDataSnapshot *snapshot))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + + +/** + * This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and + * FIRDataEventTypeChildChanged 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. + * + * @param eventType The type of event to listen for. + * @param block The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child's key. + * @param cancelBlock The block that will be called if you don't have permission to access this data + */ +- (void)observeSingleEventOfType:(FIRDataEventType)eventType andPreviousSiblingKeyWithBlock:(void (^)(FIRDataSnapshot *snapshot, NSString *__nullable prevKey))block withCancelBlock:(nullable void (^)(NSError* error))cancelBlock; + +#pragma mark - Detaching observers + +/** + * Detach a block previously attached with observeEventType:withBlock:. + * + * @param handle The handle returned by the call to observeEventType:withBlock: which we are trying to remove. + */ +- (void) removeObserverWithHandle:(FIRDatabaseHandle)handle; + +/** + * 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. + * + * @param keepSynced Pass YES to keep this location synchronized, pass NO to stop synchronization. + */ +- (void) keepSynced:(BOOL)keepSynced; + + +/** + * Removes all observers at the current reference, but does not remove any observers at child references. + * removeAllObservers must be called again for each child reference where a listener was established to remove the observers. + */ +- (void) removeAllObservers; + +#pragma mark - Querying and limiting + + +/** + * queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes. + * + * @param limit The upper bound, inclusive, for the number of child nodes to receive events for + * @return A FIRDatabaseQuery instance, limited to at most limit child nodes. + */ +- (FIRDatabaseQuery *)queryLimitedToFirst:(NSUInteger)limit; + + +/** + * queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes. + * + * @param limit The upper bound, inclusive, for the number of child nodes to receive events for + * @return A FIRDatabaseQuery instance, limited to at most limit child nodes. + */ +- (FIRDatabaseQuery *)queryLimitedToLast:(NSUInteger)limit; + +/** + * queryOrderBy: is used to generate a reference to a view of the data that's been sorted by the values of + * a particular child key. This method is intended to be used in combination with queryStartingAtValue:, + * queryEndingAtValue:, or queryEqualToValue:. + * + * @param key The child key to use in ordering data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, ordered by the values of the specified child key. + */ +- (FIRDatabaseQuery *)queryOrderedByChild:(NSString *)key; + +/** + * queryOrderedByKey: is used to generate a reference to a view of the data that's been sorted by child key. + * This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, + * or queryEqualToValue:. + * + * @return A FIRDatabaseQuery instance, ordered by child keys. + */ +- (FIRDatabaseQuery *) queryOrderedByKey; + +/** + * queryOrderedByPriority: is used to generate a reference to a view of the data that's been sorted by child + * priority. This method is intended to be used in combination with queryStartingAtValue:, queryEndingAtValue:, + * or queryEqualToValue:. + * + * @return A FIRDatabaseQuery instance, ordered by child priorities. + */ +- (FIRDatabaseQuery *) queryOrderedByPriority; + +/** + * queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value + * greater than or equal to startValue. + * + * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue + */ +- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue; + +/** + * queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery 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. + * + * @param startValue The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @param childKey The lower bound, inclusive, for the key of nodes with value equal to startValue + * @return A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue + */ +- (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue childKey:(nullable NSString *)childKey; + +/** + * queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value + * less than or equal to endValue. + * + * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue + */ +- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue; + +/** + * queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery 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. + * + * @param endValue The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery + * @param childKey The upper bound, inclusive, for the key of nodes with value equal to endValue + * @return A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue + */ +- (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue childKey:(nullable NSString *)childKey; + +/** + * queryEqualToValue: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal + * to the supplied argument. + * + * @param value The value that the data returned by this FIRDatabaseQuery will have + * @return A FIRDatabaseQuery instance, limited to data with the supplied value. + */ +- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value; + +/** + * queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. + * The FIRDatabaseQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value + * equal to the supplied argument with a key equal to childKey. There will be at most one node that matches because + * child keys are unique. + * + * @param value The value that the data returned by this FIRDatabaseQuery will have + * @param childKey The key of nodes with the right value + * @return A FIRDatabaseQuery instance, limited to data with the supplied value and the key. + */ +- (FIRDatabaseQuery *)queryEqualToValue:(nullable id)value childKey:(nullable NSString *)childKey; + +#pragma mark - Managing presence + +/** + * Ensure the data at this location is set to the specified value when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * onDisconnectSetValue: is especially useful for implementing "presence" systems, + * where a value should be changed or cleared when a user disconnects + * so that he appears "offline" to other users. + * + * @param value The value to be set after the connection is lost. + */ +- (void) onDisconnectSetValue:(nullable id)value; + + +/** + * Ensure the data at this location is set to the specified value when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers + * + * @param value The value to be set after the connection is lost. + * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers + */ +- (void) onDisconnectSetValue:(nullable id)value withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +/** + * Ensure the data at this location is set to the specified value and priority when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * @param value The value to be set after the connection is lost. + * @param priority The priority to be set after the connection is lost. + */ +- (void) onDisconnectSetValue:(nullable id)value andPriority:(id)priority; + + +/** + * Ensure the data at this location is set to the specified value and priority when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers + * + * @param value The value to be set after the connection is lost. + * @param priority The priority to be set after the connection is lost. + * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers + */ +- (void) onDisconnectSetValue:(nullable id)value andPriority:(nullable id)priority withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +/** + * Ensure the data at this location is removed when + * the client is disconnected (due to closing the app, navigating + * to a new page, or network issues). + * + * onDisconnectRemoveValue is especially useful for implementing "presence" systems. + */ +- (void) onDisconnectRemoveValue; + + +/** + * Ensure the data at this location is removed when + * the client is disconnected (due to closing the app, navigating + * to a new page, or network issues). + * + * onDisconnectRemoveValueWithCompletionBlock: is especially useful for implementing "presence" systems. + * + * @param block Block to be triggered when the operation has been queued up on the Firebase Database servers + */ +- (void) onDisconnectRemoveValueWithCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + + +/** + * Ensure the data has the specified child values updated when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * + * @param values A dictionary of child node keys and the values to set them to after the connection is lost. + */ +- (void) onDisconnectUpdateChildValues:(NSDictionary *)values; + + +/** + * Ensure the data has the specified child values updated when + * the client is disconnected (due to closing the browser, navigating + * to a new page, or network issues). + * + * + * @param values A dictionary of child node keys and the values to set them to after the connection is lost. + * @param block A block that will be called once the operation has been queued up on the Firebase Database servers + */ +- (void) onDisconnectUpdateChildValues:(NSDictionary *)values withCompletionBlock:(void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +/** + * 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; + + +/** + * 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: + * + * @param block A block that will be triggered once the Firebase Database servers have acknowledged the cancel request. + */ +- (void) cancelDisconnectOperationsWithCompletionBlock:(nullable void (^)(NSError *__nullable error, FIRDatabaseReference * ref))block; + + +#pragma mark - Manual Connection Management + +/** + * Manually disconnect the Firebase Database client from the server and disable automatic reconnection. + * + * The Firebase Database client automatically maintains a persistent connection to the Firebase Database 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 Database client will no longer receive data updates from the server. However, + * all database 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 Database server. + * + * To reconnect to the Firebase Database server and begin receiving remote events, see goOnline( ). + * Once the connection is reestablished, the Firebase Database client will transmit the appropriate data + * and fire the appropriate events so that your client "catches up" automatically. + * + * Note: Invoking this method will impact all Firebase Database connections. + */ ++ (void) goOffline; + +/** + * Manually reestablish a connection to the Firebase Database server and enable automatic reconnection. + * + * The Firebase Database client automatically maintains a persistent connection to the Firebase Database 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 Database client will automatically transmit the proper data and fire + * the appropriate events so that your client "catches up" automatically. + * + * To disconnect from the Firebase Database server, see goOffline( ). + * + * Note: Invoking this method will impact all Firebase Database connections. + */ ++ (void) goOnline; + + +#pragma mark - Transactions + +/** + * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData + * 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 FIRTransactionResult 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. + * + * When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort]. + * + * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult + */ +- (void) runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block; + + +/** + * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData + * 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 FIRTransactionResult 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. + * + * When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort]. + * + * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult + * @param 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. + */ +- (void)runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block andCompletionBlock:(void (^) (NSError *__nullable error, BOOL committed, FIRDataSnapshot *__nullable snapshot))completionBlock; + + + +/** + * Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData + * 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 FIRTransactionResult 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. + * + * When your block is run, you may decide to abort the transaction by return [FIRTransactionResult abort]. + * + * 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. + * + * @param block This block receives the current data at this location and must return an instance of FIRTransactionResult + * @param 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. + * @param localEvents Set this to NO to suppress events raised for intermediate states, and only get events based on the final state of the transaction. + */ +- (void)runTransactionBlock:(FIRTransactionResult * (^) (FIRMutableData* currentData))block andCompletionBlock:(nullable void (^) (NSError *__nullable error, BOOL committed, FIRDataSnapshot *__nullable snapshot))completionBlock withLocalEvents:(BOOL)localEvents; + + +#pragma mark - Retrieving String Representation + +/** + * Gets the absolute URL of this Firebase Database location. + * + * @return The absolute URL of the referenced Firebase Database location. + */ +- (NSString *) description; + +#pragma mark - Properties + +/** + * Gets a FIRDatabaseReference for the parent location. + * If this instance refers to the root of your Firebase Database, it has no parent, + * and therefore parent( ) will return null. + * + * @return A FIRDatabaseReference for the parent location. + */ +@property (strong, readonly, nonatomic, nullable) FIRDatabaseReference * parent; + + +/** + * Gets a FIRDatabaseReference for the root location + * + * @return A new FIRDatabaseReference to root location. + */ +@property (strong, readonly, nonatomic) FIRDatabaseReference * root; + + +/** + * Gets the last token in a Firebase Database location (e.g. 'fred' in https://SampleChat.firebaseIO-demo.com/users/fred) + * + * @return The key of the location this reference points to. + */ +@property (strong, readonly, nonatomic) NSString* key; + +/** + * Gets the URL for the Firebase Database location referenced by this FIRDatabaseReference. + * + * @return The url of the location this reference points to. + */ +@property (strong, readonly, nonatomic) NSString* URL; + +/** + * Gets the FIRDatabase instance associated with this reference. + * + * @return The FIRDatabase object for this reference. + */ +@property (strong, readonly, nonatomic) FIRDatabase *database; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRDatabaseSwiftNameSupport.h b/Firebase/Database/Public/FIRDatabaseSwiftNameSupport.h new file mode 100644 index 0000000..55e1bcc --- /dev/null +++ b/Firebase/Database/Public/FIRDatabaseSwiftNameSupport.h @@ -0,0 +1,29 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef FIR_SWIFT_NAME + +#import + +// NS_SWIFT_NAME can only translate factory methods before the iOS 9.3 SDK. +// Wrap it in our own macro if it's a non-compatible SDK. +#ifdef __IPHONE_9_3 +#define FIR_SWIFT_NAME(X) NS_SWIFT_NAME(X) +#else +#define FIR_SWIFT_NAME(X) // Intentionally blank. +#endif // #ifdef __IPHONE_9_3 + +#endif // FIR_SWIFT_NAME diff --git a/Firebase/Database/Public/FIRMutableData.h b/Firebase/Database/Public/FIRMutableData.h new file mode 100644 index 0000000..5c26024 --- /dev/null +++ b/Firebase/Database/Public/FIRMutableData.h @@ -0,0 +1,130 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseSwiftNameSupport.h" + +NS_ASSUME_NONNULL_BEGIN + +/** + * A FIRMutableData instance is populated with data from a Firebase Database location. + * When you are using runTransactionBlock:, you will be given an instance containing the current + * data at that location. Your block will be responsible for updating that instance to the data + * you wish to save at that location, and then returning using [FIRTransactionResult successWithValue:]. + * + * To modify the data, set its value property to any of the native types support by Firebase Database: + * + * + NSNumber (includes BOOL) + * + NSDictionary + * + NSArray + * + NSString + * + nil / NSNull to remove the data + * + * Note that changes made to a child FIRMutableData instance will be visible to the parent. + */ +FIR_SWIFT_NAME(MutableData) +@interface FIRMutableData : NSObject + + +#pragma mark - Inspecting and navigating the data + + +/** + * Returns boolean indicating whether this mutable data has children. + * + * @return YES if this data contains child nodes. + */ +- (BOOL) hasChildren; + + +/** + * Indicates whether this mutable data has a child at the given path. + * + * @param path A path string, consisting either of a single segment, like 'child', or multiple segments, 'a/deeper/child' + * @return YES if this data contains a child at the specified relative path + */ +- (BOOL) hasChildAtPath:(NSString *)path; + + +/** + * Used to obtain a FIRMutableData instance that encapsulates the data at the given relative path. + * Note that changes made to the child will be visible to the parent. + * + * @param path A path string, consisting either of a single segment, like 'child', or multiple segments, 'a/deeper/child' + * @return A FIRMutableData instance containing the data at the given path + */ +- (FIRMutableData *)childDataByAppendingPath:(NSString *)path; + + +#pragma mark - Properties + + +/** + * To modify the data contained by this instance of FIRMutableData, set this to any of the native types supported by Firebase Database: + * + * + NSNumber (includes BOOL) + * + NSDictionary + * + NSArray + * + NSString + * + nil / NSNull to remove the data + * + * Note that setting this value will override the priority at this location. + * + * @return The current data at this location as a native object + */ +@property (strong, nonatomic, nullable) id value; + + +/** + * Set this property to update the priority of the data at this location. Can be set to the following types: + * + * + NSNumber + * + NSString + * + nil / NSNull to remove the priority + * + * @return The priority of the data at this location + */ +@property (strong, nonatomic, nullable) id priority; + + +/** + * @return The number of child nodes at this location + */ +@property (readonly, nonatomic) NSUInteger childrenCount; + + +/** + * Used to iterate over the children at this location. You can use the native for .. in syntax: + * + * for (FIRMutableData* child in data.children) { + * ... + * } + * + * Note that this enumerator operates on an immutable copy of the child list. So, you can modify the instance + * during iteration, but the new additions will not be visible until you get a new enumerator. + */ +@property (readonly, nonatomic, strong) NSEnumerator* children; + + +/** + * @return The key name of this node, or nil if it is the top-most location + */ +@property (readonly, nonatomic, strong, nullable) NSString* key; + + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRServerValue.h b/Firebase/Database/Public/FIRServerValue.h new file mode 100644 index 0000000..f5eadd5 --- /dev/null +++ b/Firebase/Database/Public/FIRServerValue.h @@ -0,0 +1,35 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import "FIRDatabaseSwiftNameSupport.h" + +NS_ASSUME_NONNULL_BEGIN + +/** + * Placeholder values you may write into Firebase Database as a value or priority + * that will automatically be populated by the Firebase Database server. + */ +FIR_SWIFT_NAME(ServerValue) +@interface FIRServerValue : NSObject + +/** + * Placeholder value for the number of milliseconds since the Unix epoch + */ ++ (NSDictionary *) timestamp; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FIRTransactionResult.h b/Firebase/Database/Public/FIRTransactionResult.h new file mode 100644 index 0000000..3c2d39a --- /dev/null +++ b/Firebase/Database/Public/FIRTransactionResult.h @@ -0,0 +1,47 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#import +#import "FIRDatabaseSwiftNameSupport.h" +#import "FIRMutableData.h" + +NS_ASSUME_NONNULL_BEGIN + +/** + * Used for runTransactionBlock:. An FIRTransactionResult instance is a container for the results of the transaction. + */ +FIR_SWIFT_NAME(TransactionResult) +@interface FIRTransactionResult : NSObject + +/** + * Used for runTransactionBlock:. Indicates that the new value should be saved at this location + * + * @param value A FIRMutableData instance containing the new value to be set + * @return An FIRTransactionResult instance that can be used as a return value from the block given to runTransactionBlock: + */ ++ (FIRTransactionResult *)successWithValue:(FIRMutableData *)value; + + +/** + * Used for runTransactionBlock:. Indicates that the current transaction should no longer proceed. + * + * @return An FIRTransactionResult instance that can be used as a return value from the block given to runTransactionBlock: + */ ++ (FIRTransactionResult *) abort; + +@end + +NS_ASSUME_NONNULL_END diff --git a/Firebase/Database/Public/FirebaseDatabase.h b/Firebase/Database/Public/FirebaseDatabase.h new file mode 100644 index 0000000..e52f5d6 --- /dev/null +++ b/Firebase/Database/Public/FirebaseDatabase.h @@ -0,0 +1,29 @@ +/* + * Copyright 2017 Google + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef FirebaseDatabase_h +#define FirebaseDatabase_h + +#import "FIRDatabase.h" +#import "FIRDatabaseQuery.h" +#import "FIRDatabaseReference.h" +#import "FIRDataEventType.h" +#import "FIRDataSnapshot.h" +#import "FIRMutableData.h" +#import "FIRServerValue.h" +#import "FIRTransactionResult.h" + +#endif /* FirebaseDatabase_h */ -- cgit v1.2.3