[libvirt] [PATCH 09/12] Move virEvent related APIs out of libvirt.h.in

Create a new libvirt-event.h file to hold the public API definitions for the virEvent type. This header file is not self-contained, so applications will not directly include it. They will contain to #include <libvirt/libvirt.h> --- docs/apibuild.py | 1 + include/libvirt/Makefile.am | 1 + include/libvirt/libvirt-event.h | 190 ++++++++++++++++++++++++++++++++++++++++ include/libvirt/libvirt.h.in | 162 +--------------------------------- 4 files changed, 193 insertions(+), 161 deletions(-) create mode 100644 include/libvirt/libvirt-event.h diff --git a/docs/apibuild.py b/docs/apibuild.py index 4282beb..e79ac42 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -23,6 +23,7 @@ debugsym=None included_files = { "libvirt.h": "header with general libvirt API definitions", "libvirt-domain-snapshot.h": "header with general libvirt API definitions", + "libvirt-event.h": "header with general libvirt API definitions", "libvirt-interface.h": "header with general libvirt API definitions", "libvirt-network.h": "header with general libvirt API definitions", "libvirt-nodedev.h": "header with general libvirt API definitions", diff --git a/include/libvirt/Makefile.am b/include/libvirt/Makefile.am index 4a13fba..9b34539 100644 --- a/include/libvirt/Makefile.am +++ b/include/libvirt/Makefile.am @@ -20,6 +20,7 @@ virincdir = $(includedir)/libvirt virinc_HEADERS = libvirt.h \ libvirt-domain-snapshot.h \ + libvirt-event.h \ libvirt-interface.h \ libvirt-network.h \ libvirt-nodedev.h \ diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h new file mode 100644 index 0000000..23227d0 --- /dev/null +++ b/include/libvirt/libvirt-event.h @@ -0,0 +1,190 @@ +/* + * libvirt-event.h + * Summary: APIs for management of events + * Description: Provides APIs for the management of events + * Author: Daniel Veillard <veillard(a)redhat.com&gt; + * + * Copyright (C) 2006-2014 Red Hat, Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * <http://www.gnu.org/licenses/>;. + */ + +#ifndef __VIR_LIBVIRT_EVENT_H__ +# define __VIR_LIBVIRT_EVENT_H__ + +# ifndef __VIR_LIBVIRT_H_INCLUDES__ +# error "Don't include this file directly, only use libvirt/libvirt.h" +# endif + + +/** + * virEventHandleType: + * + * a virEventHandleType is used similar to POLLxxx FD events, but is specific + * to libvirt. A client app must translate to, and from POLL events when using + * this construct. + */ +typedef enum { + VIR_EVENT_HANDLE_READABLE = (1 << 0), + VIR_EVENT_HANDLE_WRITABLE = (1 << 1), + VIR_EVENT_HANDLE_ERROR = (1 << 2), + VIR_EVENT_HANDLE_HANGUP = (1 << 3), +} virEventHandleType; + +/** + * virEventHandleCallback: + * + * @watch: watch on which the event occurred + * @fd: file handle on which the event occurred + * @events: bitset of events from virEventHandleType constants + * @opaque: user data registered with handle + * + * Callback for receiving file handle events. The callback will + * be invoked once for each event which is pending. + */ +typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque); + +/** + * virEventAddHandleFunc: + * @fd: file descriptor to listen on + * @event: bitset of events on which to fire the callback + * @cb: the callback to be called when an event occurrs + * @opaque: user data to pass to the callback + * @ff: the callback invoked to free opaque data blob + * + * Part of the EventImpl, this callback adds a file handle callback to + * listen for specific events. The same file handle can be registered + * multiple times provided the requested event sets are non-overlapping + * + * If the opaque user data requires free'ing when the handle + * is unregistered, then a 2nd callback can be supplied for + * this purpose. This callback needs to be invoked from a clean stack. + * If 'ff' callbacks are invoked directly from the virEventRemoveHandleFunc + * they will likely deadlock in libvirt. + * + * Returns -1 if the file handle cannot be registered, otherwise a handle + * watch number to be used for updating and unregistering for events + */ +typedef int (*virEventAddHandleFunc)(int fd, int event, + virEventHandleCallback cb, + void *opaque, + virFreeCallback ff); + +/** + * virEventUpdateHandleFunc: + * @watch: file descriptor watch to modify + * @event: new events to listen on + * + * Part of the EventImpl, this user-provided callback is notified when + * events to listen on change + */ +typedef void (*virEventUpdateHandleFunc)(int watch, int event); + +/** + * virEventRemoveHandleFunc: + * @watch: file descriptor watch to stop listening on + * + * Part of the EventImpl, this user-provided callback is notified when + * an fd is no longer being listened on. + * + * If a virEventHandleFreeFunc was supplied when the handle was + * registered, it will be invoked some time during, or after this + * function call, when it is safe to release the user data. + * + * Returns -1 if the file handle was not registered, 0 upon success + */ +typedef int (*virEventRemoveHandleFunc)(int watch); + +/** + * virEventTimeoutCallback: + * + * @timer: timer id emitting the event + * @opaque: user data registered with handle + * + * callback for receiving timer events + */ +typedef void (*virEventTimeoutCallback)(int timer, void *opaque); + +/** + * virEventAddTimeoutFunc: + * @timeout: The timeout to monitor + * @cb: the callback to call when timeout has expired + * @opaque: user data to pass to the callback + * @ff: the callback invoked to free opaque data blob + * + * Part of the EventImpl, this user-defined callback handles adding an + * event timeout. + * + * If the opaque user data requires free'ing when the handle + * is unregistered, then a 2nd callback can be supplied for + * this purpose. + * + * Returns a timer value + */ +typedef int (*virEventAddTimeoutFunc)(int timeout, + virEventTimeoutCallback cb, + void *opaque, + virFreeCallback ff); + +/** + * virEventUpdateTimeoutFunc: + * @timer: the timer to modify + * @timeout: the new timeout value + * + * Part of the EventImpl, this user-defined callback updates an + * event timeout. + */ +typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout); + +/** + * virEventRemoveTimeoutFunc: + * @timer: the timer to remove + * + * Part of the EventImpl, this user-defined callback removes a timer + * + * If a virEventTimeoutFreeFunc was supplied when the handle was + * registered, it will be invoked some time during, or after this + * function call, when it is safe to release the user data. + * + * Returns 0 on success, -1 on failure + */ +typedef int (*virEventRemoveTimeoutFunc)(int timer); + +void virEventRegisterImpl(virEventAddHandleFunc addHandle, + virEventUpdateHandleFunc updateHandle, + virEventRemoveHandleFunc removeHandle, + virEventAddTimeoutFunc addTimeout, + virEventUpdateTimeoutFunc updateTimeout, + virEventRemoveTimeoutFunc removeTimeout); + +int virEventRegisterDefaultImpl(void); +int virEventRunDefaultImpl(void); + +int virEventAddHandle(int fd, int events, + virEventHandleCallback cb, + void *opaque, + virFreeCallback ff); +void virEventUpdateHandle(int watch, int events); +int virEventRemoveHandle(int watch); + +int virEventAddTimeout(int frequency, + virEventTimeoutCallback cb, + void *opaque, + virFreeCallback ff); +void virEventUpdateTimeout(int timer, int frequency); +int virEventRemoveTimeout(int timer); + + +#endif /* __VIR_LIBVIRT_EVENT_H__ */ diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in index c449c20..186b996 100644 --- a/include/libvirt/libvirt.h.in +++ b/include/libvirt/libvirt.h.in @@ -3189,167 +3189,6 @@ int virConnectDomainEventRegister(virConnectPtr conn, int virConnectDomainEventDeregister(virConnectPtr conn, virConnectDomainEventCallback cb); -/* - * Events Implementation - */ - -/** - * virEventHandleType: - * - * a virEventHandleType is used similar to POLLxxx FD events, but is specific - * to libvirt. A client app must translate to, and from POLL events when using - * this construct. - */ -typedef enum { - VIR_EVENT_HANDLE_READABLE = (1 << 0), - VIR_EVENT_HANDLE_WRITABLE = (1 << 1), - VIR_EVENT_HANDLE_ERROR = (1 << 2), - VIR_EVENT_HANDLE_HANGUP = (1 << 3), -} virEventHandleType; - -/** - * virEventHandleCallback: - * - * @watch: watch on which the event occurred - * @fd: file handle on which the event occurred - * @events: bitset of events from virEventHandleType constants - * @opaque: user data registered with handle - * - * Callback for receiving file handle events. The callback will - * be invoked once for each event which is pending. - */ -typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque); - -/** - * virEventAddHandleFunc: - * @fd: file descriptor to listen on - * @event: bitset of events on which to fire the callback - * @cb: the callback to be called when an event occurrs - * @opaque: user data to pass to the callback - * @ff: the callback invoked to free opaque data blob - * - * Part of the EventImpl, this callback adds a file handle callback to - * listen for specific events. The same file handle can be registered - * multiple times provided the requested event sets are non-overlapping - * - * If the opaque user data requires free'ing when the handle - * is unregistered, then a 2nd callback can be supplied for - * this purpose. This callback needs to be invoked from a clean stack. - * If 'ff' callbacks are invoked directly from the virEventRemoveHandleFunc - * they will likely deadlock in libvirt. - * - * Returns -1 if the file handle cannot be registered, otherwise a handle - * watch number to be used for updating and unregistering for events - */ -typedef int (*virEventAddHandleFunc)(int fd, int event, - virEventHandleCallback cb, - void *opaque, - virFreeCallback ff); - -/** - * virEventUpdateHandleFunc: - * @watch: file descriptor watch to modify - * @event: new events to listen on - * - * Part of the EventImpl, this user-provided callback is notified when - * events to listen on change - */ -typedef void (*virEventUpdateHandleFunc)(int watch, int event); - -/** - * virEventRemoveHandleFunc: - * @watch: file descriptor watch to stop listening on - * - * Part of the EventImpl, this user-provided callback is notified when - * an fd is no longer being listened on. - * - * If a virEventHandleFreeFunc was supplied when the handle was - * registered, it will be invoked some time during, or after this - * function call, when it is safe to release the user data. - * - * Returns -1 if the file handle was not registered, 0 upon success - */ -typedef int (*virEventRemoveHandleFunc)(int watch); - -/** - * virEventTimeoutCallback: - * - * @timer: timer id emitting the event - * @opaque: user data registered with handle - * - * callback for receiving timer events - */ -typedef void (*virEventTimeoutCallback)(int timer, void *opaque); - -/** - * virEventAddTimeoutFunc: - * @timeout: The timeout to monitor - * @cb: the callback to call when timeout has expired - * @opaque: user data to pass to the callback - * @ff: the callback invoked to free opaque data blob - * - * Part of the EventImpl, this user-defined callback handles adding an - * event timeout. - * - * If the opaque user data requires free'ing when the handle - * is unregistered, then a 2nd callback can be supplied for - * this purpose. - * - * Returns a timer value - */ -typedef int (*virEventAddTimeoutFunc)(int timeout, - virEventTimeoutCallback cb, - void *opaque, - virFreeCallback ff); - -/** - * virEventUpdateTimeoutFunc: - * @timer: the timer to modify - * @timeout: the new timeout value - * - * Part of the EventImpl, this user-defined callback updates an - * event timeout. - */ -typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout); - -/** - * virEventRemoveTimeoutFunc: - * @timer: the timer to remove - * - * Part of the EventImpl, this user-defined callback removes a timer - * - * If a virEventTimeoutFreeFunc was supplied when the handle was - * registered, it will be invoked some time during, or after this - * function call, when it is safe to release the user data. - * - * Returns 0 on success, -1 on failure - */ -typedef int (*virEventRemoveTimeoutFunc)(int timer); - -void virEventRegisterImpl(virEventAddHandleFunc addHandle, - virEventUpdateHandleFunc updateHandle, - virEventRemoveHandleFunc removeHandle, - virEventAddTimeoutFunc addTimeout, - virEventUpdateTimeoutFunc updateTimeout, - virEventRemoveTimeoutFunc removeTimeout); - -int virEventRegisterDefaultImpl(void); -int virEventRunDefaultImpl(void); - -int virEventAddHandle(int fd, int events, - virEventHandleCallback cb, - void *opaque, - virFreeCallback ff); -void virEventUpdateHandle(int watch, int events); -int virEventRemoveHandle(int watch); - -int virEventAddTimeout(int frequency, - virEventTimeoutCallback cb, - void *opaque, - virFreeCallback ff); -void virEventUpdateTimeout(int timer, int frequency); -int virEventRemoveTimeout(int timer); - int virDomainIsActive(virDomainPtr dom); int virDomainIsPersistent(virDomainPtr dom); @@ -4575,6 +4414,7 @@ typedef virMemoryParameter *virMemoryParameterPtr; #define __VIR_LIBVIRT_H_INCLUDES__ #include <libvirt/libvirt-domain-snapshot.h> +#include <libvirt/libvirt-event.h> #include <libvirt/libvirt-interface.h> #include <libvirt/libvirt-network.h> #include <libvirt/libvirt-nodedev.h> -- 2.1.0