Introduce a new public API for domain events

The current API for domain events has a number of problems

 - Only allows for domain lifecycle change events
 - Does not allow the same callback to be registered multiple times
 - Does not allow filtering of events to a specific domain

This introduces a new more general purpose domain events API

  typedef enum {
     VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0,       /* virConnectDomainEventCallback */
      ...more events later..
  }

  int virConnectDomainEventRegisterAny(virConnectPtr conn,
                                       virDomainPtr dom, /* Optional, to filter */
                                       int eventID,
                                       virConnectDomainEventGenericCallback cb,
                                       void *opaque,
                                       virFreeCallback freecb);

  int virConnectDomainEventDeregisterAny(virConnectPtr conn,
                                         int callbackID);

Since different event types can received different data in the callback,
the API is defined with a generic callback. Specific events will each
have a custom signature for their callback. Thus when registering an
event it is neccessary to cast the callback to the generic signature

eg

  int myDomainEventCallback(virConnectPtr conn,
                            virDomainPtr dom,
                            int event,
                            int detail,
                            void *opaque)
  {
    ...
  }

  virConnectDomainEventRegisterAny(conn, NULL,
                                   VIR_DOMAIN_EVENT_ID_LIFECYCLE,
                                   VIR_DOMAIN_EVENT_CALLBACK(myDomainEventCallback)
                                   NULL, NULL);

The VIR_DOMAIN_EVENT_CALLBACK() macro simply does a "bad" cast
to the generic signature

* include/libvirt/libvirt.h.in: Define new APIs for registering
  domain events
* src/driver.h: Internal driver entry points for new events APIs
* src/libvirt.c: Wire up public API to driver API for events APIs
* src/libvirt_public.syms: Export new APIs
* src/esx/esx_driver.c, src/lxc/lxc_driver.c, src/opennebula/one_driver.c,
  src/openvz/openvz_driver.c, src/phyp/phyp_driver.c,
  src/qemu/qemu_driver.c, src/remote/remote_driver.c,
  src/test/test_driver.c, src/uml/uml_driver.c,
  src/vbox/vbox_tmpl.c, src/xen/xen_driver.c,
  src/xenapi/xenapi_driver.c: Stub out new API entries

1 files changed, 38 insertions, 0 deletions

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index aaefa098bb..35c3891a2c 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -1857,6 +1857,44 @@ int virDomainGetJobInfo(virDomainPtr dom,
 int virDomainAbortJob(virDomainPtr dom);
 
 
+/* A generic callback definition. Specific events usually have a customization
+ * with extra parameters */
+typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
+                                                     virDomainPtr dom,
+                                                     void *opaque);
+
+/**
+ * VIR_DOMAIN_EVENT_CALLBACK:
+ *
+ * Used to cast the event specific callback into the generic one
+ * for use for virDomainEventRegister
+ */
+#define VIR_DOMAIN_EVENT_CALLBACK(cb) ((virConnectDomainEventGenericCallback)(cb))
+
+
+typedef enum {
+    VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0,       /* virConnectDomainEventCallback */
+
+    /*
+     * NB: this enum value will increase over time as new events are
+     * added to the libvirt API. It reflects the last event ID supported
+     * by this version of the libvirt API.
+     */
+    VIR_DOMAIN_EVENT_ID_LAST
+} virDomainEventID;
+
+
+/* Use VIR_DOMAIN_EVENT_CALLBACK() to cast the 'cb' parameter  */
+int virConnectDomainEventRegisterAny(virConnectPtr conn,
+                                     virDomainPtr dom, /* Optional, to filter */
+                                     int eventID,
+                                     virConnectDomainEventGenericCallback cb,
+                                     void *opaque,
+                                     virFreeCallback freecb);
+
+int virConnectDomainEventDeregisterAny(virConnectPtr conn,
+                                       int callbackID);
+
 #ifdef __cplusplus
 }
 #endif