Struct FileHandler

Source

pub struct FileHandler { /* private fields */ }

Expand description

Handler for file operations

Provides methods for downloading, uploading, updating, and deleting files.

Implementations§

Source §

impl FileHandler

Source

pub fn new(client: FilesClient) -> Self

Creates a new FileHandler

§Arguments

client - FilesClient instance

Source

pub async fn download_file(&self, path: &str) -> Result<FileEntity>

Download a file or get file information

§Arguments

path - File path to download

§Returns

Returns a FileEntity containing file information including a download_uri for the actual file download.

§Examples

use files_sdk::{FilesClient, FileHandler};

let client = FilesClient::builder()
    .api_key("your-api-key")
    .build()?;

let handler = FileHandler::new(client);
let file = handler.download_file("/path/to/file.txt").await?;

if let Some(uri) = file.download_uri {
    println!("Download from: {}", uri);
}

Source

pub async fn download_content(&self, path: &str) -> Result<Vec<u8>>

Download the actual file content as bytes

Unlike download_file() which returns metadata with a download URL, this method fetches and returns the actual file content.

§Arguments

path - File path to download

§Returns

Returns the file content as a Vec<u8>

§Examples

use files_sdk::{FilesClient, FileHandler};

let client = FilesClient::builder()
    .api_key("your-api-key")
    .build()?;

let handler = FileHandler::new(client);
let content = handler.download_content("/path/to/file.txt").await?;
println!("Downloaded {} bytes", content.len());

Source

pub async fn download_to_file( &self, remote_path: &str, local_path: &Path, ) -> Result<()>

Download file content and save to a local file

This is a convenience method that downloads the file content and writes it to the specified local path.

§Arguments

remote_path - Path to the file on Files.com
local_path - Local filesystem path where the file should be saved

§Examples

use files_sdk::{FilesClient, FileHandler};
use std::path::Path;

let client = FilesClient::builder()
    .api_key("your-api-key")
    .build()?;

let handler = FileHandler::new(client);
handler.download_to_file(
    "/path/to/remote/file.txt",
    Path::new("./local/file.txt")
).await?;

Source

pub async fn download_stream<W>( &self, remote_path: &str, writer: &mut W, progress_callback: Option<Arc<dyn ProgressCallback>>, ) -> Result<()>
where W: AsyncWrite + Unpin,

Download file content to an async stream

This method is more memory-efficient than download_content() for large files as it streams the data directly to the writer in chunks instead of loading it into memory.

§Arguments

remote_path - Path to the file on Files.com
writer - An async writer implementing tokio::io::AsyncWrite
progress_callback - Optional callback for progress updates (see progress module)

§Examples

§Basic streaming download

let handler = FileHandler::new(client);

let mut file = File::create("downloaded-large-file.tar.gz").await?;
handler.download_stream(
    "/remote/large-file.tar.gz",
    &mut file,
    None
).await?;

§With progress tracking

let handler = FileHandler::new(client);
let callback = Arc::new(PrintProgressCallback);

let mut file = File::create("large-file.tar.gz").await?;
handler.download_stream(
    "/remote/large-file.tar.gz",
    &mut file,
    Some(callback)
).await?;

§Streaming to any AsyncWrite destination

let handler = FileHandler::new(client);

// Download to memory
let mut buffer = Vec::new();
handler.download_stream(
    "/remote/file.txt",
    &mut buffer,
    None
).await?;

println!("Downloaded {} bytes", buffer.len());

Source

pub async fn get_metadata(&self, path: &str) -> Result<FileEntity>

Get file metadata only (no download URL, no logging)

This is a convenience method that calls FileActionHandler::get_metadata()

§Arguments

path - File path

Source

pub async fn upload_file(&self, path: &str, data: &[u8]) -> Result<FileEntity>

Upload a file (complete two-stage upload process)

This method handles the complete upload process:

Calls begin_upload to get upload URLs
Uploads the file data
Finalizes the upload

§Arguments

path - Destination path for the file
data - File contents as bytes

§Examples

let handler = FileHandler::new(client);

let data = b"Hello, Files.com!";
let file = handler.upload_file("/uploads/test.txt", data).await?;
println!("Uploaded: {:?}", file.path);

Source

pub async fn upload_stream<R>( &self, path: &str, reader: R, size: Option<i64>, progress_callback: Option<Arc<dyn ProgressCallback>>, ) -> Result<FileEntity>
where R: AsyncRead + Unpin,

Upload a file from an async stream

This method is more memory-efficient than upload_file() for large files as it reads the data in chunks (8KB) instead of loading it entirely into memory.

§Arguments

path - Destination path for the file on Files.com
reader - An async reader implementing tokio::io::AsyncRead
size - Optional size of the file in bytes (recommended for progress tracking)
progress_callback - Optional callback for progress updates (see progress module)

§Returns

Returns a FileEntity with the uploaded file’s metadata.

§Examples

§Basic streaming upload

let handler = FileHandler::new(client);

let file = File::open("large-file.tar.gz").await?;
let metadata = file.metadata().await?;
let size = metadata.len() as i64;

handler.upload_stream(
    "/uploads/large-file.tar.gz",
    file,
    Some(size),
    None
).await?;

§With progress tracking

let handler = FileHandler::new(client);
let callback = Arc::new(PrintProgressCallback);

let file = File::open("large-file.tar.gz").await?;
let size = file.metadata().await?.len() as i64;

handler.upload_stream(
    "/uploads/large-file.tar.gz",
    file,
    Some(size),
    Some(callback)
).await?;

§Streaming from any AsyncRead source

let handler = FileHandler::new(client);

// Upload from memory
let data = b"file contents";
let cursor = Cursor::new(data.to_vec());

handler.upload_stream(
    "/uploads/file.txt",
    cursor,
    Some(data.len() as i64),
    None
).await?;

Source

pub async fn update_file( &self, path: &str, custom_metadata: Option<HashMap<String, String>>, provided_mtime: Option<String>, priority_color: Option<String>, ) -> Result<FileEntity>

Update file metadata

§Arguments

path - File path
custom_metadata - Custom metadata key-value pairs (optional)
provided_mtime - Custom modification time (optional)
priority_color - Priority color (optional)

§Examples

let handler = FileHandler::new(client);

let mut metadata = HashMap::new();
metadata.insert("category".to_string(), "reports".to_string());

handler.update_file("/path/to/file.txt", Some(metadata), None, None).await?;

Source

pub async fn delete_file(&self, path: &str, recursive: bool) -> Result<()>

Delete a file

§Arguments

path - File path to delete
recursive - If path is a folder, delete recursively

§Examples

let handler = FileHandler::new(client);
handler.delete_file("/path/to/file.txt", false).await?;

Source

pub async fn copy_file(&self, source: &str, destination: &str) -> Result<()>

Copy a file

This is a convenience method that calls FileActionHandler::copy_file()

§Arguments

source - Source file path
destination - Destination path

Source

pub async fn move_file(&self, source: &str, destination: &str) -> Result<()>

Move a file

This is a convenience method that calls FileActionHandler::move_file()

§Arguments

source - Source file path
destination - Destination path

Source

pub async fn upload_directory( &self, local_dir: &Path, remote_path: &str, mkdir_parents: bool, ) -> Result<Vec<String>>

Upload an entire directory recursively

Walks through a local directory and uploads all files to Files.com, preserving the directory structure.

§Arguments

local_dir - Local directory path to upload
remote_path - Remote destination path on Files.com
mkdir_parents - Create parent directories if they don’t exist

§Returns

Vector of successfully uploaded remote file paths

§Errors

Returns an error if:

Local directory doesn’t exist or isn’t readable
Path contains invalid UTF-8
Any file upload fails

§Examples

use files_sdk::{FilesClient, FileHandler};
use std::path::Path;

let client = FilesClient::builder().api_key("key").build()?;
let handler = FileHandler::new(client);

let uploaded = handler.upload_directory(
    Path::new("./local/images"),
    "/remote/uploads",
    true  // create parent directories
).await?;

println!("Uploaded {} files", uploaded.len());

Source

pub async fn upload_directory_with_progress<F>( &self, local_dir: &Path, remote_path: &str, mkdir_parents: bool, progress: F, ) -> Result<Vec<String>>
where F: Fn(usize, usize),

Upload directory with progress callback

Same as upload_directory but calls a progress callback after each file upload. Useful for showing upload progress in UIs or logging.

§Arguments

local_dir - Local directory path to upload
remote_path - Remote destination path on Files.com
mkdir_parents - Create parent directories if they don’t exist
progress - Callback function called with (current_file_number, total_files)

§Examples

use files_sdk::{FilesClient, FileHandler};
use std::path::Path;

let client = FilesClient::builder().api_key("key").build()?;
let handler = FileHandler::new(client);

handler.upload_directory_with_progress(
    Path::new("./data"),
    "/backups",
    true,
    |current, total| {
        println!("Progress: {}/{} ({:.1}%)",
            current, total, (current as f64 / total as f64) * 100.0);
    }
).await?;