## Base Input/Output Object

Base Input/Output Object — A base class with input and output triggers, but no actual read or write methods. Those are left for derived classes to support.

## Synopsis

                        GskIOClass;
                        GskIO;
    gboolean            (*GskIOHookFunc)                    (GskIO *io,
                                                             gpointer data);
    enum                GskIOErrorCause;
    #define             GSK_IO_READ_HOOK                    (io)
    #define             GSK_IO_WRITE_HOOK                   (io)
    #define             gsk_io_block_read                   (io)
    #define             gsk_io_block_write                  (io)
    #define             gsk_io_unblock_read                 (io)
    #define             gsk_io_unblock_write                (io)
    #define             gsk_io_has_read_hook                (io)
    #define             gsk_io_has_write_hook               (io)
    #define             gsk_io_trap_readable                (io, func, shutdown_func, data, destroy)
    #define             gsk_io_trap_writable                (io, func, shutdown_func, data, destroy)
    #define             gsk_io_untrap_readable              (io)
    #define             gsk_io_untrap_writable              (io)
    void                gsk_io_shutdown                     (GskIO *io,
                                                             GError **error);
    #define             gsk_io_read_shutdown                (io, error)
    #define             gsk_io_write_shutdown               (io, error)
    void                gsk_io_close                        (GskIO *io);
    #define             gsk_io_notify_ready_to_read         (io)
    #define             gsk_io_notify_ready_to_write        (io)
    #define             gsk_io_notify_read_shutdown         (io)
    #define             gsk_io_notify_write_shutdown        (io)
    void                gsk_io_notify_shutdown              (GskIO *io);
    void                gsk_io_notify_connected             (GskIO *io);
    #define             gsk_io_is_polling_for_read          (io)
    #define             gsk_io_is_polling_for_write         (io)
    #define             gsk_io_get_is_connecting            (io)
    #define             gsk_io_get_is_readable              (io)
    #define             gsk_io_get_is_writable              (io)
    #define             gsk_io_get_never_partial_reads      (io)
    #define             gsk_io_get_never_partial_writes     (io)
    #define             gsk_io_get_never_blocks_write       (io)
    #define             gsk_io_get_never_blocks_read        (io)
    #define             gsk_io_get_idle_notify_write        (io)
    #define             gsk_io_get_idle_notify_read         (io)
    #define             gsk_io_get_is_open                  (io)
    #define             gsk_io_get_is_read_shutting_down    (io)
    #define             gsk_io_get_is_write_shutting_down   (io)
    #define             gsk_io_get_shutdown_on_error        (io)
    #define             gsk_io_mark_is_connecting           (io)
    #define             gsk_io_mark_is_readable             (io)
    #define             gsk_io_mark_is_writable             (io)
    #define             gsk_io_mark_never_partial_reads     (io)
    #define             gsk_io_mark_never_partial_writes    (io)
    #define             gsk_io_mark_never_blocks_write      (io)
    #define             gsk_io_mark_never_blocks_read       (io)
    #define             gsk_io_mark_idle_notify_write       (io)
    #define             gsk_io_mark_idle_notify_read        (io)
    #define             gsk_io_mark_is_open                 (io)
    #define             gsk_io_mark_shutdown_on_error       (io)
    #define             gsk_io_clear_is_readable            (io)
    #define             gsk_io_clear_is_writable            (io)
    #define             gsk_io_clear_never_partial_reads    (io)
    #define             gsk_io_clear_never_partial_writes   (io)
    #define             gsk_io_clear_idle_notify_write      (io)
    #define             gsk_io_clear_idle_notify_read       (io)
    #define             gsk_io_clear_is_open                (io)
    #define             gsk_io_clear_shutdown_on_error      (io)
    #define             gsk_io_set_idle_notify_write        (io,v)
    #define             gsk_io_set_idle_notify_read         (io,v)
    void                gsk_io_set_error                    (GskIO *io,
                                                             GskIOErrorCause cause,
                                                             GskErrorCode error_code,
                                                             const char *format,
                                                             ...);
    void                gsk_io_set_gerror                   (GskIO *io,
                                                             GskIOErrorCause cause,
                                                             GError *error);
    const char *        gsk_io_error_cause_to_string        (GskIOErrorCause cause);

## Object Hierarchy

      GObject
       +----GskIO
             +----GskPacketQueue
             +----GskStream

## Signals

      "on-connect"                                     : No Recursion
      "on-error"                                       : No Recursion

## Description

The primary feature of this class is that it has two hooks; a read hook and a write hook, and a ton of convenience methods to access them.

## Details

### GskIOClass

    typedef struct {
      GObjectClass object_class;
      /* --- signals (do not override, usually) --- */
      /* Emitted after the connection is made. */
      void       (*on_connect)      (GskIO      *io);
      void       (*on_error)        (GskIO      *io);

      /* --- virtuals --- */
      gboolean   (*open)            (GskIO      *io,
    				 GError    **error);
      void       (*set_poll_read)   (GskIO      *io,
    				 gboolean    do_poll);
      void       (*set_poll_write)  (GskIO      *io,
    				 gboolean    do_poll);
      gboolean   (*shutdown_read)   (GskIO      *io,
    				 GError    **error);
      gboolean   (*shutdown_write)  (GskIO      *io,
    				 GError    **error);
      void       (*close)           (GskIO      *io);
    } GskIOClass;

Methods which derived classes should overload to implement their polling and shutdown strategies.

GObjectClass `object_class`; | The base class (private).
`on_connect` () | This is a signal which is emitted after a connection has been completed.
`on_error` () |
`open` () | Open resources. This is called when the GskIO is constructed.
`set_poll_read` () | This function should turn on/off whether the implementation will call `gsk_io_notify_ready_to_read()`.
`set_poll_write` () | This function should turn on/off whether the implementation will call `gsk_io_notify_ready_to_write()`.
`shutdown_read` () | This function should stop the object from being readable ever again. If applicable, a user's read-trap's shutdown callback will be run.
`shutdown_write` () | This function should stop the object from being writable ever again. If applicable, a user's write-trap's shutdown callback will be run.
`close` () | Deallocate system resources associated with instance.

### GskIO

    typedef struct _GskIO GskIO;

The base class for all input/output objects. It has no public members.

### GskIOHookFunc ()

    gboolean            (*GskIOHookFunc)                    (GskIO *io,
                                                             gpointer data);

A callback which will be run when either the object is ready to read or write, or shutdown in either direction.

`io` : | an object which is ready to read or write
`data` : | the data passed to `gsk_io_trap_readable()` or `gsk_io_trap_writable()`.
Returns : | whether the trap should be kept, otherwise it will be deleted.

### enum GskIOErrorCause

    typedef enum
    {
      GSK_IO_ERROR_NONE,
      GSK_IO_ERROR_INIT,
      GSK_IO_ERROR_CONNECT,
      GSK_IO_ERROR_OPEN,
      GSK_IO_ERROR_READ,
      GSK_IO_ERROR_WRITE,
      GSK_IO_ERROR_POLL_READ,
      GSK_IO_ERROR_POLL_WRITE,
      GSK_IO_ERROR_SHUTDOWN_READ,
      GSK_IO_ERROR_SHUTDOWN_WRITE,
      GSK_IO_ERROR_CLOSE,
      GSK_IO_ERROR_SYNC,
      GSK_IO_ERROR_POLL
    } GskIOErrorCause;

Every GskIO has an GError and a GskIOErrorCause which tells the last error observed on the stream, and what type of action triggered it.

Implementations can use `gsk_io_set_error()` to register an error.

`GSK_IO_ERROR_NONE` | No error has been observed.
`GSK_IO_ERROR_INIT` |
`GSK_IO_ERROR_CONNECT` |
`GSK_IO_ERROR_OPEN` | An error occurred opening the file.
`GSK_IO_ERROR_READ` | An error occurred reading from the file.
`GSK_IO_ERROR_WRITE` |
`GSK_IO_ERROR_POLL_READ` | An error occurred polling for readability.
`GSK_IO_ERROR_POLL_WRITE` | An error occurred polling for writability.
`GSK_IO_ERROR_SHUTDOWN_READ` | An error occurred shutting down the read end.
`GSK_IO_ERROR_SHUTDOWN_WRITE` | An error occurred shutting down the write end.
`GSK_IO_ERROR_CLOSE` | An error occurred closing.
`GSK_IO_ERROR_SYNC` |
`GSK_IO_ERROR_POLL` |

### GSK_IO_READ_HOOK()

    #define             GSK_IO_READ_HOOK(io)

Get a pointer to the GskHook corresponding to the read end of the GskIO.

`io` : | the GskIO which contains the read-hook.

### GSK_IO_WRITE_HOOK()

    #define             GSK_IO_WRITE_HOOK(io)

Get a pointer to the GskHook corresponding to the write end of the GskIO.

`io` : | the GskIO which contains the write-hook.

### gsk_io_block_read()

    #define             gsk_io_block_read(io)

Block the read hook from being triggered.

`io` : | the GskIO whose read hook should be blocked.

### gsk_io_block_write()

    #define             gsk_io_block_write(io)

Block the write hook from being triggered.

`io` : | the GskIO whose write hook should be blocked.

### gsk_io_unblock_read()

    #define             gsk_io_unblock_read(io)

Unblock the read hook from being triggered.

`io` : | the GskIO whose read hook should be unblocked.

### gsk_io_unblock_write()

    #define             gsk_io_unblock_write(io)

Unblock the write hook from being triggered.

`io` : | the GskIO whose write hook should be unblocked.

### gsk_io_has_read_hook()

    #define             gsk_io_has_read_hook(io)

Return whether the read hook is trapped.

`io` : | the GskIO whose read hook should be tested.

### gsk_io_has_write_hook()

    #define             gsk_io_has_write_hook(io)

Return whether the write hook is trapped.

`io` : | the GskIO whose write hook should be tested.

### gsk_io_trap_readable()

    #define             gsk_io_trap_readable(io, func, shutdown_func, data, destroy)

Trap the read end of the GskIO.

Note that only one trap of a GskIO's read-end is allowed at a time.

`io` : | the GskIO whose read end should be trapped.
`func` : | the function to call (a GskIOHookFunc) when it's readable.
`shutdown_func` : | the function to call (a GskIOHookFunc) when it's read end is shut down.
`data` : | data passed along to `func` and `shutdown_func`
`destroy` : | optional function called when the hook is untrapped.

### gsk_io_trap_writable()

    #define             gsk_io_trap_writable(io, func, shutdown_func, data, destroy)

Trap the write end of the GskIO.

Note that only one trap of a GskIO's write-end is allowed at a time.

`io` : | the GskIO whose write end should be trapped.
`func` : | the function to call (a GskIOHookFunc) when it's writable.
`shutdown_func` : | the function to call (a GskIOHookFunc) when it's write end is shut down.
`data` : | data passed along to `func` and `shutdown_func`
`destroy` : | optional function called when the hook is untrapped.

### gsk_io_untrap_readable()

    #define             gsk_io_untrap_readable(io)

Untrap the read end of the GskIO.

`io` : | the GskIO whose read end should be untrapped.

### gsk_io_untrap_writable()

    #define             gsk_io_untrap_writable(io)

Untrap the write end of the GskIO.

`io` : | the GskIO whose write end should be untrapped.

### gsk_io_shutdown ()

    void                gsk_io_shutdown                     (GskIO *io,
                                                             GError **error);

Shutdown the read and write ends of a GskIO.

`io` : | the object which should be shut down.
`error` : | optional error to set upon failure.

### gsk_io_read_shutdown()

    #define             gsk_io_read_shutdown(io, error)

Shutdown both the read ends of the GskIO.

Returns TRUE if the shutdown succeeded immediately.

Returns FALSE if the shutdown has been initiated but not finished, or if an error occurred. These cases can be distinguished by looking at the `error` return.

`io` : | the GskIO to affect.
`error` : | error return if things go wrong.

### gsk_io_write_shutdown()

    #define             gsk_io_write_shutdown(io, error)

Shutdown both the write ends of the GskIO.

Returns FALSE if the shutdown has been initiated but not finished, or if an error occurred. These cases can be distinguished by looking at the `error` return.

`io` : | the GskIO to affect.
`error` : | optional error return if things go wrong.

### gsk_io_close ()

    void                gsk_io_close                        (GskIO *io);

Close an open GskIO.

`io` : | the GskIO to close.

### gsk_io_notify_ready_to_read()

    #define             gsk_io_notify_ready_to_read(io)

Trigger an is-readable event. This should only be called by derived implementations.

`io` : | the GskIO whose read-end is ready.

### gsk_io_notify_ready_to_write()

    #define             gsk_io_notify_ready_to_write(io)

Trigger an is-writable event. This should only be called by derived implementations.

`io` : | the GskIO whose write-end is ready.

### gsk_io_notify_read_shutdown()

    #define             gsk_io_notify_read_shutdown(io)

Trigger a read-end-shutdown event. This should only be called by derived implementations.

`io` : | the GskIO whose read-end is shutdown.

### gsk_io_notify_write_shutdown()

    #define             gsk_io_notify_write_shutdown(io)

Trigger a write-end-shutdown event. This should only be called by derived implementations.

`io` : | the GskIO whose write-end is shutdown.

### gsk_io_notify_shutdown ()

    void                gsk_io_notify_shutdown              (GskIO *io);

This function is called by an implementation when the read- and write- ends of the i/o object have both shut-down.

`io` : | the object which is shut-down.

### gsk_io_notify_connected ()

    void                gsk_io_notify_connected             (GskIO *io);

Trigger an is-connected event. This should only be called by derived implementations. Called to indicate that the connection has been made.

`io` : | the GskIO that finished connecting to the remote side.

### gsk_io_is_polling_for_read()

    #define             gsk_io_is_polling_for_read(io)

Check whether the last invocation of `set_poll_read()` indicated that polling for readability was desired.

`io` : | the IO to query.

### gsk_io_is_polling_for_write()

    #define             gsk_io_is_polling_for_write(io)

Check whether the last invocation of `set_poll_write()` indicated that polling for writability was desired.

`io` : | the IO to query.

### gsk_io_get_is_connecting()

    #define             gsk_io_get_is_connecting(io)

Return whether the GskIO is still connecting. Will be FALSE if the GskIO is never connecting.

`io` : | the GskIO to test.

### gsk_io_get_is_readable()

    #define             gsk_io_get_is_readable(io)

Return whether the GskIO is readable. (It means that the read-end is available-- it does not that there is any data which can be read.)

`io` : | the GskIO to test.

### gsk_io_get_is_writable()

    #define             gsk_io_get_is_writable(io)

Return whether the GskIO is writable. (It means that the write-end is available-- it does not mean that you can necessarily write data.)

`io` : | the GskIO to test.

### gsk_io_get_never_partial_reads()

    #define             gsk_io_get_never_partial_reads(io)

Return whether the GskIO ever reads a partial buffer.

An example of a source which never returns partial data is a virtual source like /dev/zero.

`io` : | the GskIO to test.

### gsk_io_get_never_partial_writes()

    #define             gsk_io_get_never_partial_writes(io)

Return whether the GskIO ever writes a partial buffer.

An example of a source which never writes partial data is a infinite memory buffer, or a sink which merely discards data written to it.

`io` : | the GskIO to test.

### gsk_io_get_never_blocks_write()

    #define             gsk_io_get_never_blocks_write(io)

Return if the GskIO 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.

`io` : | the GskIO to test.

### gsk_io_get_never_blocks_read()

    #define             gsk_io_get_never_blocks_read(io)

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

`io` : | the GskIO to test.

### gsk_io_get_idle_notify_write()

    #define             gsk_io_get_idle_notify_write(io)

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.

`io` : | the GskIO to test.

### gsk_io_get_idle_notify_read()

    #define             gsk_io_get_idle_notify_read(io)

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.

`io` : | the GskIO to test.

### gsk_io_get_is_open()

    #define             gsk_io_get_is_open(io)

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

`io` : | the GskIO to test.

### gsk_io_get_is_read_shutting_down()

    #define             gsk_io_get_is_read_shutting_down(io)

Get whether the read end of the IO is in the process of shutting down.

`io` : | the IO to query.

### gsk_io_get_is_write_shutting_down()

    #define             gsk_io_get_is_write_shutting_down(io)

Get whether the write end of the IO is in the process of shutting down.

`io` : | the IO to query.

### gsk_io_get_shutdown_on_error()

    #define             gsk_io_get_shutdown_on_error(io)

`io` : |

### gsk_io_mark_is_connecting()

    #define             gsk_io_mark_is_connecting(io)

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

`io` : | the GskIO to affect.

### gsk_io_mark_is_readable()

    #define             gsk_io_mark_is_readable(io)

Set whether the GskIO is_readable. This should only be called by the implementations of derived classes. In general, you should not change is_readable more than once in the lifetime of an object; however some types of streams can be made readable again once they are shutdown.

`io` : | the GskIO to affect.

### gsk_io_mark_is_writable()

    #define             gsk_io_mark_is_writable(io)

Set whether the GskIO is_writable. This should only be called by the implementations of derived classes. In general, you should not change is_writable more than once in the lifetime of an object; however some types of streams can be made writable again once they are shutdown.

`io` : | the GskIO to affect.

### gsk_io_mark_never_partial_reads()

    #define             gsk_io_mark_never_partial_reads(io)

Mark the never_partial_reads flag. This means that the read method should never have a partial success. This should therefore only be used by implementations of derived classes.

`io` : | the GskIO to affect.

### gsk_io_mark_never_partial_writes()

    #define             gsk_io_mark_never_partial_writes(io)

Mark the never_partial_writes flag. This means that the write method should never have a partial success. This should therefore only be used by implementations of derived classes.

`io` : | the GskIO to affect.

### gsk_io_mark_never_blocks_write()

    #define             gsk_io_mark_never_blocks_write(io)

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

`io` : | the GskIO to affect.

### gsk_io_mark_never_blocks_read()

    #define             gsk_io_mark_never_blocks_read(io)

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

`io` : | the GskIO to affect.

### gsk_io_mark_idle_notify_write()

    #define             gsk_io_mark_idle_notify_write(io)

Tell the GskIO 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.

`io` : | the GskIO to affect.

### gsk_io_mark_idle_notify_read()

    #define             gsk_io_mark_idle_notify_read(io)

Tell the GskIO 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.

`io` : | the GskIO to affect.

### gsk_io_mark_is_open()

    #define             gsk_io_mark_is_open(io)

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

`io` : | the GskIO to affect.

### gsk_io_mark_shutdown_on_error()

    #define             gsk_io_mark_shutdown_on_error(io)

Cause the GskIO object to be shutdown if it fails.

`io` : | the GskIO object to affect.

### gsk_io_clear_is_readable()

    #define             gsk_io_clear_is_readable(io)

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

`io` : | the GskIO to affect.

### gsk_io_clear_is_writable()

    #define             gsk_io_clear_is_writable(io)

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

`io` : | the GskIO to affect.

### gsk_io_clear_never_partial_reads()

    #define             gsk_io_clear_never_partial_reads(io)

Indicate that the GskIO may exhibit partial reads.

`io` : | the GskIO to affect.

### gsk_io_clear_never_partial_writes()

    #define             gsk_io_clear_never_partial_writes(io)

Indicate that the GskIO may exhibit partial writes.

`io` : | the GskIO to affect.

### gsk_io_clear_idle_notify_write()

    #define             gsk_io_clear_idle_notify_write(io)

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

`io` : | the GskIO to affect.

### gsk_io_clear_idle_notify_read()

    #define             gsk_io_clear_idle_notify_read(io)

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

`io` : | the GskIO to affect.

### gsk_io_clear_is_open()

    #define             gsk_io_clear_is_open(io)

Indicate that the GskIO is closed.

`io` : | the GskIO to affect.

### gsk_io_clear_shutdown_on_error()

    #define             gsk_io_clear_shutdown_on_error(io)

Suppress automatic-shutdown when the stream fails.

`io` : | the stream to affect.

### gsk_io_set_idle_notify_write()

    #define             gsk_io_set_idle_notify_write(io,v)

Set whether to perform idle-notification on the writable end of this GskIO.

`io` : | the IO object to affect.
`v` : | whether to notify.

### gsk_io_set_idle_notify_read()

    #define             gsk_io_set_idle_notify_read(io,v)

Set whether to perform idle-notification on the readable end of this GskIO.

`io` : | the IO object to affect.
`v` : | whether to notify.

### gsk_io_set_error ()

    void                gsk_io_set_error                    (GskIO *io,
                                                             GskIOErrorCause cause,
                                                             GskErrorCode error_code,
                                                             const char *format,
                                                             ...);

Set the error member of the GskIO.

`io` : | the object whose GError member should be set.
`cause` : | what kind of situation triggered the error
`error_code` : | an error code.
`format` : | a printf-like format string.
`...` : | values to be embedded in the format string.

### gsk_io_set_gerror ()

    void                gsk_io_set_gerror                   (GskIO *io,
                                                             GskIOErrorCause cause,
                                                             GError *error);

Set the IO's error member, taking ownership of the `error` parameter.

`io` : | the IO whose error member should be set.
`cause` : | the operation which caused the error.
`error` : | gerror which will be freed by the IO automatically now.

### gsk_io_error_cause_to_string ()

    const char *        gsk_io_error_cause_to_string        (GskIOErrorCause cause);

Convert the GskIOErrorCause code into a human-readable lowercase string.

`cause` : | the cause code.
Returns : | the error as a string.

## Signal Details

### The `"on-connect"` signal

    void                user_function                      (GskIO   *gskio,
                                                            gpointer user_data)      : No Recursion

Signal to indicate that the gsk-io has become connected (to a remote server).

`gskio` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"on-error"` signal

    void                user_function                      (GskIO   *gskio,
                                                            gpointer user_data)      : No Recursion

Signal to indicate that the gsk-io has had an error. Use the 'error' and 'error_cause' members of GskIO to find out what went wrong.

`gskio` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GskHook, GskStream