streams.h File Reference

Basic byte stream interfaces. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/objects.h"
#include "gate/strings.h"

Macros
#define	gate_stream_read(stream, buffer, bufferlength, returned)
	Shortcut to gate_stream_t::read.
#define	gate_stream_peek(stream, buffer, bufferlength, returned)
	Shortcut to gate_stream_t::peek.
#define	gate_stream_flush(stream)
	Shortcut to gate_stream_t::flush.
#define	gate_stream_write(stream, buffer, bufferlength, written)
	Shortcut to gate_stream_t::write.
#define	GATE_STREAM_RESOURCE_DEFAULT   0x0000
#define	GATE_STREAM_RESOURCE_INPUT   0x0001
#define	GATE_STREAM_RESOURCE_OUTPUT   0x0002
#define	GATE_STREAM_RESOURCE_ERROR   0x0003
#define	gate_stream_get_resource(stream, resource_type, resource_handle)
	Returns the native resource handle of a stream.
#define	gate_stream_can_read(stream, return_value)
	Shortcut to gate_controlstream_t::can_read.
#define	gate_stream_can_write(stream, return_value)
	Shortcut to gate_controlstream_t::can_write.
#define	gate_stream_get_size(stream, return_value)
	Shortcut to gate_controlstream_t::get_size.
#define	gate_stream_get_available(stream, return_value)
	Shortcut to gate_controlstream_t::get_available.
#define	gate_stream_seek(stream, position, origin, new_position)
	Shortcut to gate_controlstream_t::seek.
#define	gate_stream_reset(stream)
	Shortcut to gate_controlstream_t::reset.
#define	gate_stream_close(stream, close_type)
	Shortcut to gate_controlstream_t::close.
#define	gate_stream_get_position(stream, position)
	Returns the current absolute position within the stream (by using seek(0, CURRENT)
#define	GATE_STREAM_SEEK_BEGIN   0x0000
#define	GATE_STREAM_SEEK_CURRENT   0x0001
#define	GATE_STREAM_SEEK_END   0x0002
#define	GATE_STREAM_CLOSE_DEFAULT   0x0000
#define	GATE_STREAM_CLOSE_INPUT   0x0001
#define	GATE_STREAM_CLOSE_OUTPUT   0x0002
#define	GATE_STREAM_CLOSE_ERROR   0x0003
#define	gate_memstream_get_data(obj)
	Shortcut to gate_memstream_t::get_data.
#define	gate_memstream_size(obj)
	Shortcut to gate_memstream_t::size.
#define	gate_memstream_reserve(obj, space)
	Shortcut to gate_memstream_t::reserve.
#define	gate_memstream_fill(obj, item, count)
	Shortcut to gate_memstream_t::fill.
#define	gate_memstream_discard(obj, count)
	Shortcut to gate_memstream_t::discard.
#define	gate_memstream_discard_back(obj, count)
	Shortcut to gate_memstream_t::discard_back.
#define	gate_memstream_reset(obj)
	Shortcut to gate_memstream_t::reset.
#define	gate_stringstream_get_data(obj)
	Shortcut to gate_stringstream_t::get_data.
#define	gate_stringstream_size(obj)
	Shortcut to gate_stringstream_t::size.
#define	gate_stringstream_get_current_view(obj, ptr_output)
	Shortcut to gate_stringstream_t::get_current_view.
#define	gate_stringstream_to_string(obj, ptr_output)
	Shortcut to gate_stringstream_t::to_string.

Functions
GATE_CORE_API gate_memstream_t *	gate_memstream_create (gate_size_t capacity)
	Creates a new memory stream on heap (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static (void *buffer, gate_size_t capacity, gate_size_t used)
	Creates a memory stream using a static fixed buffer (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static_unmanaged (gate_memstream_impl_t *impl, void *buffer, gate_size_t capacity, gate_size_t used)
	Initializes a memory stream as a local unmanaged structure without reference counting (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static_unmanaged_readonly (gate_memstream_impl_t *impl, void const *buffer, gate_size_t capacity, gate_size_t used)
	Initializes a memory stream as a local unmanaged structure without reference counting (read-only)
GATE_CORE_API gate_controlstream_t *	gate_memstream_create_view (void const *buffer, gate_size_t length, gate_size_t offset, gate_object_t *ptr_container)
	Creates a dynamic read-only control stream object from a memory block.
GATE_CORE_API gate_controlstream_t *	gate_memfilestream_create (gate_size_t prealloc)
	Creates a dynamic read/write control stream object from a memory block.
GATE_CORE_API gate_controlstream_t *	gate_memfilestream_share (gate_controlstream_t *ptr_memfile)
	Creates a new access stream to an existing mem-file stream.
GATE_CORE_API gate_stringstream_t *	gate_stringstream_create (gate_size_t capacity)
	Creates a new string stream object.
GATE_CORE_API gate_stringstream_t *	gate_stringstream_create_builder (gate_strbuilder_t *external_strbuilder)
	Creates a new string stream object from an external string-builder object.
GATE_CORE_API gate_stream_t *	gate_nullstream ()
	Creates a NULL-stream that accepts and discards all write()s and returns 0 bytes on read()s.

Detailed Description

Basic byte stream interfaces.

Macro Definition Documentation

GATE_STREAM_RESOURCE_DEFAULT

#define GATE_STREAM_RESOURCE_DEFAULT   0x0000

Requests the default resource handle of a stream

GATE_STREAM_RESOURCE_INPUT

#define GATE_STREAM_RESOURCE_INPUT   0x0001

Requests the input resource handle of a stream

GATE_STREAM_RESOURCE_OUTPUT

#define GATE_STREAM_RESOURCE_OUTPUT   0x0002

Requests the output resource handle of a stream

GATE_STREAM_RESOURCE_ERROR

#define GATE_STREAM_RESOURCE_ERROR   0x0003

Requests the error resource handle of a stream

gate_stream_get_resource

#define gate_stream_get_resource	(		stream,
			resource_type,
			resource_handle )

Value:

(stream)->vtbl->get_resource((stream), (resource_type), (resource_handle))

Returns the native resource handle of a stream.

Parameters

[in]	stream	Pointer to stream object
[in]	resource_type	GATE_STREAM_RESOURCE_* type of handle to retrieve
[out]	resource_handle	Pointer to output resource handle variable

Returns

GATE_RESULT_* result code

GATE_STREAM_SEEK_BEGIN

#define GATE_STREAM_SEEK_BEGIN   0x0000

Seeks a new access position in stream relative to the absolute BEGIN of the stream

GATE_STREAM_SEEK_CURRENT

#define GATE_STREAM_SEEK_CURRENT   0x0001

Seeks a new access position in stream relative to the CURRENT position of the stream

GATE_STREAM_SEEK_END

#define GATE_STREAM_SEEK_END   0x0002

Seeks a new access position in stream relative to the absolute END of the stream

GATE_STREAM_CLOSE_DEFAULT

#define GATE_STREAM_CLOSE_DEFAULT   0x0000

Closes the stream following the streams defaults

GATE_STREAM_CLOSE_INPUT

#define GATE_STREAM_CLOSE_INPUT   0x0001

Closes the input resources of the stream

GATE_STREAM_CLOSE_OUTPUT

#define GATE_STREAM_CLOSE_OUTPUT   0x0002

Closes the output resources of the stream

GATE_STREAM_CLOSE_ERROR

#define GATE_STREAM_CLOSE_ERROR   0x0003

Closes the error resources of the stream

Function Documentation

gate_memstream_create()

GATE_CORE_API gate_memstream_t * gate_memstream_create

(

gate_size_t

capacity

)

Creates a new memory stream on heap (readable/writable)

Parameters

[in]

capacity

Amount of bytes to preallocate return New memstream instance

gate_memstream_create_static()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static	(	void *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Creates a memory stream using a static fixed buffer (readable/writable)

Parameters

[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_memstream_create_static_unmanaged()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static_unmanaged	(	gate_memstream_impl_t *	impl,
		void *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Initializes a memory stream as a local unmanaged structure without reference counting (readable/writable)

Parameters

[in,out]	impl	Pointer to memstream implementation structure to be initiaized
[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_memstream_create_static_unmanaged_readonly()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static_unmanaged_readonly	(	gate_memstream_impl_t *	impl,
		void const *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Initializes a memory stream as a local unmanaged structure without reference counting (read-only)

Parameters

[in,out]	impl	Pointer to memstream implementation structure to be initiaized
[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_memstream_create_view()

GATE_CORE_API gate_controlstream_t * gate_memstream_create_view	(	void const *	buffer,
		gate_size_t	length,
		gate_size_t	offset,
		gate_object_t *	ptr_container )

Creates a dynamic read-only control stream object from a memory block.

Parameters

[in]	buffer	Pointer to begin of buffer to use
[in]	length	Length of buffer (maximum amount of accessible bytes)
[in]	offset	Initial read-offset inside buffer
[in]	ptr_container	Optional pointer to container object that's lifetime is extended by the new stream return New control stream pointer or NULL in case of allocation error

gate_memfilestream_create()

GATE_CORE_API gate_controlstream_t * gate_memfilestream_create

(

gate_size_t

prealloc

)

Creates a dynamic read/write control stream object from a memory block.

Parameters

[in]

prealloc

Amount of bytes to preallocate in internal storage return New control stream pointer or NULL in case of allocation error

gate_memfilestream_share()

GATE_CORE_API gate_controlstream_t * gate_memfilestream_share

(

gate_controlstream_t *

ptr_memfile

)

Creates a new access stream to an existing mem-file stream.

Parameters

[in]

ptr_memfile

Pointer to existing memfile-stream return New control stream pointer or NULL in case of allocation error

gate_stringstream_create()

GATE_CORE_API gate_stringstream_t * gate_stringstream_create

(

gate_size_t

capacity

)

Creates a new string stream object.

Parameters

[in]

capacity

Amount of bytes to preallocate internally

Returns

new string-stream object

gate_stringstream_create_builder()

GATE_CORE_API gate_stringstream_t * gate_stringstream_create_builder

(

gate_strbuilder_t *

external_strbuilder

)

Creates a new string stream object from an external string-builder object.

Parameters

[in]

external_strbuilder

Pointer to strbuilder object to be imported and used

Returns

new string-stream object

gate_nullstream()

GATE_CORE_API gate_stream_t * gate_nullstream

(

)

Creates a NULL-stream that accepts and discards all write()s and returns 0 bytes on read()s.

Returns

new null stream object