Add public API to register a callback to be invoked on connection close

Define new virConnect{Register,Unregister}CloseCallback() public APIs
which allows registering/unregistering a callback to be invoked when
the connection to a hypervisor is closed. The callback is provided
with the reason for the close, which may be 'error', 'eof', 'client'
or 'keepalive'.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>

1 files changed, 39 insertions, 10 deletions

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index 71e41e816..d21d029bf 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -61,6 +61,24 @@ extern "C" {
  * defines VIR_ENUM_SENTINELS.  Enumerations for bit values do not
  * have a *_LAST value, but additional bits may be defined.  */
 
+/*
+ * virFreeCallback:
+ * @opaque: opaque user data provided at registration
+ *
+ * Type for a callback cleanup function to be paired with a callback.  This
+ * function will be called as a final chance to clean up the @opaque
+ * registered with the primary callback, at the time when the primary
+ * callback is deregistered.
+ *
+ * It is forbidden to call any other libvirt APIs from an
+ * implementation of this callback, since it can be invoked
+ * from a context which is not re-entrant safe. Failure to
+ * abide by this requirement may lead to application deadlocks
+ * or crashes.
+ */
+typedef void (*virFreeCallback)(void *opaque);
+
+
 /**
  * virConnect:
  *
@@ -1160,6 +1178,27 @@ int virConnectSetKeepAlive(virConnectPtr conn,
                            int interval,
                            unsigned int count);
 
+typedef enum {
+    VIR_CONNECT_CLOSE_REASON_ERROR     = 0, /* Misc I/O error */
+    VIR_CONNECT_CLOSE_REASON_EOF       = 1, /* End-of-file from server */
+    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered */
+    VIR_CONNECT_CLOSE_REASON_CLIENT    = 3, /* Client requested it */
+
+# ifdef VIR_ENUM_SENTINELS
+    VIR_CONNECT_CLOSE_REASON_LAST
+# endif
+} virConnectCloseReason;
+
+typedef void (*virConnectCloseFunc)(virConnectPtr conn,
+                                    int reason,
+                                    void *opaque);
+
+int virConnectRegisterCloseCallback(virConnectPtr conn,
+                                    virConnectCloseFunc cb,
+                                    void *opaque,
+                                    virFreeCallback freecb);
+int virConnectUnregisterCloseCallback(virConnectPtr conn,
+                                      virConnectCloseFunc cb);
 
 /*
  * Capabilities of the connection / driver.
@@ -2875,16 +2914,6 @@ typedef int (*virConnectDomainEventCallback)(virConnectPtr conn,
                                              int detail,
                                              void *opaque);
 
-/*
- * virFreeCallback:
- * @opaque: opaque user data provided at registration
- *
- * Type for a domain event callback when the event is deregistered and
- * need to be freed, @opaque is provided along with the callback at
- * registration time
- */
-typedef void (*virFreeCallback)(void *opaque);
-
 int virConnectDomainEventRegister(virConnectPtr conn,
                                   virConnectDomainEventCallback cb,
                                   void *opaque,