Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Comms
  5. pw_transfer
  6. pw::transfer::Handler Class Reference
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Friends | List of all members
pw::transfer::Handler Class Referenceabstract
Comms » pw_transfer

Overview

Base class for transfer handlers.

Transfer handlers connect a transfer resource ID to a data stream, wrapped with initialization and cleanup procedures. Handlers use a pw::stream::Reader or pw::stream::Writer to perform reads and writes, and provide optional Prepare and Finalize methods invoked from the transfer thread.

Inheritance diagram for pw::transfer::Handler:
pw::IntrusiveForwardList< T >::Item pw::transfer::ReadOnlyHandler pw::transfer::ReadWriteHandler pw::transfer::WriteOnlyHandler pw::trace::TraceTransferHandler pw::transfer::AtomicFileTransferHandler

Public Member Functions

constexpr uint32_t id () const
 
virtual Status PrepareRead ()=0
 
virtual Status PrepareRead (uint32_t offset)
 
virtual void FinalizeRead (Status status)
 
virtual Status PrepareWrite ()=0
 
virtual Status PrepareWrite (uint32_t offset)
 
virtual Status FinalizeWrite (Status status)
 
virtual size_t ResourceSize () const
 
virtual Status GetStatus (uint64_t &readable_offset, uint64_t &writeable_offset, uint64_t &read_checksum, uint64_t &write_checksum)
 

Protected Member Functions

constexpr Handler (uint32_t resource_id, stream::Reader *reader)
 
constexpr Handler (uint32_t resource_id, stream::Writer *writer)
 
void set_reader (stream::Reader &reader)
 
void set_writer (stream::Writer &writer)
 
- Protected Member Functions inherited from pw::IntrusiveForwardList< T >::Item
constexpr Item ()=default
 

Friends

class internal::Context
 

Constructor & Destructor Documentation

◆ Handler() [1/2]

constexpr pw::transfer::Handler::Handler ( uint32_t  resource_id,
stream::Reader *  reader 
)
inlineconstexprprotected

Constructs a Handler with an optional initial pw::stream::Reader.

Parameters
[in]resource_idUnique ID of the transferable resource.
[in]readerOptional reader stream to associate with this handler.

◆ Handler() [2/2]

constexpr pw::transfer::Handler::Handler ( uint32_t  resource_id,
stream::Writer *  writer 
)
inlineconstexprprotected

Constructs a Handler with an optional initial pw::stream::Writer.

Parameters
[in]resource_idUnique ID of the transferable resource.
[in]writerOptional writer stream to associate with this handler.

Member Function Documentation

◆ FinalizeRead()

virtual void pw::transfer::Handler::FinalizeRead ( Status  status)
inlinevirtual

Called on the transfer thread at the end of a read transfer.

Parameters
[in]statusOverall status indicating whether the data transfer succeeded.

Reimplemented in pw::transfer::AtomicFileTransferHandler.

◆ FinalizeWrite()

virtual Status pw::transfer::Handler::FinalizeWrite ( Status  status)
inlinevirtual

Called on the transfer thread at the end of a write transfer.

Returning an error signals that the transfer failed, even if data transfer had succeeded up to this point.

Parameters
[in]statusStatus indicating whether the data transfer succeeded up to finalization.
Returns
  • OK: Finalization succeeded.
  • Any error status to fail the transfer.

Reimplemented in pw::transfer::AtomicFileTransferHandler.

◆ GetStatus()

virtual Status pw::transfer::Handler::GetStatus ( uint64_t &  readable_offset,
uint64_t &  writeable_offset,
uint64_t &  read_checksum,
uint64_t &  write_checksum 
)
inlinevirtual

Queries application-defined status metadata for this resource in response to a Transfer.GetResourceStatus RPC.

Parameters
[out]readable_offsetReadable byte offset of the resource.
[out]writeable_offsetWriteable byte offset of the resource.
[out]read_checksumChecksum of readable data.
[out]write_checksumChecksum of written data.
Returns
  • OK: The status fields were populated by the handler.
  • UNIMPLEMENTED: Resource status reporting is not supported by this handler.
  • Any other error status to report to the caller.

◆ id()

constexpr uint32_t pw::transfer::Handler::id ( ) const
inlineconstexpr

Returns the unique identifier for the resource managed by this handler.

Returns
The resource ID.

◆ PrepareRead() [1/2]

virtual Status pw::transfer::Handler::PrepareRead ( )
pure virtual

Called on the transfer thread at the beginning of a read transfer. The pw::stream::Reader must be set and ready to read after a successful PrepareRead() call. Returning a non-OK status aborts the read.

Returns
  • OK: The reader is ready for the transfer.
  • UNIMPLEMENTED: Reads are not supported by this handler.
  • Any other error status to abort the read transfer.

Implemented in pw::transfer::WriteOnlyHandler, pw::transfer::AtomicFileTransferHandler, pw::transfer::ReadOnlyHandler, and pw::transfer::ReadWriteHandler.

◆ PrepareRead() [2/2]

virtual Status pw::transfer::Handler::PrepareRead ( uint32_t  offset)
inlinevirtual

Called on the transfer thread at the beginning of a non-zero-offset read transfer.

Implementations should verify that offset is a valid read point for the resource and position the pw::stream::Reader to read from offset before returning \ref pw::OkStatus() "OK". Returning a non-OK status aborts the read.

Parameters
[in]offsetStarting byte offset for the read transfer.
Returns
  • OK: The reader is positioned at offset and ready for the transfer.
  • UNIMPLEMENTED: Non-zero-offset reads are not supported.
  • RESOURCE_EXHAUSTED: offset is past the end of the stream.
  • Any other error status to abort the read transfer.

◆ PrepareWrite() [1/2]

virtual Status pw::transfer::Handler::PrepareWrite ( )
pure virtual

Called on the transfer thread at the beginning of a write transfer. The pw::stream::Writer must be set and ready to write after a successful PrepareWrite() call. Returning a non-OK status aborts the write.

Returns
  • OK: The writer is ready for the transfer.
  • UNIMPLEMENTED: Writes are not supported by this handler.
  • Any other error status to abort the write transfer.

Implemented in pw::transfer::ReadOnlyHandler, pw::transfer::AtomicFileTransferHandler, pw::transfer::WriteOnlyHandler, and pw::transfer::ReadWriteHandler.

◆ PrepareWrite() [2/2]

virtual Status pw::transfer::Handler::PrepareWrite ( uint32_t  offset)
inlinevirtual

Called on the transfer thread at the beginning of a non-zero-offset write transfer.

Implementations should verify that offset is a valid write point for the resource and prepare the pw::stream::Writer to write at offset before returning \ref pw::OkStatus() "OK". Returning a non-OK status aborts the write.

Parameters
[in]offsetStarting byte offset for the write transfer.
Returns
  • OK: The writer is positioned at offset and ready for the transfer.
  • UNIMPLEMENTED: Non-zero-offset writes are not supported.
  • RESOURCE_EXHAUSTED: offset is past the end of the resource.
  • Any other error status to abort the write transfer.

◆ ResourceSize()

virtual size_t pw::transfer::Handler::ResourceSize ( ) const
inlinevirtual

Returns the total size of the transfer resource in bytes, if known.

Returns
The resource size in bytes, or std::numeric_limits<size_t>::max() if unknown.

◆ set_reader()

void pw::transfer::Handler::set_reader ( stream::Reader &  reader)
inlineprotected

Sets the pw::stream::Reader used by this handler.

Parameters
[in]readerStream from which transfer data will be read.

◆ set_writer()

void pw::transfer::Handler::set_writer ( stream::Writer &  writer)
inlineprotected

Sets the pw::stream::Writer used by this handler.

Parameters
[in]writerStream to which transfer data will be written.
The documentation for this class was generated from the following file: