## gskbufferstream

gskbufferstream — Simple Buffering Stream

## Synopsis

                        GskBufferStreamClass;
                        GskBufferStream;
    GskBufferStream *   gsk_buffer_stream_new               (void);
    #define             gsk_buffer_stream_read_hook         (stream)
    #define             gsk_buffer_stream_write_hook        (stream)
    void                gsk_buffer_stream_read_buffer_changed
                                                            (GskBufferStream *stream);
    void                gsk_buffer_stream_write_buffer_changed
                                                            (GskBufferStream *stream);
    void                gsk_buffer_stream_read_shutdown     (GskBufferStream *stream);
    void                gsk_buffer_stream_changed           (GskBufferStream *stream);
    #define             gsk_buffer_stream_clear_strict_max_write(stream)
    #define             gsk_buffer_stream_has_strict_max_write(stream)
    #define             gsk_buffer_stream_get_max_write_buffer(stream)
    #define             gsk_buffer_stream_peek_write_buffer (stream)
    #define             gsk_buffer_stream_peek_read_buffer  (stream)
    #define             gsk_buffer_stream_mark_strict_max_write(stream)

## Object Hierarchy

      GObject
       +----GskIO
             +----GskStream
                   +----GskBufferStream

## Description

This class provides trivial buffering, and additional hooks to be notified of buffer events.

This class can be used for simple sources where there is minimal need for input/output monitoring. For example, it can be used to proxy for a foreign source. We use it for this purpose in gskopensslbufferstream.c to make a connected pair of a BIO (the SSL i/o abstraction) and a GskStream (which is really a GskBufferStream).

Most functions in the API are intended only for "implementors", that is, users who are using a GskBufferStream as an internal stream. Most users who are given a GskBufferStream which is returned as a GskStream should not use this API, because it may conflict with the way the implementor of the function which returned it expects it to be used.

## Details

### GskBufferStreamClass

    typedef struct {
      GskStreamClass stream_class;

      void (*buffered_read_set_poll) (GskBufferStream *bs, gboolean);
      void (*buffered_write_set_poll) (GskBufferStream *bs, gboolean);
      void (*buffered_read_shutdown) (GskBufferStream *bs);
      void (*buffered_write_shutdown) (GskBufferStream *bs);
    } GskBufferStreamClass;

The class which has the buffer methods.

### GskBufferStream

    typedef struct _GskBufferStream GskBufferStream;

The buffered stream. All of its members are private and should be accessed through the methods below only.

However, for debugging purposes, ....

### gsk_buffer_stream_new ()

    GskBufferStream *   gsk_buffer_stream_new               (void);

Create a new GskBufferStream.

Returns : | the newly allocated GskBufferStream.

### gsk_buffer_stream_read_hook()

    #define             gsk_buffer_stream_read_hook(stream)

Get a pointer to a hook on the buffered-read method. This hook will be triggered as long as the stream's read-hook wants data and the buffer is empty.

`stream` : | the GskBufferStream to get the read-hook for.

### gsk_buffer_stream_write_hook()

    #define             gsk_buffer_stream_write_hook(stream)

Get a pointer to a hook of the buffered-write method. This will be triggered as long as the write-buffer is non-empty.

`stream` : | the GskBufferStream to get the write-hook for.

### gsk_buffer_stream_read_buffer_changed ()

    void                gsk_buffer_stream_read_buffer_changed
                                                            (GskBufferStream *stream);

Called to notify the buffer stream that its read-size has been changed, usually because an implementor has appended data into it for the attached stream to read.

`stream` : | stream whose read buffer has been modified.

### gsk_buffer_stream_write_buffer_changed ()

    void                gsk_buffer_stream_write_buffer_changed
                                                            (GskBufferStream *stream);

Called to notify the buffer stream that its write-buffer has been changed, usually because an implementor has read data from it.

`stream` : | stream whose write buffer has been modified.

### gsk_buffer_stream_read_shutdown ()

    void                gsk_buffer_stream_read_shutdown     (GskBufferStream *stream);

Shutdown the read-end of the buffer-stream, waiting for the buffer to be drained first.

`stream` : | the stream to gracefully shut-down.

### gsk_buffer_stream_changed ()

    void                gsk_buffer_stream_changed           (GskBufferStream *stream);

Do all updates needed to compensate for any user changes to: read_buffer, write_buffer, max_write_buffer.

`stream` : | the stream whose internals have been modified.

### gsk_buffer_stream_clear_strict_max_write()

    #define             gsk_buffer_stream_clear_strict_max_write(stream)

Stop forcing the buffer-writer to be in strict-compliance with the max-write-buffer quantity. In this case, max-write-buffer just used for polling purposes.

`stream` : |

### gsk_buffer_stream_has_strict_max_write()

    #define             gsk_buffer_stream_has_strict_max_write(stream)

Whether the GskBufferStream will strictly enforce the maximum write-buffer threshold by forcing writes beyond the maximum to get clipped (possibly to 0).

`stream` : | the stream to query.

### gsk_buffer_stream_get_max_write_buffer()

    #define             gsk_buffer_stream_get_max_write_buffer(stream)

Get the maximum number of bytes in the write buffer.

`stream` : | the stream to query.

### gsk_buffer_stream_peek_write_buffer()

    #define             gsk_buffer_stream_peek_write_buffer(stream)

Peek at the write-buffer (the buffer where the input `gsk_stream_write()` is appended). Note that you must call `gsk_buffer_stream_write_buffer_changed()` if you change the returned buffer.

`stream` : | the stream whose write-buffer is returned.

### gsk_buffer_stream_peek_read_buffer()

    #define             gsk_buffer_stream_peek_read_buffer(stream)

Peek at the read-buffer (the buffer where the output `gsk_stream_read()` is drain from). Note that you must call `gsk_buffer_stream_read_buffer_changed()` if you change the returned buffer.

`stream` : | the stream whose read-buffer is returned.

### gsk_buffer_stream_mark_strict_max_write()

    #define             gsk_buffer_stream_mark_strict_max_write(stream)

Indicate that strict enforcement of the maximum-write buffer size is desired.

Note that this only affect the write implementation: existing buffered data is retained, and also the implementor can always `gsk_buffer_append()` to cram extra data in.

`stream` : | the stream where the max-write-buffer should be strictly enforced.

## See Also

GskStream.