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)                gsk_io_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)                  gsk_io_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)                  gsk_io_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)           gsk_io_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)            gsk_io_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)            gsk_io_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)             gsk_io_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)                      gsk_io_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)          (GSK_STREAM (stream)->never_partial_reads != 0)

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)         (GSK_STREAM (stream)->never_partial_writes != 0)

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)               gsk_io_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.