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