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 | |