C++ APISession methods
download_file
Downloads a file through a server-issued presigned URL and returns the final file bytes.
download_file requests a one-time download URL from the websocket API and then
downloads file bytes over HTTP.
Function variants
blaze::file download_file(std::string filename, blaze::resume_at from_where = blaze::resume_at{0});
blaze::file download_file(std::string filename, blaze::resume_at from_where, std::error_code& ec) noexcept;
void async_download_file(std::string filename, std::function<void(std::error_code, blaze::file)> callback);
void async_download_file(
std::string filename,
blaze::resume_at from_where,
std::function<void(std::error_code, blaze::file)> callback
);
blaze::coro::awaitable_result<blaze::file> co_download_file(
std::string filename,
blaze::resume_at from_where = blaze::resume_at{}
);Status vs error
file.status is the API/library result. std::error_code and
std::system_error are used for transport/runtime failures only.
Parameters
struct resume_at {
std::int64_t bytes_offset;
};Prop
Type
Result
struct file {
std::vector<std::byte> content;
std::string server_checksum;
blaze::status status{};
bool good() const noexcept;
bool bad_checksum() const noexcept;
};Prop
Type
Behavior notes
download_fileis a single-result operation in all API styles.- Internally the flow is: websocket request -> presigned URL response -> HTTP download.
- Resume mode (
bytes_offset > 0) sends HTTPRange: bytes=<offset>-. - Full-download checksum validation is automatic when server provides checksum metadata.
- Resumed downloads are not auto-validated as full-file integrity by the library.
Checksum behavior
For resume_at{0}, the library compares downloaded bytes hash with server
checksum (when checksum is provided). On mismatch it returns
blaze::status::file_checksum_mismatch.
Example
Compilation note
Synchronous and Asynchronous examples compile in the same form from C++17
to C++26.
#include "blazeauth/api/api.hpp"
#include <fstream>
#include <iostream>
#include <string>
#include <system_error>
#include <vector>
void print_error_code(const std::string& context, const std::error_code& ec) {
std::cout << context << ": " << ec.message() << " ("
<< ec.value() << " : " << ec.category().name() << ")\n";
}
bool write_file(const std::string& path, const std::vector<std::byte>& bytes) {
std::ofstream out(path, std::ios::binary);
if (!out) {
return false;
}
if (!bytes.empty()) {
out.write(reinterpret_cast<const char*>(bytes.data()), static_cast<std::streamsize>(bytes.size()));
}
return static_cast<bool>(out);
}
int main() {
blaze::session session;
try {
const blaze::api_server server = session.connect();
std::cout << "Connected: " << server.location << '\n';
const blaze::application app = session.initialize("your-websocket-api-key", "your-client-id");
if (!app.good()) {
std::cout << "Initialize status: " << blaze::to_string(app.status) << '\n';
return 1;
}
const blaze::license auth = session.authorize("your-license");
if (!auth.good()) {
std::cout << "Authorize status: " << blaze::to_string(auth.status) << '\n';
return 1;
}
const blaze::file file = session.download_file("client.dll");
if (!file.good()) {
std::cout << "Download status: " << blaze::to_string(file.status) << '\n';
return 1;
}
if (!write_file("client.dll", file.content)) {
std::cout << "Failed to write output file\n";
return 1;
}
std::cout << "Downloaded bytes: " << file.content.size() << '\n';
if (!file.server_checksum.empty()) {
std::cout << "Server checksum: " << file.server_checksum << '\n';
}
session.shutdown();
} catch (const std::system_error& e) {
print_error_code("download_file failed", e.code());
return 1;
}
return 0;
}Download-file statuses
| Value | Status | Returned when |
|---|---|---|
1 | ok | Download completed successfully. |
3 | not_authorized | Session is not authorized for file download. |
6 | internal_server_error | Server failed while preparing download data. |
300 | file_not_found | Requested file does not exist. |
301 | file_invalid_name | Filename is invalid (for example too short). |
302 | file_checksum_mismatch | Full-download checksum validation failed in the client library. |
303 | file_invalid_resume_offset | resume_at.bytes_offset is invalid for requested file. |
Connection-level shutdowns
Normal download-file results are returned in file.status. The websocket may
still be closed by session-level guards:
| Close code | Meaning | When it can happen |
|---|---|---|
4200 | not_initialized | download_file was called before a successful initialize. |
4201 | rate_limited | Session or IP rate limiting closed the websocket around this operation. |