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 continue to #include <libvirt/libvirt.h>

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

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 \

include/libvirt/libvirt-event.h

+/*
+ * libvirt-event.h
+ * Summary: APIs for management of events
+ * Description: Provides APIs for the management of events
+ * Author: Daniel Veillard <veillard@redhat.com>
+ *
+ * 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__ */

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>

libvirt.spec.in

@@ -2252,6 +2252,7 @@ exit 0
 %{_includedir}/libvirt/virterror.h
 %{_includedir}/libvirt/libvirt.h
 %{_includedir}/libvirt/libvirt-domain-snapshot.h
+%{_includedir}/libvirt/libvirt-event.h
 %{_includedir}/libvirt/libvirt-interface.h
 %{_includedir}/libvirt/libvirt-network.h
 %{_includedir}/libvirt/libvirt-nodedev.h

mingw-libvirt.spec.in

@@ -230,6 +230,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
 %dir %{mingw32_includedir}/libvirt
 %{mingw32_includedir}/libvirt/libvirt.h
 %{mingw32_includedir}/libvirt/libvirt-domain-snapshot.h
+%{mingw32_includedir}/libvirt/libvirt-event.h
 %{mingw32_includedir}/libvirt/libvirt-interface.h
 %{mingw32_includedir}/libvirt/libvirt-network.h
 %{mingw32_includedir}/libvirt/libvirt-nodedev.h
@@ -301,6 +302,7 @@ rm -rf $RPM_BUILD_ROOT%{mingw64_libexecdir}/libvirt-guests.sh
 %dir %{mingw64_includedir}/libvirt
 %{mingw64_includedir}/libvirt/libvirt.h
 %{mingw64_includedir}/libvirt/libvirt-domain-snapshot.h
+%{mingw64_includedir}/libvirt/libvirt-event.h
 %{mingw64_includedir}/libvirt/libvirt-interface.h
 %{mingw64_includedir}/libvirt/libvirt-network.h
 %{mingw64_includedir}/libvirt/libvirt-nodedev.h