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.