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
34typedef struct QIONetListener QIONetListener;
35typedef struct QIONetListenerClass QIONetListenerClass;
36
37typedef 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 */
51struct 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
66struct 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 */
79QIONetListener *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 */
91void 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 */
106int 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 */
121void 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 */
138void 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 */
154void 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 */
170QIOChannelSocket *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 */
180void 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 */
192bool qio_net_listener_is_connected(QIONetListener *listener);
193
194#endif /* QIO_NET_LISTENER_H */
195