File Transfer

File transfer in DNP3 is defining using objects from Group 70. The Master API allows you to do several operations related to file transfer:

• Get file info - Retrieve information on an individual file or directory
• Read file - Read a remote file from the outstation asynchronously
• Read directory listing - Read a directory information from the outstation

Get File Info

Information about a single file or directory may be retrieved from outstation using a single method invocation.

Rust

match association.get_file_info(".").await {
    Err(err) => {
        tracing::warn!("Unable to get file info: {err}");
    }
    Ok(info) => {
        print_file_info(info);
    }
}

C

This is possible, but not part of the C example!

C++

// Callback interface
class FileInfoCallback : public dnp3::FileInfoCallback {
    void on_complete(const dnp3::FileInfo& info) override
    {
        print_file_info(info);
    }

    void on_failure(dnp3::FileError error) override
    {
        std::cout << "Error getting file info: " << dnp3::to_string(error) << std::endl;
    }
};

// asynchronously start the operation
channel.get_file_info(assoc, ".", std::make_unique<FileInfoCallback>());

Java

FileInfo info = channel.getFileInfo(association, ".").toCompletableFuture().get();
printFileInfo(info);

C#

var info = await channel.GetFileInfo(association, ".");
PrintFileInfo(info);

Read a File

File data may be asynchronously read from the outstation using a callback interface. Reading a file consists of multiple DNP3 requests. Obtaining an authentication key from the outstation and is optional depending on outstation requirements.

sequenceDiagram Master-->>Outstation: authenticate_file (optional); Outstation-->>Master: response w/ key; Master->>Outstation: read file block (1 of N); Outstation->>Master: response (1 of N); Master->>Outstation: close file; Outstation->>Master: response;

The FileReader interface is used to receive data from the outstation as it is read. Your code is responsible for doing something with this data, e.g. writing it to a local file.

Rust

struct FileLogger;

impl FileReader for FileLogger {
    fn opened(&mut self, size: u32) -> FileAction {
        tracing::info!("File opened - size: {size}");
        FileAction::Continue
    }

    fn block_received(&mut self, block_num: u32, data: &[u8]) -> MaybeAsync<FileAction> {
        tracing::info!("Received block {block_num} with size: {}", data.len());
        MaybeAsync::ready(FileAction::Continue)
    }

    fn aborted(&mut self, err: FileError) {
        tracing::info!("File transfer aborted: {}", err);
    }

    fn completed(&mut self) {
        tracing::info!("File transfer completed");
    }
}

// asynchronously start the transfer
if let Err(err) = association
    .read_file(
        ".", // this reads the root "directory" file but doesn't parse it
        FileReadConfig::default(),
        Box::new(FileLogger),
        None,
    )
    .await
{
    tracing::warn!("Unable to start file transfer: {err}");
}

C

This is possible, but not part of the C example!

C++

// Callback interface
class FileReader : public dnp3::FileReader {
    bool opened(uint32_t size) override {
        std::cout << "File opened - size: " << size << std::endl;
        return true;
    }

    bool block_received(uint32_t block_num, dnp3::ByteIterator& data) override {
        std::cout << "Received file block: " << block_num << std::endl;
        return true;
    }

    void aborted(dnp3::FileError error) override {
        std::cout << "File read aborted: " << dnp3::to_string(error) << std::endl;
    }

    void completed() override {
        std::cout << "File read completed" << std::endl;
    }
};

// asynchronously start the operation
channel.read_file(assoc, ".", dnp3::FileReadConfig::defaults(), std::make_unique<FileReader>());

Java

class LoggingFileReader implements FileReader {
  @Override
  public boolean opened(UInteger size) {
    System.out.println("Opened file - size: " + size);
    return true;
  }

  @Override
  public boolean blockReceived(UInteger blockNum, List<UByte> data) {
    System.out.println("Received file block: " + blockNum);
    return true;
  }

  @Override
  public void aborted(FileError error) {
    System.out.println("Aborted file transfer: " + error);
  }

  @Override
  public void completed() {
    System.out.println("Completed file transfer");
  }
}

// asynchronously start the operation
channel.readFile(association, ".", FileReadConfig.defaults(), new LoggingFileReader());

C#

class FileReader : IFileReader
{
    void IFileReader.Aborted(FileError error)
    {
        Console.WriteLine($"File transfer aborted: {error}");
    }

    bool IFileReader.BlockReceived(uint blockNum, ICollection<byte> data)
    {
        Console.WriteLine($"Received file block {blockNum} with size {data.Count}");
        return true;
    }

    void IFileReader.Completed()
    {
        Console.WriteLine($"File transfer completed");
    }

    bool IFileReader.Opened(uint size)
    {
        Console.WriteLine($"Outstation open file with size: ${size}");
        return true;
    }
}

// asynchronously start the operation
channel.ReadFile(association, ".", FileReadConfig.Defaults(), new FileReader());

tip

There is no need to manually close a file. The master will always attempt to close a file, even if the file operation is aborted by the user.

Read a Directory

A directory listing in DNP3 is just a special kind of file with a special encoding. We implement this feature by starting a background file transfer, accumulating the file data over possibly multiple blocks, and then parsing it into a collection of FileInfo instances.

danger

The default limit for the size of directory file is 2048 bytes. This is a reasonable and safe limit, however, if its too small in your application you can raise this limit using the provided parameter in DirReadConfig.

Rust

match association
    .read_directory(".", DirReadConfig::default(), None)
    .await
{
    Err(err) => {
        tracing::warn!("Unable to read directory: {err}");
    }
    Ok(items) => {
        for info in items {
            print_file_info(info);
        }
    }
}

C

This is possible, but not part of the C example!

C++

// Callback interface
class ReadDirectoryCallback : public dnp3::ReadDirectoryCallback {
    void on_complete(dnp3::FileInfoIterator &iter) override
    {
        while (iter.next()) {
            const auto info = iter.get();
            print_file_info(info);
        }
    }

    void on_failure(dnp3::FileError error) override
    {
        std::cout << "Error reading directory: " << dnp3::to_string(error) << std::endl;
    }
};

// asynchronously start the operation
channel.read_directory(assoc, ".", dnp3::DirReadConfig::defaults(), std::make_unique<ReadDirectoryCallback>());

Java

List<FileInfo> items = channel
        .readDirectory(association, ".", DirReadConfig.defaults())
        .toCompletableFuture().get();
for(FileInfo info : items) {
  printFileInfo(info);
}

C#

var items = await channel.ReadDirectory(association, ".", DirReadConfig.Defaults());
foreach(var info in items)
{
    PrintFileInfo(info);
}