librats::FileTransfer Class Reference

#include <file_transfer.h>

Inheritance diagram for librats::FileTransfer:

Collaboration diagram for librats::FileTransfer:

Classes
struct	Config
struct	FileEntry
	One file inside a transfer (a single-file transfer has exactly one). More...
struct	Offer
	Delivered to the offer callback so the app can accept() or reject(). More...
struct	Progress
	Snapshot passed to the progress callback (both directions). More...
struct	Stats
	Aggregate counters. More...

Public Types
enum class	Status {   Pending , Active , Paused , Completed ,   Failed , Cancelled }
enum class	Direction { Sending , Receiving }
using	OfferHandler = std::function< void(const Offer &)>
using	ProgressHandler = std::function< void(const Progress &)>
using	CompleteHandler = std::function< void(const PeerId &peer, uint64_t id, bool success, const std::string &path)>

Public Member Functions
	FileTransfer (std::string temp_dir=".")
	FileTransfer (Config config)
	~FileTransfer () override
void	on_offer (OfferHandler handler)
void	on_progress (ProgressHandler handler)
void	on_complete (CompleteHandler handler)
uint64_t	send_file (const PeerId &to, const std::string &path)
	Offer a single file. Returns the transfer id (0 if the file is unusable).
uint64_t	send_directory (const PeerId &to, const std::string &dir_path)
	Offer a directory tree. Returns the transfer id (0 if the dir is unusable).
void	accept (const PeerId &from, uint64_t id, const std::string &dest_path)
	Accept an offered transfer.
void	reject (const PeerId &from, uint64_t id)
bool	accept_resume (const PeerId &from, uint64_t id, const std::string &dest_path, const std::string &partial_path)
	Accept a single-file offer, continuing an earlier attempt at the same file.
bool	cancel (const PeerId &peer, uint64_t id)
	Control a live transfer (works from either side); (peer, id) names it.
bool	pause (const PeerId &peer, uint64_t id)
bool	resume (const PeerId &peer, uint64_t id)
Stats	stats () const
void	attach (NodeContext &ctx) override
void	start () override
void	stop () override
Public Member Functions inherited from librats::Subsystem
virtual	~Subsystem ()=default

Static Public Member Functions
static bool	is_safe_relative_path (const std::string &p)
	A relative path from a peer's directory manifest is safe only if it stays inside the destination: non-empty, not absolute, no drive letter, and no "."/".." component.

Detailed Description

Definition at line 80 of file file_transfer.h.

Member Typedef Documentation

CompleteHandler

using librats::FileTransfer::CompleteHandler = std::function<void(const PeerId& peer, uint64_t id, bool success, const std::string& path)>

Definition at line 152 of file file_transfer.h.

OfferHandler

using librats::FileTransfer::OfferHandler = std::function<void(const Offer&)>

Definition at line 146 of file file_transfer.h.

ProgressHandler

using librats::FileTransfer::ProgressHandler = std::function<void(const Progress&)>

Definition at line 147 of file file_transfer.h.

Member Enumeration Documentation

Direction

enum class librats::FileTransfer::Direction

strong

Enumerator
Sending
Receiving

Definition at line 99 of file file_transfer.h.

Status

enum class librats::FileTransfer::Status

strong

Enumerator
Pending
Active
Paused
Completed
Failed
Cancelled

Definition at line 98 of file file_transfer.h.

Constructor & Destructor Documentation

FileTransfer() [1/2]

librats::FileTransfer::FileTransfer ( std::string  temp_dir = "." )

explicit

FileTransfer() [2/2]

librats::FileTransfer::FileTransfer ( Config  config )

explicit

~FileTransfer()

librats::FileTransfer::~FileTransfer ( )

override

Member Function Documentation

accept()

void librats::FileTransfer::accept	(	const PeerId &	from,
		uint64_t	id,
		const std::string &	dest_path
	)

Accept an offered transfer.

For a single file, dest_path is the file path; for a directory, it is the destination directory. (from, id) names the offer.

accept_resume()

bool librats::FileTransfer::accept_resume	(	const PeerId &	from,
		uint64_t	id,
		const std::string &	dest_path,
		const std::string &	partial_path
	)

Accept a single-file offer, continuing an earlier attempt at the same file.

partial_path is both where the bytes already received live and where this attempt keeps writing. The app has to own that path: the internal temp names are keyed by the sender's transfer id, which is a fresh number on every new offer, and an ordinary temp is reclaimed the moment a transfer fails — neither survives to be resumed. A partial handed in here is never deleted on failure, so the next attempt can pick it up.

The receiver asks the sender to start at the partial's length; a sender that ignores the request streams from zero and the partial is discarded (the transfer still succeeds, it just costs the whole file again). The partial must be a prefix of the offered file: nothing checks that up front, and the end-to-end SHA-256 turns a mismatch into a failed transfer after the whole download. A partial at least as long as the offered file is discarded.

partial_path must differ from dest_path: the partial is a scratch file the verified bytes are moved out of, not the destination written in place.

Returns false without accepting anything when (from, id) names no offer, the offer is a directory, it is not a single-file transfer, or partial_path equals dest_path.

attach()

void librats::FileTransfer::attach ( NodeContext &  ctx )

overridevirtual

Implements librats::Subsystem.

cancel()

bool librats::FileTransfer::cancel	(	const PeerId &	peer,
		uint64_t	id
	)

Control a live transfer (works from either side); (peer, id) names it.

is_safe_relative_path()

static bool librats::FileTransfer::is_safe_relative_path ( const std::string &  p )

static

A relative path from a peer's directory manifest is safe only if it stays inside the destination: non-empty, not absolute, no drive letter, and no "."/".." component.

Public + static so it can be unit-tested directly.

on_complete()

void librats::FileTransfer::on_complete ( CompleteHandler  handler )

inline

Definition at line 161 of file file_transfer.h.

on_offer()

void librats::FileTransfer::on_offer ( OfferHandler  handler )

inline

Definition at line 159 of file file_transfer.h.

on_progress()

void librats::FileTransfer::on_progress ( ProgressHandler  handler )

inline

Definition at line 160 of file file_transfer.h.

pause()

bool librats::FileTransfer::pause	(	const PeerId &	peer,
		uint64_t	id
	)

reject()

void librats::FileTransfer::reject	(	const PeerId &	from,
		uint64_t	id
	)

resume()

bool librats::FileTransfer::resume	(	const PeerId &	peer,
		uint64_t	id
	)

send_directory()

uint64_t librats::FileTransfer::send_directory	(	const PeerId &	to,
		const std::string &	dir_path
	)

Offer a directory tree. Returns the transfer id (0 if the dir is unusable).

send_file()

uint64_t librats::FileTransfer::send_file	(	const PeerId &	to,
		const std::string &	path
	)

Offer a single file. Returns the transfer id (0 if the file is unusable).

start()

void librats::FileTransfer::start ( )

overridevirtual

Implements librats::Subsystem.

stats()

Stats librats::FileTransfer::stats

(

)

const

stop()

void librats::FileTransfer::stop ( )

overridevirtual

Implements librats::Subsystem.

---

The documentation for this class was generated from the following file:

• librats/subsystems/file_transfer.h