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