دانلود فایل ها با Cloud Storage برای C++

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

ایجاد یک مرجع

برای دانلود یک فایل، ابتدا یک مرجع 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. یک URL رشته‌ای ایجاد کنید که فایل را به صورت آنلاین نشان می‌دهد

دانلود در حافظه

با استفاده از متد 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);

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

// 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 دریافت می‌کند که می‌توانید از آن برای مدیریت دانلود خود استفاده کنید. برای اطلاعات بیشتر به مدیریت دانلودها مراجعه کنید.

ایجاد آدرس اینترنتی دانلود

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

// 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 ذخیره شده‌اند را دریافت و به‌روزرسانی کنید .