بارگیری فایل‌ها با Cloud Storage برای C++‎

‫Cloud Storage for Firebase به شما امکان می‌دهد فایل‌ها را به‌سرعت و به‌آسانی از باکت Cloud Storage ارائه‌شده و مدیریت‌شده توسط Firebase بارگیری کنید.

ایجاد مرجع

برای بارگیری فایل، ابتدا مرجع Cloud Storage ایجاد کنید برای فایلی که می‌خواهید بارگیری کنید.

می‌توانید با پیوست کردن مسیرهای فرزند به ریشه Cloud Storage دسته‌بندی خود مرجع ایجاد کنید، یا می‌توانید از gs:// یا https:// نشانی وب موجود که به شیئی در Cloud Storage ارجاع می‌دهد مرجع ایجاد کنید.

// Create a reference with an initial file path and name
StorageReference path_reference = storage->GetReference("images/stars.jpg");

// Create a reference from a Cloud Storage URI
StorageReference gs_reference = storage->GetReferenceFromUrl("gs://bucket/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference https_reference = storage->GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");

بارگیری فایل‌ها

پس‌از اینکه مرجعی داشتید، می‌توانید فایل‌ها را از Cloud Storage به سه روش بارگیری کنید:

  1. بارگیری در میان‌گیری در حافظه
  2. بارگیری در مسیر مشخصی در دستگاه
  3. نشانی وب رشته‌ای تولید کنید که نشان‌دهنده فایل آنلاین باشد

بارگیری در حافظه

فایل را بااستفاده از روش GetBytes() در حافظه در یک بافر بایت بارگیری کنید. این ساده‌ترین راه برای بارگیری سریع فایل است، اما باید کل محتوای فایل را در حافظه بار کند. اگر فایل بزرگ‌تری از حافظه دردسترس برنامه‌تان درخواست کنید، برنامه شما خراب خواهد شد. برای محافظت دربرابر مشکلات حافظه، اندازه بیشینه را روی مقداری تنظیم کنید که می‌دانید برنامه‌تان می‌تواند ازعهده آن برآید، یا از روش بارگیری دیگری استفاده کنید.

// Create a reference to the file you want to download
StorageReference island_ref = storage_ref.Child("images/island.jpg");

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const size_t kMaxAllowedSize = 1 * 1024 * 1024
int8_t byte_buffer[kMaxAllowedSize];
firebase::Future<size_t> future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);

در نقطه‌ای که درخواست انجام شده است اما باید منتظر بمانیم تا «آینده» تکمیل شود و سپس بتوانیم فایل را بخوانیم. ازآنجایی‌که بازی‌ها معمولاً در یک حلقه اجرا می‌شوند و نسبت‌به برنامه‌های دیگر کمتر مبتنی بر تماس برگشتی هستند، معمولاً برای تکمیل نظرسنجی می‌کنید.

// In the game loop that polls for the result...

if (future.status() != firebase::kFutureStatusPending) {
  if (future.status() != firebase::kFutureStatusComplete) {
    LogMessage("ERROR: GetBytes() returned an invalid future.");
    // Handle the error...
  } else if (future.Error() != firebase::storage::kErrorNone) {
    LogMessage("ERROR: GetBytes() returned error %d: %s", future.Error(),
               future.error_message());
    // Handle the error...
  } else {
    // byte_buffer is now populated with data for "images/island.jpg"
  }
}

بارگیری در فایل محلی

روش GetFile() فایل را مستقیماً در دستگاه محلی بارگیری می‌کند. اگر کاربران شما می‌خواهند در حالت آفلاین به فایل دسترسی داشته باشند یا آن را در برنامه دیگری هم‌رسانی کنند، از این گزینه استفاده کنید.

// Create a reference to the file you want to download
StorageReference islandRef = storage_ref.Child("images/island.jpg"];

// Create local filesystem URL
const char* local_url = "file:///local/images/island.jpg";

// Download to the local filesystem
Future<size_t> future = islandRef.GetFile(local_url);

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // The file has been downloaded to local file URL "images/island.jpg"
}

‫GetFile() آرگومان اختیاری Controller را می‌پذیرد که می‌توانید از آن برای مدیریت بارگیری استفاده کنید. برای اطلاعات بیشتر، مدیریت بارگیری‌ها را ببینید.

تولید نشانی وب بارگیری

اگر ازقبل زیرساخت بارگیری براساس نشانی‌های وب دارید، یا فقط می‌خواهید نشانی وبی برای هم‌رسانی داشته باشید، می‌توانید با فراخوانی روش GetDownloadUrl() در مرجع Cloud Storage، نشانی وب بارگیری فایل را دریافت کنید.

// Create a reference to the file you want to download
StorageReference stars_ref = storage_ref.Child("images/stars.jpg");

// Fetch the download URL
firebase::Future<std::string> future = stars_ref.GetDownloadUrl();

// Wait for Future to complete...

if (future.Error() != firebase::storage::kErrorNone) {
  // Uh-oh, an error occurred!
} else {
  // Get the download URL for 'images/stars.jpg'
  std::string download_url = future.Result();
}

مدیریت بارگیری‌ها

علاوه‌بر شروع بارگیری‌ها، می‌توانید بارگیری‌ها را بااستفاده از روش‌های Pause()، Resume()، و Cancel() در Controller موقتاً متوقف کنید، ازسر بگیرید، و لغو کنید، که می‌توانید به‌صورت اختیاری به روش‌های GetBytes() یا GetFile() ارسال کنید.

// Start downloading a file
Controller controller;
storage_ref.Child("images/mountains.jpg").GetFile(local_file, nullptr, &controller);

// Pause the download
controller.Pause();

// Resume the download
controller.Resume();

// Cancel the download
controller.Cancel();

نظارت بر پیشرفت بارگیری

می‌توانید شنوندگانی را به بارگیری‌ها پیوست کنید تا پیشرفت بارگیری را نظارت کنید.

class MyListener : public firebase::storage::Listener {
 public:
  virtual void OnProgress(firebase::storage::Controller* controller) {
    // A progress event occurred
  }
};

{
  // Start uploading a file
  MyEventListener my_listener;
  storage_ref.Child("images/mountains.jpg").GetFile(local_file, my_listener);
}

مدیریت خطاها

دلایل متعددی وجود دارد که ممکن است خطاها در هنگام بارگیری رخ دهند، ازجمله عدم وجود فایل، یا عدم داشتن اجازه کاربر برای دسترسی به فایل موردنظر. اطلاعات بیشتر درباره خطاها را می‌توانید در بخش مدیریت خطاها اسناد پیدا کنید.

مراحل بعدی

همچنین می‌توانید فراداده را دریافت و به‌روز کنید برای فایل‌هایی که در Cloud Storage ذخیره شده‌اند.