Skip to content

IStream

Jay edited this page Oct 3, 2026 · 2 revisions

IStream

#include <certpp/io/stream.hpp> --- certpp

Interface for input streams.

Methods

virtual ~IStream() = default

static IStreamPtr createMemory(SizeType initialCap = 0)

Create a memory-based stream with the specified initial capacity.

  • initialCap --- The initial capacity of the memory stream in bytes.

Returns: A shared pointer to the created memory stream.

static IStreamPtr createMemory(const SReadOnlyByteSpan& buf)

Create a memory-based stream using the provided buffer.

  • buf --- The buffer to initialize the memory stream with.

Returns: A shared pointer to the created memory stream.

virtual uint32_t capabilities() const = 0

Get the capabilities of the stream.

Returns: The capabilities of the stream as a bitmask of EStreamCapability values.

virtual SizeType capacity() const = 0

Get the capacity of the stream.

Returns: The capacity of the stream in bytes.

virtual SizeType length() const = 0

Get the length of the stream.

Returns: The length of the stream in bytes.

virtual SizeType position() const = 0

Get the current position within the stream.

Returns: The current position in bytes from the beginning of the stream.

virtual ERetCode trimExcess()

Trim any excess capacity from the stream.

Returns: ERetCode indicating success or failure.

virtual ERetCode length(SizeType newLen)

Try to set the length of the stream.

  • newLen --- The new length of the stream in bytes.

Returns: ERetCode indicating success or failure.

virtual ERetCode position(SizeType newPos)

Try to set the current position within the stream.

  • newPos --- The new position in bytes from the beginning of the stream.

Returns: ERetCode indicating success or failure.

virtual ERetCode seek(OffsetType offset, ESeekMode mode) = 0

Seek to a new position within the stream.

  • offset --- The offset to seek to, relative to the position specified by mode.
  • mode --- The seek mode (ESEEK_SET, ESEEK_CUR, ESEEK_END).

Returns: ERetCode indicating success or failure.

virtual size_t read(uint8_t* buf, size_t len) = 0

Read data from the stream into the provided buffer.

  • buf --- The buffer to read data into.
  • len --- The maximum number of bytes to read.

Returns: The number of bytes actually read.

virtual size_t read(SByteSpan& buf)

Read data from the stream into the provided SByteSpan buffer.

  • buf --- The SByteSpan buffer to read data into.

Returns: The number of bytes actually read.

virtual size_t write(const uint8_t* buf, size_t len) = 0

Write data to the stream from the provided buffer.

  • buf --- The buffer containing data to write.
  • len --- The maximum number of bytes to write.

Returns: The number of bytes actually written.

virtual size_t write(const SByteSpan& buf)

Write data to the stream from the provided SByteSpan buffer.

  • buf --- The SByteSpan buffer containing data to write.

Returns: The number of bytes actually written.

virtual ERetCode flush()

Flush any buffered data to the underlying storage.

Returns: ERetCode indicating success or failure.

virtual ERetCode close() = 0

Close the stream.

Returns: ERetCode indicating success or failure.

Example

Obtains a stream from the IStream::createMemory() factory, which is the only way to get one. createMemory() with no argument starts empty, and a write leaves the position at the end -- so reading back what you just wrote needs an explicit seek(), unlike the span overload, which starts already rewound.

// given: SReadOnlyByteSpan content
IStreamPtr stream = IStream::createMemory();
if (!stream) {
    return;
}

if (stream->write(content.data, content.size) != content.size) {
    return;
}

if (stream->seek(0, ESEEK_SET) != ERET_OK) {
    return;
}

uint8_t head[8] = {};
SByteSpan into(head, sizeof(head));
const size_t got = stream->read(into);
if (got == 0) {
    return;   // a short read reports the count; there is no error code on read()
}

if (stream->close() != ERET_OK) {
    return;
}

Reference generated from certpp/io/stream.hpp at commit 0834b29 (v1.0.1). The header is authoritative --- if this page disagrees with it, the header is right and this page needs regenerating.

Clone this wiki locally