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