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 */ 195