Class IStream

Class IStream#

Inheritance Relationships#

Derived Type#

Class Documentation#

class IStream#

Interface used for accessing the data-stream. The underlying contents and length are assumed to remain unchanged while used for reading. Repeated successful reads with the same offset and size must return identical data and byte counts. Implementations of this interface are expected to be thread-safe - it should be possible to call the Read-method from multiple threads simultaneously with independent destination buffers and byte-count storage. Snapshot isolation and detection of external changes are not required; behavior when the underlying data changes is outside this contract. In libCZI-usage, exceptions thrown by Read-method are wrapped into a libCZI::LibCZIIOException-exception, where the exception thrown by the Read-method is stored as the inner exception.

Subclassed by libCZI::IInputOutputStream

Public Functions

virtual void Read(std::uint64_t offset, void *pv, std::uint64_t size, std::uint64_t *ptrBytesRead) = 0#

Reads the specified amount of data at the zero-based byte offset. For valid, supported requests, reads the requested number of bytes unless the end of the stream prevents it. Actual I/O errors must throw; transport-level short reads must not be exposed as successful completion when more requested data is available. A read crossing the end returns the available bytes. A read at or beyond the end, including an empty stream, returns normally with zero bytes. EOF does not prevent later reads at other offsets. On success, only the bytes actually read are written; the rest of the buffer is unchanged. If size is zero, no data is read, the buffer is unchanged, and zero is reported when requested. Argument and backend-limit validation may still fail; a zero-length read is not a reliable existence or connectivity check. Backends may support a narrower range of offsets and sizes than uint64_t. Unsupported requests may throw and must not silently wrap. On an exception the buffer may be partially modified and the byte count is unspecified; no rollback or common exception type is guaranteed.

Parameters:

  • offset – The offset to start reading from.

  • pv – [out] Caller-provided writable storage for at least size bytes. Must be non-null, even if size is zero. Detection of invalid pointers is not guaranteed.

  • size – The size of the buffer.

  • ptrBytesRead – [out] If non-null, receives the number of bytes actually read on success. If null, the same read is performed without reporting its byte count.

virtual ~IStream() = default#