## Listening for Connections

Listening for Connections — Base class for server-type objects.

## Synopsis

    gboolean            (*GskStreamListenerAcceptFunc)      (GskStream *stream,
                                                             gpointer data,
                                                             GError **error);
    void                (*GskStreamListenerErrorFunc)       (GError *err,
                                                             gpointer data);
                        GskStreamListenerClass;
                        GskStreamListener;
    void                gsk_stream_listener_handle_accept   (GskStreamListener *listener,
                                                             GskStreamListenerAcceptFunc func,
                                                             GskStreamListenerErrorFunc err_func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);
    void                gsk_stream_listener_notify_accepted (GskStreamListener *stream_listener,
                                                             GskStream *new_stream);
    void                gsk_stream_listener_notify_error    (GskStreamListener *stream_listener,
                                                             GError *error);

## Object Hierarchy

      GObject
       +----GskStreamListener
             +----GskStreamListenerSocket

## Description

Derived classes of GskStreamListener provide new GskStreams as connections are accepted. Users can receive notification of this, and usually attach the stream to a new protocol object to handle the connection.

## Details

### GskStreamListenerAcceptFunc ()

    gboolean            (*GskStreamListenerAcceptFunc)      (GskStream *stream,
                                                             gpointer data,
                                                             GError **error);

A method for handling a new connection.

Because `gsk_stream_attach()` automatically adds a reference to the stream, the usual pattern is to do a few `gsk_stream_attach()`s and then `g_object_unref()` from within this callback.

TODO: One can interpret this as meaning that the ownership of the stream is passed through this callback, which is irregular. We will probably fix this by implementing listener attachment with a GskHook and deprecating this API.

`stream` : | the new connection. This should be `g_object_unref()`d eventually be the called code.
`data` : | the data provided to `gsk_stream_listener_handle_accept()`
`error` : | optional error return value.
Returns : | whether everything is ok.

### GskStreamListenerErrorFunc ()

    void                (*GskStreamListenerErrorFunc)       (GError *err,
                                                             gpointer data);

A method for handling a low-level server error.

`err` : | the error which transpired.
`data` : | the data provided to `gsk_stream_listener_handle_accept()`

### GskStreamListenerClass

    typedef struct {
      GObjectClass object_class;
    } GskStreamListenerClass;

The base class of an object which accepts new incoming GskStream's.

GObjectClass `object_class`; | parent class of this class.

### GskStreamListener

    typedef struct _GskStreamListener GskStreamListener;

The base instance of an object which accepts new incoming GskStream's.

### gsk_stream_listener_handle_accept ()

    void                gsk_stream_listener_handle_accept   (GskStreamListener *listener,
                                                             GskStreamListenerAcceptFunc func,
                                                             GskStreamListenerErrorFunc err_func,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

Public interface to trap when new connections are established. Basically, `func` will be called with new streams until an error occurs, then `err_func` and `destroy` will be run.

`listener` : | object to handle accepted connections from.
`func` : | function to call if a connection is accepted.
`err_func` : | function to call if an error occurs.
`data` : | data to be passed to `func` and `err_func`.
`destroy` : | function to be notified with the trap is been undone.

### gsk_stream_listener_notify_accepted ()

    void                gsk_stream_listener_notify_accepted (GskStreamListener *stream_listener,
                                                             GskStream *new_stream);

Called by a derived class to notify the system that a new stream has been accepted.

`stream_listener` : | object which accepted a new connection.
`new_stream` : | the newly accepted input stream.

### gsk_stream_listener_notify_error ()

    void                gsk_stream_listener_notify_error    (GskStreamListener *stream_listener,
                                                             GError *error);

Called by a derived class to notify the system that an error has occurred.

`stream_listener` : | object which has an error.
`error` : | the error which occurred. The *callee* *takes* responsibility for error.