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 #include "qom/object.h"
  26
  27 #define TYPE_QIO_NET_LISTENER "qio-net-listener"
  28 OBJECT_DECLARE_SIMPLE_TYPE(QIONetListener,
  29                            QIO_NET_LISTENER)
  30
  31
  32 typedef void (*QIONetListenerClientFunc)(QIONetListener *listener,
  33                                          QIOChannelSocket *sioc,
  34                                          gpointer data);
  35
  36 /**
  37  * QIONetListener:
  38  *
  39  * The QIONetListener object encapsulates the management of a
  40  * listening socket. It is able to listen on multiple sockets
  41  * concurrently, to deal with the scenario where IPv4 / IPv6
  42  * needs separate sockets, or there is a need to listen on a
  43  * subset of interface IP addresses, instead of the wildcard
  44  * address.
  45  */
  46 struct QIONetListener {
  47     Object parent;
  48
  49     char *name;
  50     QIOChannelSocket **sioc;
  51     GSource **io_source;
  52     size_t nsioc;
  53
  54     bool connected;
  55
  56     QIONetListenerClientFunc io_func;
  57     gpointer io_data;
  58     GDestroyNotify io_notify;
  59 };
  60
  61
  62
  63 /**
  64  * qio_net_listener_new:
  65  *
  66  * Create a new network listener service, which is not
  67  * listening on any sockets initially.
  68  *
  69  * Returns: the new listener
  70  */
  71 QIONetListener *qio_net_listener_new(void);
  72
  73
  74 /**
  75  * qio_net_listener_set_name:
  76  * @listener: the network listener object
  77  * @name: the listener name
  78  *
  79  * Set the name of the listener. This is used as a debugging
  80  * aid, to set names on any GSource instances associated
  81  * with the listener
  82  */
  83 void qio_net_listener_set_name(QIONetListener *listener,
  84                                const char *name);
  85
  86 /**
  87  * qio_net_listener_open_sync:
  88  * @listener: the network listener object
  89  * @addr: the address to listen on
  90  * @num: the amount of expected connections
  91  * @errp: pointer to a NULL initialized error object
  92  *
  93  * Synchronously open a listening connection on all
  94  * addresses associated with @addr. This method may
  95  * also be invoked multiple times, in order to have a
  96  * single listener on multiple distinct addresses.
  97  */
  98 int qio_net_listener_open_sync(QIONetListener *listener,
  99                                SocketAddress *addr,
 100                                int num,
 101                                Error **errp);
 102
 103 /**
 104  * qio_net_listener_add:
 105  * @listener: the network listener object
 106  * @sioc: the socket I/O channel
 107  *
 108  * Associate a listening socket I/O channel with the
 109  * listener. The listener will acquire a new reference
 110  * on @sioc, so the caller should release its own reference
 111  * if it no longer requires the object.
 112  */
 113 void qio_net_listener_add(QIONetListener *listener,
 114                           QIOChannelSocket *sioc);
 115
 116 /**
 117  * qio_net_listener_set_client_func_full:
 118  * @listener: the network listener object
 119  * @func: the callback function
 120  * @data: opaque data to pass to @func
 121  * @notify: callback to free @data
 122  * @context: the context that the sources will be bound to.  If %NULL,
 123  *           the default context will be used.
 124  *
 125  * Register @func to be invoked whenever a new client
 126  * connects to the listener. @func will be invoked
 127  * passing in the QIOChannelSocket instance for the
 128  * client.
 129  */
 130 void qio_net_listener_set_client_func_full(QIONetListener *listener,
 131                                            QIONetListenerClientFunc func,
 132                                            gpointer data,
 133                                            GDestroyNotify notify,
 134                                            GMainContext *context);
 135
 136 /**
 137  * qio_net_listener_set_client_func:
 138  * @listener: the network listener object
 139  * @func: the callback function
 140  * @data: opaque data to pass to @func
 141  * @notify: callback to free @data
 142  *
 143  * Wrapper of qio_net_listener_set_client_func_full(), only that the
 144  * sources will always be bound to default main context.
 145  */
 146 void qio_net_listener_set_client_func(QIONetListener *listener,
 147                                       QIONetListenerClientFunc func,
 148                                       gpointer data,
 149                                       GDestroyNotify notify);
 150
 151 /**
 152  * qio_net_listener_wait_client:
 153  * @listener: the network listener object
 154  *
 155  * Block execution of the caller until a new client arrives
 156  * on one of the listening sockets. If there was previously
 157  * a callback registered with qio_net_listener_set_client_func
 158  * it will be temporarily disabled, and re-enabled afterwards.
 159  *
 160  * Returns: the new client socket
 161  */
 162 QIOChannelSocket *qio_net_listener_wait_client(QIONetListener *listener);
 163
 164
 165 /**
 166  * qio_net_listener_disconnect:
 167  * @listener: the network listener object
 168  *
 169  * Disconnect the listener, removing all I/O callback
 170  * watches and closing the socket channels.
 171  */
 172 void qio_net_listener_disconnect(QIONetListener *listener);
 173
 174
 175 /**
 176  * qio_net_listener_is_connected:
 177  * @listener: the network listener object
 178  *
 179  * Determine if the listener is connected to any socket
 180  * channels
 181  *
 182  * Returns: true if connected, false otherwise
 183  */
 184 bool qio_net_listener_is_connected(QIONetListener *listener);
 185
 186 #endif /* QIO_NET_LISTENER_H */