Crate virtual_file_transfer

Expand description

Virtual file transfer through Windows drag-and-drop and the clipboard.

This crate allows applications to offer data as files without first writing the contents to temporary files.

File contents are provided on demand using FileSource and SourceReader. On Windows, these are exposed to receiving applications through OLE IDataObject and IStream interfaces.

§Quick start

use std::io::Cursor;
use virtual_file_transfer::{
    begin_drag, FactorySource, SourceReader, VirtualFile,
};

fn start_drag() -> virtual_file_transfer::Result<()> {
    let source = FactorySource::new(|| {
        Ok(SourceReader::seekable(
            Cursor::new(b"hello\n".to_vec())
        ))
    });

    let file = VirtualFile::new(
        "hello.txt",
        Box::new(source),
    )?;

    let _handle = begin_drag(vec![file])?;
    Ok(())
}

Call begin_drag from an appropriate Windows UI event handler. The application must provide a message loop.

§Data sources

A FileSource produces a fresh SourceReader for each request. Sources may read from memory, archives, generated content, or other application-defined storage.

Use SourceReader::streaming for sequential data and SourceReader::seekable when seeking is available.

The optional spool feature provides SourceReader::spooled for explicitly materializing non-seekable data into temporary storage.

§Transfer operations

begin_drag starts an OLE drag-and-drop operation.
copy_to_clipboard exposes virtual files through the system clipboard.
TransferHandle provides cancellation and status information.

A successful drop does not necessarily mean that an asynchronous receiver has finished reading the data. See TransferStatus for completion semantics.

§Platform support

Currently Windows only.

Modules§

windows: Windows-specific APIs, including the lower-level OLE data-object interface. Windows OLE integration for virtual-file transfer.

Structs§

CancellationToken: A shareable token for requesting cooperative transfer cancellation.
ClipboardSession: Keeps a virtual-file clipboard transfer available.
FactorySource: Adapts a reader-producing closure into a FileSource.
PlatformError: A platform-specific failure with a categorized kind and diagnostic message.
SourceReader: Supplies bytes to the receiver as either a sequential or seekable stream.
TransferHandle: Provides cancellation and status inspection for a drag transfer.
TransferRequest: A set of virtual files and a cancellation token for one transfer.
VirtualFile: Describes one virtual file exposed to a receiving application.

Enums§

Error: An error returned by a public transfer or file-definition operation.
FileNameErrorReason: The reason a virtual file name or path component is invalid.
InputError: An invalid file definition or transfer request supplied by the caller.
NativeStatusCode: A platform-specific completion status reported for a transfer.
PlatformErrorKind: The category of an operating-system integration error.
TransferEffect: The data-transfer operation reported by a receiving application.
TransferStatus: The observed state of a drag-and-drop operation.

Traits§

FileSource: A provider of virtual file contents.

Functions§

begin_drag: Starts a Windows OLE drag-and-drop operation for the supplied virtual files.
copy_to_clipboard: Publishes virtual files through the Windows clipboard.

Type Aliases§

Result: Result type used by this crate’s public fallible operations.