qemu

net-listener.h (5760B)

---

 /*
  * QEMU network listener
  *
  * Copyright (c) 2016-2017 Red Hat, Inc.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License along
  * with this program; if not, see <http://www.gnu.org/licenses/>.
  *
  */
 
 #ifndef QIO_NET_LISTENER_H
 #define QIO_NET_LISTENER_H
 
 #include "io/channel-socket.h"
 #include "qom/object.h"
 
 #define TYPE_QIO_NET_LISTENER "qio-net-listener"
 OBJECT_DECLARE_SIMPLE_TYPE(QIONetListener,
                            QIO_NET_LISTENER)
 
 
 typedef void (*QIONetListenerClientFunc)(QIONetListener *listener,
                                          QIOChannelSocket *sioc,
                                          gpointer data);
 
 /**
  * QIONetListener:
  *
  * The QIONetListener object encapsulates the management of a
  * listening socket. It is able to listen on multiple sockets
  * concurrently, to deal with the scenario where IPv4 / IPv6
  * needs separate sockets, or there is a need to listen on a
  * subset of interface IP addresses, instead of the wildcard
  * address.
  */
 struct QIONetListener {
     Object parent;
 
     char *name;
     QIOChannelSocket **sioc;
     GSource **io_source;
     size_t nsioc;
 
     bool connected;
 
     QIONetListenerClientFunc io_func;
     gpointer io_data;
     GDestroyNotify io_notify;
 };
 
 
 
 /**
  * qio_net_listener_new:
  *
  * Create a new network listener service, which is not
  * listening on any sockets initially.
  *
  * Returns: the new listener
  */
 QIONetListener *qio_net_listener_new(void);
 
 
 /**
  * qio_net_listener_set_name:
  * @listener: the network listener object
  * @name: the listener name
  *
  * Set the name of the listener. This is used as a debugging
  * aid, to set names on any GSource instances associated
  * with the listener
  */
 void qio_net_listener_set_name(QIONetListener *listener,
                                const char *name);
 
 /**
  * qio_net_listener_open_sync:
  * @listener: the network listener object
  * @addr: the address to listen on
  * @num: the amount of expected connections
  * @errp: pointer to a NULL initialized error object
  *
  * Synchronously open a listening connection on all
  * addresses associated with @addr. This method may
  * also be invoked multiple times, in order to have a
  * single listener on multiple distinct addresses.
  */
 int qio_net_listener_open_sync(QIONetListener *listener,
                                SocketAddress *addr,
                                int num,
                                Error **errp);
 
 /**
  * qio_net_listener_add:
  * @listener: the network listener object
  * @sioc: the socket I/O channel
  *
  * Associate a listening socket I/O channel with the
  * listener. The listener will acquire a new reference
  * on @sioc, so the caller should release its own reference
  * if it no longer requires the object.
  */
 void qio_net_listener_add(QIONetListener *listener,
                           QIOChannelSocket *sioc);
 
 /**
  * qio_net_listener_set_client_func_full:
  * @listener: the network listener object
  * @func: the callback function
  * @data: opaque data to pass to @func
  * @notify: callback to free @data
  * @context: the context that the sources will be bound to.  If %NULL,
  *           the default context will be used.
  *
  * Register @func to be invoked whenever a new client
  * connects to the listener. @func will be invoked
  * passing in the QIOChannelSocket instance for the
  * client.
  */
 void qio_net_listener_set_client_func_full(QIONetListener *listener,
                                            QIONetListenerClientFunc func,
                                            gpointer data,
                                            GDestroyNotify notify,
                                            GMainContext *context);
 
 /**
  * qio_net_listener_set_client_func:
  * @listener: the network listener object
  * @func: the callback function
  * @data: opaque data to pass to @func
  * @notify: callback to free @data
  *
  * Wrapper of qio_net_listener_set_client_func_full(), only that the
  * sources will always be bound to default main context.
  */
 void qio_net_listener_set_client_func(QIONetListener *listener,
                                       QIONetListenerClientFunc func,
                                       gpointer data,
                                       GDestroyNotify notify);
 
 /**
  * qio_net_listener_wait_client:
  * @listener: the network listener object
  *
  * Block execution of the caller until a new client arrives
  * on one of the listening sockets. If there was previously
  * a callback registered with qio_net_listener_set_client_func
  * it will be temporarily disabled, and re-enabled afterwards.
  *
  * Returns: the new client socket
  */
 QIOChannelSocket *qio_net_listener_wait_client(QIONetListener *listener);
 
 
 /**
  * qio_net_listener_disconnect:
  * @listener: the network listener object
  *
  * Disconnect the listener, removing all I/O callback
  * watches and closing the socket channels.
  */
 void qio_net_listener_disconnect(QIONetListener *listener);
 
 
 /**
  * qio_net_listener_is_connected:
  * @listener: the network listener object
  *
  * Determine if the listener is connected to any socket
  * channels
  *
  * Returns: true if connected, false otherwise
  */
 bool qio_net_listener_is_connected(QIONetListener *listener);
 
 #endif /* QIO_NET_LISTENER_H */