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.