get_file_metadata

get_file_metadata(std::string filename) returns blaze::file_metadata for a stored application file.

Function variants

blaze::file_metadata get_file_metadata(std::string filename);
blaze::file_metadata get_file_metadata(std::string filename, std::error_code& ec) noexcept;
void async_get_file_metadata(std::string filename, std::function<void(std::error_code, blaze::file_metadata)> callback);
blaze::coro::awaitable_result<blaze::file_metadata> co_get_file_metadata(std::string filename);

Status vs error

file_metadata.status is the API result. std::error_code and std::system_error are used for transport/runtime failures only.

Parameters

Prop

Type

Result

struct file_metadata {
  std::string checksum;
  uint64_t size;
  uint32_t presigned_urls_count;
  std::chrono::seconds last_presigned_url_created_at;
  blaze::status status;

  bool good() const noexcept;
};

Prop

Type

file_metadata.good() is equivalent to status == blaze::status::ok.

Checking returned fields

Missing fields are returned as default values. If result.status != blaze::status::ok, treat metadata fields as optional in practice and check them explicitly.

Field	Practical check
`result.checksum`	`result.checksum.empty()`
`result.size`	Check `result.status == blaze::status::ok` before relying on it. `0` is valid on success for an empty file.
`result.presigned_urls_count`	Check `result.status == blaze::status::ok` before relying on it.
`result.last_presigned_url_created_at`	`result.last_presigned_url_created_at.count() == 0` means no timestamp was provided.

Behavior notes

Call get_file_metadata only after successful connect and initialize.
This operation does not require an authorized license or account context.
checksum describes the whole stored file, not a transfer range.
presigned_urls_count and last_presigned_url_created_at are useful for monitoring download URL generation activity.

Example

Compilation note

Synchronous and Asynchronous examples compile in the same form from C++17 to C++26.

#include "blazeauth/api/api.hpp"

#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string filename = read_line("Filename");

  blaze::session session;

  try {
    const blaze::api_server server = session.connect();
    std::cout << "Connected to server location: " << server.location << '\n';

    const blaze::application app = session.initialize(websocket_api_key, client_id);
    if (!app.good()) {
      print_status("Initialize returned status", app.status);
      return 1;
    }

    const blaze::file_metadata result = session.get_file_metadata(filename);
    if (!result.good()) {
      print_status("Get-file-metadata returned status", result.status);
      return 1;
    }

    std::cout << "Checksum: " << result.checksum << '\n';
    std::cout << "Size: " << result.size << " bytes\n";
    std::cout << "Presigned URL count: " << result.presigned_urls_count << '\n';
    if (result.last_presigned_url_created_at.count() != 0) {
      std::cout << "Last presigned URL created at (unix): "
                << result.last_presigned_url_created_at.count() << '\n';
    } else {
      std::cout << "Last presigned URL created at: never\n";
    }

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Get-file-metadata failed", e.code());
    return 1;
  }

  return 0;
}