Data Streams
PBStream
Opaque object handle: A buffered stream for reading and writing data to and from an arbitrary callback. The buffer is automatically flushed when the stream is deallocated.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBStreamRetain; to decrement the reference count, call PBStreamRelease. These functions are thread-safe.
PBStreamAccessCallback
Callback: The callback for a custom stream type.
Syntax (C/C++)
bool PBStreamAccessCallback(PBUserContext context, bool doWrite,
/* in-out */ uint8_t *_Nullable buffer, size_t *_Nonnull __restrict bufferUsed, size_t bufferCapacity);
You can create a callback of this type from a function pointer with the above signature using PBStreamAccessCallback_Make.
Syntax (Python)
StreamAccessCallback(context, doWrite, buffer) -> (success)
Parameters and Return Values
[in] context (PBUserContext): The context value set when creating the stream.
[in] doWrite (bool): True if this is an attempt to write to the stream. False if this is a read.
[in-out] buffer (mutable array of uint8_t): The data buffer. See the remarks for how this should be used.
[out] success (bool): Whether the access operation succeeded. See the remarks for how this should be used.
Discussion
If doWrite is false, this is a read operation. The buffer's capacity gives the maximum amount of data that should be read. The callback should set the buffer's length to the amount of data that was actually read. A set length of zero indicates the end of the stream has been reached. The return value should be false if the read operation encountered an error that preventing reading any data. However, if no data can be read because the stream was already at its end, then true should be returned and the buffer's length should be set to zero. If false is returned, the buffer's length is ignored.
If doWrite is true, this is a write operation. The buffer's capacity should be ignored, and the buffer's length should not be modified. The buffer's length gives the amount of data to write to the stream. True should be returned if all the data has been written to the stream. False should be returned if not all the data could be written or no data could be written. "Short writes" are not allowed.
See Also
PBStreamCreate
Function: Create a buffered data stream with a custom access callback.
Syntax (C/C++)
PBStreamPtr _Nullable PBStreamCreate(PBStreamAccessCallback accessCallback,
PBUserContext context, int64_t readableSizeInBytes, bool forWriting,
uint32_t bufferSizeInBytes);
Syntax (Python)
StreamCreate(accessCallback, context, readableSizeInBytes, forWriting, bufferSizeInBytes) -> (stream)
Parameters and Return Values
[in] accessCallback (PBStreamAccessCallback): The callback that will be used when the buffer needs to filled for reading, or is full and needs to be written.
[in] context (PBUserContext): The context value that will be passed to the callback.
[in] readableSizeInBytes (int64_t): The total number of bytes that can be read from the stream. If this is not applicable for the type of stream, set this to -1.
[in] forWriting (bool): True if this stream can be written to. False if this stream can be read from.
[in] bufferSizeInBytes (uint32_t): The size of the stream's internal buffer, in bytes. Set to 0 for the default buffer size.
[out] stream (nullable owned PBStream): The created stream, or null if there was not enough memory to create it.
See Also
PBStreamWrite
Function: Write to a buffered stream.
Syntax (C/C++)
bool PBStreamWrite(PBStreamRef stream,
const uint8_t *_Nullable buffer, size_t bufferCount);
Syntax (Python)
StreamWrite(stream, buffer) -> (success)
Parameters and Return Values
[in] stream (referenced PBStream): The stream object.
[in] buffer (referenced array of uint8_t): The data to write to the stream.
[out] success (bool): True if the data could be written to the stream's buffer. False if it could not; this indicates that the buffer was full and could not be flushed.
Discussion
The data may not actually be written until the stream is flushed with PBStreamFlush.
See Also
PBStreamRead
Function: Read from a buffered stream.
Syntax (C/C++)
bool PBStreamRead(PBStreamRef stream,
/* in-out */ uint8_t *_Nullable buffer, size_t *_Nonnull __restrict bufferUsed, size_t bufferCapacity);
Syntax (Python)
StreamRead(stream, buffer) -> (success)
Parameters and Return Values
[in] stream (referenced PBStream): The stream object.
[in-out] buffer (mutable array of uint8_t): The output buffer. The capacity indicates the maximum number of bytes to read. The length will be set to the number of bytes actually read. This will only be less than the capacity if no more data is available to read from the stream.
[out] success (bool): False if the stream reported an error while loading data.
See Also
PBStreamReadQueryField
C-only function:
Syntax (C)
bool PBStreamReadQueryField(PBStreamRef _Nonnull stream, PBBuf *_Nonnull buffer, bool *_Nonnull endOfRecord)
PBStreamWriteQueryString
Function:
Syntax (C/C++)
bool PBStreamWriteQueryString(PBStreamRef stream, ConstStr value,
bool lastFieldInRecord);
Syntax (Python)
StreamWriteQueryString(stream, value, lastFieldInRecord) -> (success)
Parameters and Return Values
[in] stream (referenced PBStream):
[in] value (referenced string):
[in] lastFieldInRecord (bool):
[out] success (bool):
PBStreamWriteQueryI64
Function:
Syntax (C/C++)
bool PBStreamWriteQueryI64(PBStreamRef stream, int64_t value,
bool lastFieldInRecord);
Syntax (Python)
StreamWriteQueryI64(stream, value, lastFieldInRecord) -> (success)
Parameters and Return Values
[in] stream (referenced PBStream):
[in] value (int64_t):
[in] lastFieldInRecord (bool):
[out] success (bool):
PBStreamFlush
Function: Ensure the contents of the stream's buffer has been written.
Syntax (C/C++)
bool PBStreamFlush(PBStreamRef stream);
Syntax (Python)
StreamFlush(stream) -> (success)
Parameters and Return Values
[in] stream (referenced PBStream): The stream object.
[out] success (bool): False if the stream reported an error while writing the data. Otherwise, true.
PBStreamCreateFromResource
Function:
Syntax (C/C++)
PBStreamPtr _Nullable PBStreamCreateFromResource(ConstStr resourceRelativePath);
Syntax (Python)
StreamCreateFromResource(resourceRelativePath) -> (readStream)
Parameters and Return Values
[in] resourceRelativePath (referenced string):
[out] readStream (nullable owned PBStream):
PBStreamGetReadableSize
Function: Get the total number of bytes that can be read from the stream in total.
Syntax (C/C++)
bool PBStreamGetReadableSize(PBStreamRef stream,
/* output */ uint64_t * __restrict readableSizeInBytes);
Syntax (Python)
StreamGetReadableSize(stream) -> (success, readableSizeInBytes)
Parameters and Return Values
[in] stream (referenced PBStream): The stream object.
[out] success (bool): False if the size was not available.
[out] readableSizeInBytes (uint64_t): The readable size, in bytes.
Discussion
This is the total original size; the number of bytes that have already been read is not taken into account.
Some streams, such as "pipes", does not support this operation.
PBStreamSwitchMode
Function:
Syntax (C/C++)
void PBStreamSwitchMode(PBStreamRef stream, bool write);
Syntax (Python)
StreamSwitchMode(stream, write)
Parameters and Return Values
[in] stream (referenced PBStream):
[in] write (bool):
PBStreamCreateFromFD
C-only function: Create a stream from a file descriptor. This takes ownership of the file descriptor, even on failure. The file descriptor will be closed when the stream is deallocated, or if the function fails, the file descriptor will be immediately closed.
The isPipe parameter determines whether the total size of the stream can be queried.
Syntax (C)
PBStream *_Nullable PBStreamCreateFromFD(int fd, bool write, bool isPipe)
PBStreamCreateFromPathMode
Enumeration/bitset of type int32_t: Modes for creating a stream from a file system path.
Constants
PBStreamCreateFromPath_READ
PBStreamCreateFromPath_READ = 1
Read an existing file. This mode can also be used to read from a pipe.
PBStreamCreateFromPath_WRITE_NEW
PBStreamCreateFromPath_WRITE_NEW = 2
Write to a file that does not already exist. If there is however a file at the path, the call fails. On file systems which store a per-file "executable" permission bit, such a bit will not be set for the file.
PBStreamCreateFromPath_WRITE_EXISTING
PBStreamCreateFromPath_WRITE_EXISTING = 3
Write to a file that already exists. If there is however no file at the path, the call fails. The file is truncated to 0 bytes before the stream is returned. The permissions and extended attributes of the file are preserved. This mode can also be used to write to a pipe, in which no truncation occurs.
PBStreamCreateFromPath_WRITE_ALWAYS
PBStreamCreateFromPath_WRITE_ALWAYS = 4
Write to a file, regardless of whether it already exists. If the file needs to be created, on file systems which store a per-file "executable" permission bit, such a bit will not be set for the file. If the file already exists, it is truncated to 0 bytes before the stream is returned. The permissions and extended attributes of the file are preserved. This mode cannot be used to write to a pipe.
See Also
PBStreamCreateFromPath
Function: Create a stream from a file at a given path.
Syntax (C/C++)
PBStreamPtr _Nullable PBStreamCreateFromPath(ConstStr path,
PBStreamCreateFromPathMode mode);
Syntax (Python)
StreamCreateFromPath(path, mode) -> (stream)
Parameters and Return Values
[in] path (referenced string): The path to the file.
[in] mode (PBStreamCreateFromPathMode): Determines whether this is a read or write stream, and how to handle existing files.
[out] stream (nullable owned PBStream): The created stream. Release with PBStreamRelease when no longer needed. This will be null if the call fails.