3 files changed, 87 insertions, 0 deletions
diff --git a/Firestore/Source/Public/FIRDocumentReference.h b/Firestore/Source/Public/FIRDocumentReference.h
index e7ba6eb..4aa8c45 100644
--- a/Firestore/Source/Public/FIRDocumentReference.h
+++ b/Firestore/Source/Public/FIRDocumentReference.h
@@ -16,6 +16,7 @@
 
 #import <Foundation/Foundation.h>
 
+#import "FIRFirestoreSource.h"
 #import "FIRListenerRegistration.h"
 
 @class FIRCollectionReference;
@@ -166,12 +167,30 @@ NS_SWIFT_NAME(DocumentReference)
 /**
  * Reads the document referenced by this `FIRDocumentReference`.
  *
+ * This method attempts to provide up-to-date data when possible by waiting for
+ * data from the server, but it may return cached data or fail if you are
+ * offline and the server cannot be reached. See the
+ * `getDocument(source:completion:)` method to change this behavior.
+ *
  * @param completion a block to execute once the document has been successfully read.
  */
 - (void)getDocumentWithCompletion:(FIRDocumentSnapshotBlock)completion
     NS_SWIFT_NAME(getDocument(completion:));
 
 /**
+ * Reads the document referenced by this `FIRDocumentReference`.
+ *
+ * @param source indicates whether the results should be fetched from the cache
+ *     only (`Source.cache`), the server only (`Source.server`), or to attempt
+ *     the server and fall back to the cache (`Source.default`).
+ * @param completion a block to execute once the document has been successfully read.
+ */
+// clang-format off
+- (void)getDocumentWithSource:(FIRFirestoreSource)source completion:(FIRDocumentSnapshotBlock)completion
+    NS_SWIFT_NAME(getDocument(source:completion:));
+// clang-format on
+
+/**
  * Attaches a listener for DocumentSnapshot events.
  *
  * @param listener The listener to attach.
diff --git a/Firestore/Source/Public/FIRFirestoreSource.h b/Firestore/Source/Public/FIRFirestoreSource.h
new file mode 100644
index 0000000..c133747
--- /dev/null
+++ b/Firestore/Source/Public/FIRFirestoreSource.h
@@ -0,0 +1,48 @@
+/*
+ * Copyright 2018 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 <Foundation/Foundation.h>
+
+/**
+ * An enum that configures the behavior of `DocumentReference.getDocument()` and
+ * `Query.getDocuments()`.  By providing a source enum the `getDocument[s]`
+ * methods can be configured to fetch results only from the server, only from
+ * the local cache, or attempt to fetch results from the server and fall back to
+ * the cache (which is the default).
+ *
+ * Setting the source to `Source.default` causes Firestore to try to retrieve an
+ * up-to-date (server-retrieved) snapshot, but fall back to returning cached
+ * data if the server can't be reached.
+ *
+ * Setting the source to `Source.server` causes Firestore to avoid the cache,
+ * generating an error if the server cannot be reached. Note that the cache will
+ * still be updated if the server request succeeds. Also note that
+ * latency-compensation still takes effect, so any pending write operations will
+ * be visible in the returned data (merged into the server-provided data).
+ *
+ * Setting the source to `Source.cache` causes Firestore to immediately return a
+ * value from the cache, ignoring the server completely (implying that the
+ * returned value may be stale with respect to the value on the server). If
+ * there is no data in the cache to satisfy the `getDocument[s]` call,
+ * `DocumentReference.getDocument()` will return an error and
+ * `QuerySnapshot.getDocuments()` will return an empty `QuerySnapshot` with no
+ * documents.
+ */
+typedef NS_ENUM(NSUInteger, FIRFirestoreSource) {
+  FIRFirestoreSourceDefault,
+  FIRFirestoreSourceServer,
+  FIRFirestoreSourceCache
+} NS_SWIFT_NAME(FirestoreSource);
diff --git a/Firestore/Source/Public/FIRQuery.h b/Firestore/Source/Public/FIRQuery.h
index a28af39..946cf06 100644
--- a/Firestore/Source/Public/FIRQuery.h
+++ b/Firestore/Source/Public/FIRQuery.h
@@ -16,6 +16,7 @@
 
 #import <Foundation/Foundation.h>
 
+#import "FIRFirestoreSource.h"
 #import "FIRListenerRegistration.h"
 
 @class FIRFieldPath;
@@ -44,6 +45,11 @@ NS_SWIFT_NAME(Query)
 /**
  * Reads the documents matching this query.
  *
+ * This method attempts to provide up-to-date data when possible by waiting for
+ * data from the server, but it may return cached data or fail if you are
+ * offline and the server cannot be reached. See the
+ * `getDocuments(source:completion:)` method to change this behavior.
+ *
  * @param completion a block to execute once the documents have been successfully read.
  *     documentSet will be `nil` only if error is `non-nil`.
  */
@@ -51,6 +57,20 @@ NS_SWIFT_NAME(Query)
     NS_SWIFT_NAME(getDocuments(completion:));
 
 /**
+ * Reads the documents matching this query.
+ *
+ * @param source indicates whether the results should be fetched from the cache
+ *     only (`Source.cache`), the server only (`Source.server`), or to attempt
+ *     the server and fall back to the cache (`Source.default`).
+ * @param completion a block to execute once the documents have been successfully read.
+ *     documentSet will be `nil` only if error is `non-nil`.
+ */
+// clang-format off
+- (void)getDocumentsWithSource:(FIRFirestoreSource)source completion:(FIRQuerySnapshotBlock)completion
+    NS_SWIFT_NAME(getDocuments(source:completion:));
+// clang-format on
+
+/**
  * Attaches a listener for QuerySnapshot events.
  *
  * @param listener The listener to attach.