[Storage] Implement List API across Android, iOS, and Desktop

Added the paginated `List` API to the Firebase Storage C++ SDK.
- Android: Interoperates via JNI with `com/google/firebase/storage/ListResult`.
- iOS: Connects to `FIRStorageListOptions` and `FIRStorageListResult` using Objective-C.
- Desktop: Uses the Firebase Storage REST API `o` endpoint to retrieve folder prefixes and files.

Included integration tests to verify successful nested directory creation, listing results, and pagination via `page_token`.

Co-authored-by: AustinBenoit <22805659+AustinBenoit@users.noreply.github.com>

Author: google-labs-jules[bot]

storage/CMakeLists.txt

@@ -19,6 +19,7 @@ set(common_SRCS
     src/common/common.cc
     src/common/controller.cc
     src/common/listener.cc
+    src/common/list_result.cc
     src/common/metadata.cc
     src/common/storage.cc
     src/common/storage_reference.cc

storage/integration_test/src/integration_test.cc

@@ -1644,4 +1644,84 @@ TEST_F(FirebaseStorageTest, TestInvalidatingReferencesWhenDeletingApp) {
   InitializeAppAndAuth();
 }
 
+TEST_F(FirebaseStorageTest, TestList) {
+  SignIn();
+
+  firebase::storage::StorageReference root = CreateFolder();
+
+  // Create some files and folders
+  std::vector<std::string> file_paths = {
+      "folderA/file1.txt",
+      "folderA/file2.txt",
+      "folderB/file3.txt",
+      "folderC/file4.txt",
+      "rootFile.txt"
+  };
+
+  for (const std::string& path : file_paths) {
+    firebase::storage::StorageReference ref = root.Child(path);
+    WaitForCompletion(RunWithRetry([&]() {
+      return ref.PutBytes(&kSimpleTestFile[0], kSimpleTestFile.size());
+    }), "PutBytes List Test");
+  }
+
+  // Allow some time for index to catch up
+  ProcessEvents(1000);
+
+  // List all at the root of the test folder
+  firebase::Future<firebase::storage::StorageListResult> list_future;
+  WaitForCompletion(RunWithRetry([&]() {
+    list_future = root.List(1000);
+    return list_future;
+  }), "ListRoot");
+
+  EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
+
+  auto list_result = list_future.result();
+  ASSERT_NE(list_result, nullptr);
+
+  // Check prefixes (folders)
+  auto prefixes = list_result->prefixes();
+  EXPECT_EQ(prefixes.size(), 3);
+  int found_prefixes = 0;
+  for (auto& prefix : prefixes) {
+    std::string name = prefix.name();
+    if (name == "folderA" || name == "folderB" || name == "folderC") {
+      found_prefixes++;
+    }
+  }
+  EXPECT_EQ(found_prefixes, 3);
+
+  // Check items (files)
+  auto items = list_result->items();
+  EXPECT_EQ(items.size(), 1);
+  EXPECT_EQ(items[0].name(), "rootFile.txt");
+
+  EXPECT_EQ(list_result->next_page_token(), nullptr);
+
+  // Test pagination
+  firebase::storage::StorageReference folderA = root.Child("folderA");
+  WaitForCompletion(RunWithRetry([&]() {
+    list_future = folderA.List(1);
+    return list_future;
+  }), "ListFolderA_Page1");
+
+  EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
+  list_result = list_future.result();
+  EXPECT_EQ(list_result->items().size(), 1);
+  EXPECT_NE(list_result->next_page_token(), nullptr);
+
+  std::string next_token = list_result->next_page_token();
+
+  WaitForCompletion(RunWithRetry([&]() {
+    list_future = folderA.List(1, next_token.c_str());
+    return list_future;
+  }), "ListFolderA_Page2");
+
+  EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
+  list_result = list_future.result();
+  EXPECT_EQ(list_result->items().size(), 1);
+  EXPECT_EQ(list_result->next_page_token(), nullptr);
+}
+
 }  // namespace firebase_testapp_automated

storage/src/android/storage_reference_android.cc

@@ -33,6 +33,18 @@ namespace firebase {
 namespace storage {
 namespace internal {
 
+// clang-format off
+#define LIST_RESULT_METHODS(X)                                                 \
+  X(GetPrefixes, "getPrefixes", "()Ljava/util/List;"),                         \
+  X(GetItems, "getItems", "()Ljava/util/List;"),                               \
+  X(GetPageToken, "getPageToken", "()Ljava/lang/String;")
+METHOD_LOOKUP_DECLARATION(list_result, LIST_RESULT_METHODS)
+METHOD_LOOKUP_DEFINITION(list_result,
+                         PROGUARD_KEEP_CLASS
+                         "com/google/firebase/storage/ListResult",
+                         LIST_RESULT_METHODS)
+// clang-format on
+
 // clang-format off
 #define STORAGE_REFERENCE_METHODS(X)                                           \
   X(Child, "child",                                                            \
@@ -61,6 +73,8 @@ namespace internal {
   X(PutFileWithMetadata, "putFile",                                            \
     "(Landroid/net/Uri;Lcom/google/firebase/storage/StorageMetadata;)"         \
     "Lcom/google/firebase/storage/UploadTask;"),                               \
+  X(List, "list",                                                              \
+    "(ILjava/lang/String;)Lcom/google/android/gms/tasks/Task;"),               \
   X(PutFileWithMetadataAndUri, "putFile",                                      \
     "(Landroid/net/Uri;Lcom/google/firebase/storage/StorageMetadata;"          \
     "Landroid/net/Uri;)Lcom/google/firebase/storage/UploadTask;"),             \
@@ -105,17 +119,20 @@ enum StorageReferenceFn {
   kStorageReferenceFnUpdateMetadata,
   kStorageReferenceFnPutBytes,
   kStorageReferenceFnPutFile,
+  kStorageReferenceFnList,
   kStorageReferenceFnCount,
 };
 
 bool StorageReferenceInternal::Initialize(App* app) {
   JNIEnv* env = app->GetJNIEnv();
   jobject activity = app->activity();
-  return storage_reference::CacheMethodIds(env, activity);
+  return list_result::CacheMethodIds(env, activity) &&
+         storage_reference::CacheMethodIds(env, activity);
 }
 
 void StorageReferenceInternal::Terminate(App* app) {
   JNIEnv* env = app->GetJNIEnv();
+  list_result::ReleaseClass(env);
   storage_reference::ReleaseClass(env);
   util::CheckAndClearJniExceptions(env);
 }
@@ -249,9 +266,59 @@ void StorageReferenceInternal::FutureCallback(JNIEnv* env, jobject result,
       // is returned.
       data->impl->CompleteWithResult(data->handle, code, message.c_str(),
                                      Metadata(nullptr));
+    } else if (data->func == kStorageReferenceFnList) {
+      data->impl->CompleteWithResult(data->handle, code, message.c_str(),
+                                     StorageListResult(nullptr));
     } else {
       data->impl->Complete(data->handle, code, message.c_str());
     }
+  } else if (result && env->IsInstanceOf(result, list_result::GetClass())) {
+    // result is a ListResult.
+    SafeFutureHandle<StorageListResult> handle(data->handle);
+    jobject prefixes_list = env->CallObjectMethod(
+        result, list_result::GetMethodId(list_result::kGetPrefixes));
+    jobject items_list = env->CallObjectMethod(
+        result, list_result::GetMethodId(list_result::kGetItems));
+    jstring page_token_jstring = static_cast<jstring>(env->CallObjectMethod(
+        result, list_result::GetMethodId(list_result::kGetPageToken)));
+
+    std::vector<StorageReference> prefixes;
+    if (prefixes_list) {
+      jint size = env->CallIntMethod(
+          prefixes_list, list::GetMethodId(list::kSize));
+      for (jint i = 0; i < size; ++i) {
+        jobject prefix_obj = env->CallObjectMethod(
+            prefixes_list, list::GetMethodId(list::kGet), i);
+        prefixes.push_back(
+            StorageReference(new StorageReferenceInternal(data->storage, prefix_obj)));
+        env->DeleteLocalRef(prefix_obj);
+      }
+      env->DeleteLocalRef(prefixes_list);
+    }
+
+    std::vector<StorageReference> items;
+    if (items_list) {
+      jint size = env->CallIntMethod(
+          items_list, list::GetMethodId(list::kSize));
+      for (jint i = 0; i < size; ++i) {
+        jobject item_obj = env->CallObjectMethod(
+            items_list, list::GetMethodId(list::kGet), i);
+        items.push_back(
+            StorageReference(new StorageReferenceInternal(data->storage, item_obj)));
+        env->DeleteLocalRef(item_obj);
+      }
+      env->DeleteLocalRef(items_list);
+    }
+
+    std::string page_token;
+    if (page_token_jstring) {
+      page_token = util::JniStringToString(env, page_token_jstring);
+      env->DeleteLocalRef(page_token_jstring);
+    }
+
+    StorageListResultInternal* list_internal =
+        new StorageListResultInternal(prefixes, items, page_token);
+    data->impl->CompleteWithResult(handle, kErrorNone, StorageListResult(list_internal));
   } else if (result && env->IsInstanceOf(result, util::string::GetClass())) {
     LogDebug("FutureCallback: Completing a Future from a String.");
     // Complete a Future<std::string> from a Java String object.
@@ -687,6 +754,38 @@ Future<Metadata> StorageReferenceInternal::PutFileLastResult() {
       future()->LastResult(kStorageReferenceFnPutFile));
 }
 
+Future<StorageListResult> StorageReferenceInternal::List(int max_results_per_page,
+                                                         const char *page_token) {
+  JNIEnv* env = storage_->app()->GetJNIEnv();
+  ReferenceCountedFutureImpl* future_impl = future();
+  FutureHandle handle =
+      future_impl->Alloc<StorageListResult>(kStorageReferenceFnList);
+
+  jstring java_page_token = page_token ? env->NewStringUTF(page_token) : nullptr;
+  jobject task = env->CallObjectMethod(
+      obj_, storage_reference::GetMethodId(storage_reference::kList),
+      max_results_per_page, java_page_token);
+
+  if (java_page_token) {
+      env->DeleteLocalRef(java_page_token);
+  }
+
+  util::RegisterCallbackOnTask(
+      env, task, FutureCallback,
+      // FutureCallback will delete the newed FutureCallbackData.
+      reinterpret_cast<void*>(new FutureCallbackData(handle, future(), storage_,
+                                                     kStorageReferenceFnList)),
+      storage_->jni_task_id());
+  util::CheckAndClearJniExceptions(env);
+  env->DeleteLocalRef(task);
+  return ListLastResult();
+}
+
+Future<StorageListResult> StorageReferenceInternal::ListLastResult() {
+  return static_cast<const Future<StorageListResult>&>(
+      future()->LastResult(kStorageReferenceFnList));
+}
+
 ReferenceCountedFutureImpl* StorageReferenceInternal::future() {
   return storage_->future_manager().GetFutureApi(this);
 }

storage/src/android/storage_reference_android.h

@@ -129,6 +129,13 @@ class StorageReferenceInternal {
   // Returns the result of the most recent call to PutFile();
   Future<Metadata> PutFileLastResult();
 
+  // List items (files) and prefixes (folders) under this StorageReference.
+  Future<StorageListResult> List(int max_results_per_page,
+                                 const char *page_token);
+
+  // Returns the result of the most recent call to List();
+  Future<StorageListResult> ListLastResult();
+
   // Initialize JNI bindings for this class.
   static bool Initialize(App* app);
   static void Terminate(App* app);

storage/src/common/list_result.cc

@@ -0,0 +1,75 @@
+// Copyright 2024 Google LLC
+//
+// 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.
+
+#include "storage/src/include/firebase/storage/list_result.h"
+#include "storage/src/common/list_result_internal.h"
+
+namespace firebase {
+namespace storage {
+
+StorageListResult::StorageListResult() : internal_(nullptr) {}
+
+StorageListResult::~StorageListResult() {
+  delete internal_;
+  internal_ = nullptr;
+}
+
+StorageListResult::StorageListResult(const StorageListResult& other)
+    : internal_(other.internal_ ? new internal::StorageListResultInternal(*other.internal_) : nullptr) {}
+
+StorageListResult& StorageListResult::operator=(const StorageListResult& other) {
+  if (this == &other) {
+    return *this;
+  }
+  delete internal_;
+  internal_ = other.internal_ ? new internal::StorageListResultInternal(*other.internal_) : nullptr;
+  return *this;
+}
+
+#if defined(FIREBASE_USE_MOVE_OPERATORS) || defined(DOXYGEN)
+StorageListResult::StorageListResult(StorageListResult&& other) {
+  internal_ = other.internal_;
+  other.internal_ = nullptr;
+}
+
+StorageListResult& StorageListResult::operator=(StorageListResult&& other) {
+  if (this == &other) {
+    return *this;
+  }
+  delete internal_;
+  internal_ = other.internal_;
+  other.internal_ = nullptr;
+  return *this;
+}
+#endif  // defined(FIREBASE_USE_MOVE_OPERATORS) || defined(DOXYGEN)
+
+const std::vector<StorageReference>& StorageListResult::prefixes() const {
+  static const std::vector<StorageReference> empty_prefixes;
+  return internal_ ? internal_->prefixes() : empty_prefixes;
+}
+
+const std::vector<StorageReference>& StorageListResult::items() const {
+  static const std::vector<StorageReference> empty_items;
+  return internal_ ? internal_->items() : empty_items;
+}
+
+const char* StorageListResult::next_page_token() const {
+  return internal_ ? internal_->next_page_token() : nullptr;
+}
+
+StorageListResult::StorageListResult(internal::StorageListResultInternal* internal)
+    : internal_(internal) {}
+
+}  // namespace storage
+}  // namespace firebase

storage/src/common/list_result_internal.h

@@ -0,0 +1,57 @@
+// Copyright 2024 Google LLC
+//
+// 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_STORAGE_SRC_COMMON_LIST_RESULT_INTERNAL_H_
+#define FIREBASE_STORAGE_SRC_COMMON_LIST_RESULT_INTERNAL_H_
+
+#include <string>
+#include <vector>
+
+#include "storage/src/include/firebase/storage/storage_reference.h"
+
+namespace firebase {
+namespace storage {
+namespace internal {
+
+/// @brief Internal representation of a StorageListResult.
+class StorageListResultInternal {
+ public:
+  StorageListResultInternal() {}
+  StorageListResultInternal(const std::vector<StorageReference>& prefixes,
+                            const std::vector<StorageReference>& items,
+                            const std::string& next_page_token)
+      : prefixes_(prefixes), items_(items), next_page_token_(next_page_token) {}
+
+  StorageListResultInternal(const StorageListResultInternal& other)
+      : prefixes_(other.prefixes_),
+        items_(other.items_),
+        next_page_token_(other.next_page_token_) {}
+
+  const std::vector<StorageReference>& prefixes() const { return prefixes_; }
+  const std::vector<StorageReference>& items() const { return items_; }
+  const char* next_page_token() const {
+    return next_page_token_.empty() ? nullptr : next_page_token_.c_str();
+  }
+
+ private:
+  std::vector<StorageReference> prefixes_;
+  std::vector<StorageReference> items_;
+  std::string next_page_token_;
+};
+
+}  // namespace internal
+}  // namespace storage
+}  // namespace firebase
+
+#endif  // FIREBASE_STORAGE_SRC_COMMON_LIST_RESULT_INTERNAL_H_