include/io/net-listener.h

   1 /*
   2  * QEMU network listener
   3  *
   4  * Copyright (c) 2016-2017 Red Hat, Inc.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #ifndef QIO_NET_LISTENER_H
  22 #define QIO_NET_LISTENER_H
  23
  24 #include "io/channel-socket.h"
  25
  26 #define TYPE_QIO_NET_LISTENER "qio-net-listener"
  27 #define QIO_NET_LISTENER(obj)                                    \
  28     OBJECT_CHECK(QIONetListener, (obj), TYPE_QIO_NET_LISTENER)
  29 #define QIO_NET_LISTENER_CLASS(klass)                                    \
  30     OBJECT_CLASS_CHECK(QIONetListenerClass, klass, TYPE_QIO_NET_LISTENER)
  31 #define QIO_NET_LISTENER_GET_CLASS(obj)                                  \
  32     OBJECT_GET_CLASS(QIONetListenerClass, obj, TYPE_QIO_NET_LISTENER)
  33
  34 typedef struct QIONetListener QIONetListener;
  35 typedef struct QIONetListenerClass QIONetListenerClass;
  36
  37 typedef void (*QIONetListenerClientFunc)(QIONetListener *listener,
  38                                          QIOChannelSocket *sioc,
  39                                          gpointer data);
  40
  41 /**
  42  * QIONetListener:
  43  *
  44  * The QIONetListener object encapsulates the management of a
  45  * listening socket. It is able to listen on multiple sockets
  46  * concurrently, to deal with the scenario where IPv4 / IPv6
  47  * needs separate sockets, or there is a need to listen on a
  48  * subset of interface IP addresses, instead of the wildcard
  49  * address.
  50  */
  51 struct QIONetListener {
  52     Object parent;
  53
  54     char *name;
  55     QIOChannelSocket **sioc;
  56     GSource **io_source;
  57     size_t nsioc;
  58
  59     bool connected;
  60
  61     QIONetListenerClientFunc io_func;
  62     gpointer io_data;
  63     GDestroyNotify io_notify;
  64 };
  65
  66 struct QIONetListenerClass {
  67     ObjectClass parent;
  68 };
  69
  70
  71 /**
  72  * qio_net_listener_new:
  73  *
  74  * Create a new network listener service, which is not
  75  * listening on any sockets initially.
  76  *
  77  * Returns: the new listener
  78  */
  79 QIONetListener *qio_net_listener_new(void);
  80
  81
  82 /**
  83  * qio_net_listener_set_name:
  84  * @listener: the network listener object
  85  * @name: the listener name
  86  *
  87  * Set the name of the listener. This is used as a debugging
  88  * aid, to set names on any GSource instances associated
  89  * with the listener
  90  */
  91 void qio_net_listener_set_name(QIONetListener *listener,
  92                                const char *name);
  93
  94 /**
  95  * qio_net_listener_open_sync:
  96  * @listener: the network listener object
  97  * @addr: the address to listen on
  98  * @num: the amount of expected connections
  99  * @errp: pointer to a NULL initialized error object
 100  *
 101  * Synchronously open a listening connection on all
 102  * addresses associated with @addr. This method may
 103  * also be invoked multiple times, in order to have a
 104  * single listener on multiple distinct addresses.
 105  */
 106 int qio_net_listener_open_sync(QIONetListener *listener,
 107                                SocketAddress *addr,
 108                                int num,
 109                                Error **errp);
 110
 111 /**
 112  * qio_net_listener_add:
 113  * @listener: the network listener object
 114  * @sioc: the socket I/O channel
 115  *
 116  * Associate a listening socket I/O channel with the
 117  * listener. The listener will acquire a new reference
 118  * on @sioc, so the caller should release its own reference
 119  * if it no longer requires the object.
 120  */
 121 void qio_net_listener_add(QIONetListener *listener,
 122                           QIOChannelSocket *sioc);
 123
 124 /**
 125  * qio_net_listener_set_client_func_full:
 126  * @listener: the network listener object
 127  * @func: the callback function
 128  * @data: opaque data to pass to @func
 129  * @notify: callback to free @data
 130  * @context: the context that the sources will be bound to.  If %NULL,
 131  *           the default context will be used.
 132  *
 133  * Register @func to be invoked whenever a new client
 134  * connects to the listener. @func will be invoked
 135  * passing in the QIOChannelSocket instance for the
 136  * client.
 137  */
 138 void qio_net_listener_set_client_func_full(QIONetListener *listener,
 139                                            QIONetListenerClientFunc func,
 140                                            gpointer data,
 141                                            GDestroyNotify notify,
 142                                            GMainContext *context);
 143
 144 /**
 145  * qio_net_listener_set_client_func:
 146  * @listener: the network listener object
 147  * @func: the callback function
 148  * @data: opaque data to pass to @func
 149  * @notify: callback to free @data
 150  *
 151  * Wrapper of qio_net_listener_set_client_func_full(), only that the
 152  * sources will always be bound to default main context.
 153  */
 154 void qio_net_listener_set_client_func(QIONetListener *listener,
 155                                       QIONetListenerClientFunc func,
 156                                       gpointer data,
 157                                       GDestroyNotify notify);
 158
 159 /**
 160  * qio_net_listener_wait_client:
 161  * @listener: the network listener object
 162  *
 163  * Block execution of the caller until a new client arrives
 164  * on one of the listening sockets. If there was previously
 165  * a callback registered with qio_net_listener_set_client_func
 166  * it will be temporarily disabled, and re-enabled afterwards.
 167  *
 168  * Returns: the new client socket
 169  */
 170 QIOChannelSocket *qio_net_listener_wait_client(QIONetListener *listener);
 171
 172
 173 /**
 174  * qio_net_listener_disconnect:
 175  * @listener: the network listener object
 176  *
 177  * Disconnect the listener, removing all I/O callback
 178  * watches and closing the socket channels.
 179  */
 180 void qio_net_listener_disconnect(QIONetListener *listener);
 181
 182
 183 /**
 184  * qio_net_listener_is_connected:
 185  * @listener: the network listener object
 186  *
 187  * Determine if the listener is connected to any socket
 188  * channels
 189  *
 190  * Returns: true if connected, false otherwise
 191  */
 192 bool qio_net_listener_is_connected(QIONetListener *listener);
 193
 194 #endif /* QIO_NET_LISTENER_H */