## Binary Input/Output Stream Base

Binary Input/Output Stream Base — A byte stream. This has methods to read and write data, and it inherits read/write notification from GskStream.

## Synopsis

                        GskStreamClass;
                        GskStream;
    gsize               gsk_stream_read                     (GskStream *stream,
                                                             gpointer buffer,
                                                             gsize buffer_length,
                                                             GError **error);
    gsize               gsk_stream_write                    (GskStream *stream,
                                                             gconstpointer buffer,
                                                             gsize buffer_length,
                                                             GError **error);
    gsize               gsk_stream_read_buffer              (GskStream *stream,
                                                             GskBuffer *buffer,
                                                             GError **error);
    gsize               gsk_stream_write_buffer             (GskStream *stream,
                                                             GskBuffer *buffer,
                                                             GError **error);
    gboolean            gsk_stream_attach                   (GskStream *input_stream,
                                                             GskStream *output_stream,
                                                             GError **error);
    gboolean            gsk_stream_attach_pair              (GskStream *stream_a,
                                                             GskStream *stream_b,
                                                             GError **error);
    #define             gsk_stream_get_is_connecting        (stream)
    #define             gsk_stream_get_is_readable          (stream)
    #define             gsk_stream_get_is_writable          (stream)
    #define             gsk_stream_get_never_blocks_write   (stream)
    #define             gsk_stream_get_never_blocks_read    (stream)
    #define             gsk_stream_get_idle_notify_write    (stream)
    #define             gsk_stream_get_idle_notify_read     (stream)
    #define             gsk_stream_get_is_open              (stream)
    #define             gsk_stream_get_never_partial_reads  (stream)
    #define             gsk_stream_get_never_partial_writes (stream)
    #define             gsk_stream_mark_is_connecting       (stream)
    #define             gsk_stream_mark_is_readable         (stream)
    #define             gsk_stream_mark_is_writable         (stream)
    #define             gsk_stream_mark_never_blocks_write  (stream)
    #define             gsk_stream_mark_never_blocks_read   (stream)
    #define             gsk_stream_mark_idle_notify_write   (stream)
    #define             gsk_stream_mark_idle_notify_read    (stream)
    #define             gsk_stream_mark_is_open             (stream)
    #define             gsk_stream_mark_never_partial_reads (stream)
    #define             gsk_stream_mark_never_partial_writes(stream)
    #define             gsk_stream_clear_is_readable        (stream)
    #define             gsk_stream_clear_is_writable        (stream)
    #define             gsk_stream_clear_is_open            (stream)
    #define             gsk_stream_clear_idle_notify_write  (stream)
    #define             gsk_stream_clear_idle_notify_read   (stream)
    #define             gsk_stream_clear_never_partial_reads(stream)
    #define             gsk_stream_clear_never_partial_writes(stream)
    #define             gsk_stream_trap_readable
    #define             gsk_stream_trap_writable
    #define             gsk_stream_untrap_readable
    #define             gsk_stream_untrap_writable

## Object Hierarchy

      GObject
       +----GskIO
             +----GskStream
                   +----GskStreamFd
                   +----GskStreamSsl
                   +----GskBufferStream
                   +----GskHttpClient
                   +----GskHttpServer

## Description

This encapsulates anything which reads bytes in or writes bytes out. Examples are a unix socket or a http-protocol implementation.

It supports all the richness of GskIO's read/write notification system, along with read and write methods. In particular, (1) you can trap and block read/write separately on the stream. (2) the read/write ends of the stream can be shutdown separately. (3) in general, you may not be able to read/write immediately, but instead may have to trap the appropriate end to know when you can read or write. (4) you may be able to only write or read a partial buffer.

By checking certain flags below, you can assume that the data will never be partial, or that the stream will never block.

## Details

### GskStreamClass

    typedef struct {
      GskIOClass base_class;

      /* --- virtuals --- */
      guint      (*raw_read)        (GskStream     *stream,
    			 	 gpointer       data,
    			 	 guint          length,
    			 	 GError       **error);
      guint      (*raw_write)       (GskStream     *stream,
    			 	 gconstpointer  data,
    			 	 guint          length,
    			 	 GError       **error);
      guint      (*raw_read_buffer) (GskStream     *stream,
    				 GskBuffer     *buffer,
    				 GError       **error);
      guint      (*raw_write_buffer)(GskStream    *stream,
    				 GskBuffer     *buffer,
    				 GError       **error);
    } GskStreamClass;

Functions which may be overridden by derived classes to provide input and output methods.

GskIOClass `base_class`; |
`raw_read` () | function to read raw binary data into a contiguous buffer. This function may not block, but it can return any number of bytes without an error code (even returning 0 does NOT imply end-of-file), or it can return a GError when things go wrong.
`raw_write` () | This function may not block, but it can return any number of bytes without an error code (if it returns 0, it merely means that it does not have space or time for more outgoing data; it is not necessarily an error). Or it can return a GError when things go wrong.
`raw_read_buffer` () | Optional function to read from a stream and transfer it into a buffer, without blocking. This function is provided as an optimization.
`raw_write_buffer` () | Optional function to write to a stream from a buffer, without blocking. This function is provided as an optimization.

### GskStream

    typedef struct _GskStream GskStream;

An input and/or output stream of raw bytes. This has input and output triggers, inherited from GskIO as well as methods to read and write raw bytes.

### gsk_stream_read ()

    gsize               gsk_stream_read                     (GskStream *stream,
                                                             gpointer buffer,
                                                             gsize buffer_length,
                                                             GError **error);

Read up to `buffer_length` bytes into `buffer`, returning the amount read. It may return 0; this does not indicate an end-of-file.

`stream` : | the stream to attempt to read data from.
`buffer` : | the buffer to fill with data.
`buffer_length` : | the maximum data to copy into the buffer.
`error` : | optional place to store a GError if something goes wrong.
Returns : | the number of bytes read into `buffer`.

### gsk_stream_write ()

    gsize               gsk_stream_write                    (GskStream *stream,
                                                             gconstpointer buffer,
                                                             gsize buffer_length,
                                                             GError **error);

Write up to `buffer_length` bytes into `buffer`, returning the amount written. It may return 0; this does not indicate an error by itself.

`stream` : | the stream to attempt to write data to.
`buffer` : | the buffer to write from.
`buffer_length` : | the number of bytes in buffer.
`error` : | optional place to store a GError if something goes wrong.
Returns : | the number of bytes written.

### gsk_stream_read_buffer ()

    gsize               gsk_stream_read_buffer              (GskStream *stream,
                                                             GskBuffer *buffer,
                                                             GError **error);

Read data from the stream directly into a GskBuffer.

`stream` : | the stream to attempt to read data from.
`buffer` : | the buffer to copy data into.
`error` : | optional place to store a GError if something goes wrong.
Returns : | the number of bytes read into `buffer`.

### gsk_stream_write_buffer ()

    gsize               gsk_stream_write_buffer             (GskStream *stream,
                                                             GskBuffer *buffer,
                                                             GError **error);

Write data to the stream directly from a GskBuffer. Data written from the buffer is removed from it.

`stream` : | the stream to attempt to write data to.
`buffer` : | the buffer to get data from.
`error` : | optional place to store a GError if something goes wrong.
Returns : | the number of bytes written from `buffer`.

### gsk_stream_attach ()

    gboolean            gsk_stream_attach                   (GskStream *input_stream,
                                                             GskStream *output_stream,
                                                             GError **error);

Attach the read end of `input_stream` to the write end of `output_stream`, returning an error if anything goes wrong.

`input_stream` : | the input stream whose read-end will be trapped.
`output_stream` : | the output stream whose write-end will be trapped.
`error` : | optional error return location.
Returns : | whether the connection was successful.

### gsk_stream_attach_pair ()

    gboolean            gsk_stream_attach_pair              (GskStream *stream_a,
                                                             GskStream *stream_b,
                                                             GError **error);

Attach a's input to b's output and vice versa.

`stream_a` : | one of the two streams to attach together.
`stream_b` : | one of the two streams to attach together.
`error` : | optional error return location.
Returns : | whether the connection was successful.

### gsk_stream_get_is_connecting()

    #define             gsk_stream_get_is_connecting(stream)

Test whether the stream is connecting.

`stream` : | the stream to test.

### gsk_stream_get_is_readable()

    #define             gsk_stream_get_is_readable(stream)

Test whether the stream is potentially readable. (There may not be any data available at the moment, however.)

`stream` : | the stream to test.

### gsk_stream_get_is_writable()

    #define             gsk_stream_get_is_writable(stream)

Test whether the stream is potentially writable. (you may not be able to write at the moment, however.)

`stream` : | the stream to test.

### gsk_stream_get_never_blocks_write()

    #define             gsk_stream_get_never_blocks_write(stream)

Return if the GskStream will never block to write data. It will always allow some data to be written, until it is full and will allow no more ever.

`stream` : | the stream to test.

### gsk_stream_get_never_blocks_read()

    #define             gsk_stream_get_never_blocks_read(stream)

Return if the GskStream will never block to read data. It will always return some data, until it is empty and will never return any more.

`stream` : | the stream to test.

### gsk_stream_get_idle_notify_write()

    #define             gsk_stream_get_idle_notify_write(stream)

Return whether the write-hook is in idle-notify mode. That means it will be triggered continually, as long as there is a unblocked hook watching it.

`stream` : | the stream to test.

### gsk_stream_get_idle_notify_read()

    #define             gsk_stream_get_idle_notify_read(stream)

Return whether the read-hook is in idle-notify mode. That means it will be triggered continually, as long as there is a unblocked hook watching it.

`stream` : | the stream to test.

### gsk_stream_get_is_open()

    #define             gsk_stream_get_is_open(stream)

Return whether the GskStream is open. A GskStream should be open if you want to use it.

`stream` : | the stream to test.

### gsk_stream_get_never_partial_reads()

    #define             gsk_stream_get_never_partial_reads(stream)

Return whether the GskStream is never allowed to return a partial buffer.

`stream` : | the stream to test.

### gsk_stream_get_never_partial_writes()

    #define             gsk_stream_get_never_partial_writes(stream)

Return whether the GskStream is never allowed to write a partial buffer.

`stream` : | the stream to test.

### gsk_stream_mark_is_connecting()

    #define             gsk_stream_mark_is_connecting(stream)

Set the GskStream's is_connecting flag. This should only be called by the implementations of derived classes. By default, GskStream is not in the connecting state.

`stream` : | the GskStream to affect.

### gsk_stream_mark_is_readable()

    #define             gsk_stream_mark_is_readable(stream)

Set whether the GskStream is_readable. This should only be called by the implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_is_writable()

    #define             gsk_stream_mark_is_writable(stream)

Set whether the GskStream is_writable. This should only be called by the implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_never_blocks_write()

    #define             gsk_stream_mark_never_blocks_write(stream)

Indicate that writing to the GskStream never will block. Once this flag is set it cannot be cleared. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_never_blocks_read()

    #define             gsk_stream_mark_never_blocks_read(stream)

Indicate that reading to the GskStream never will block. Once this flag is set it cannot be cleared. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_idle_notify_write()

    #define             gsk_stream_mark_idle_notify_write(stream)

Tell the GskStream system to continually trigger a user's write hook, if any, assuming it is not blocked. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_idle_notify_read()

    #define             gsk_stream_mark_idle_notify_read(stream)

Tell the GskStream system to continually trigger a user's read hook, if any, assuming it is not blocked. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_is_open()

    #define             gsk_stream_mark_is_open(stream)

Indicate that a GskStream is open. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_mark_never_partial_reads()

    #define             gsk_stream_mark_never_partial_reads(stream)

Indicate that the `gsk_stream_read()` will always read a whole buffer of data.

`stream` : | the GskStream to affect.

### gsk_stream_mark_never_partial_writes()

    #define             gsk_stream_mark_never_partial_writes(stream)

Indicate that the `gsk_stream_write()` and `gsk_stream_write_buffer()` will always finish completely, or give an error.

`stream` : | the GskStream to affect.

### gsk_stream_clear_is_readable()

    #define             gsk_stream_clear_is_readable(stream)

Indicate that a GskStream is no longer readable. In most classes, this condition is permanent. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_clear_is_writable()

    #define             gsk_stream_clear_is_writable(stream)

Indicate that a GskStream is no longer writable. In most classes, this condition is permanent. This should only be used by implementations of derived classes.

`stream` : | the GskStream to affect.

### gsk_stream_clear_is_open()

    #define             gsk_stream_clear_is_open(stream)

Indicate that the GskStream is closed.

`stream` : | the GskStream to affect.

### gsk_stream_clear_idle_notify_write()

    #define             gsk_stream_clear_idle_notify_write(stream)

Stop continually triggering the user's write hook. (This undoes `gsk_stream_mark_idle_notify_write()`)

`stream` : | the GskStream to affect.

### gsk_stream_clear_idle_notify_read()

    #define             gsk_stream_clear_idle_notify_read(stream)

Stop continually triggering the user's read hook. (This undoes `gsk_stream_mark_idle_notify_read()`)

`stream` : | the GskStream to affect.

### gsk_stream_clear_never_partial_reads()

    #define             gsk_stream_clear_never_partial_reads(stream)

Indicate that the GskStream may exhibit partial reads.

`stream` : | the GskStream to affect.

### gsk_stream_clear_never_partial_writes()

    #define             gsk_stream_clear_never_partial_writes(stream)

Indicate that the GskStream may exhibit partial writes.

`stream` : | the GskStream to affect.

### gsk_stream_trap_readable

    #define             gsk_stream_trap_readable

Trap the read end of a stream. See `gsk_io_trap_readable()`.

### gsk_stream_trap_writable

    #define             gsk_stream_trap_writable

Trap the write end of a stream. See `gsk_io_trap_writable()`.

### gsk_stream_untrap_readable

    #define             gsk_stream_untrap_readable

Untrap the read end of a stream. See `gsk_io_untrap_readable()`.

### gsk_stream_untrap_writable

    #define             gsk_stream_untrap_writable

Untrap the write end of a stream. See `gsk_io_untrap_writable()`.

## See Also

GskIO