From 9d08debe887db96a444afae890967cf02f4237ee Mon Sep 17 00:00:00 2001
From: Eric Blake <eblake@redhat.com>
Date: Fri, 8 Jun 2012 10:28:55 -0600
Subject: [PATCH] snapshot: add virDomainSnapshotRef API

virDomainSnapshotPtr has a refcount member, but no one was able
to use it.  Furthermore, all of our other vir*Ptr objects have
a *Ref method to match their *Free method.  Thankfully, this is
client-side only, so we can use this new function regardless of
how old the server side is!  (I have future patches to virsh
that want to use it.)

* include/libvirt/libvirt.h.in (virDomainSnapshotRef): Declare.
* src/libvirt.c (virDomainSnapshotRef): Implement it.
* src/libvirt_public.syms (LIBVIRT_0.9.13): Export it.
---
 include/libvirt/libvirt.h.in |  1 +
 src/libvirt.c                | 33 +++++++++++++++++++++++++++++++++
 src/libvirt_public.syms      |  5 +++++
 3 files changed, 39 insertions(+)

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index da3ce29fd6..fcb66955d4 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -3424,6 +3424,7 @@ typedef enum {
 int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
                             unsigned int flags);
 
+int virDomainSnapshotRef(virDomainSnapshotPtr snapshot);
 int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
 
 /*
diff --git a/src/libvirt.c b/src/libvirt.c
index 6386ed48be..00358d68bb 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -17486,6 +17486,39 @@ error:
     return -1;
 }
 
+/**
+ * virDomainSnapshotRef:
+ * @snapshot: the snapshot to hold a reference on
+ *
+ * Increment the reference count on the snapshot. For each
+ * additional call to this method, there shall be a corresponding
+ * call to virDomainSnapshotFree to release the reference count, once
+ * the caller no longer needs the reference to this object.
+ *
+ * This method is typically useful for applications where multiple
+ * threads are using a connection, and it is required that the
+ * connection and domain remain open until all threads have finished
+ * using the snapshot. ie, each new thread using a snapshot would
+ * increment the reference count.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
+{
+    if ((!VIR_IS_DOMAIN_SNAPSHOT(snapshot))) {
+        virLibDomainSnapshotError(VIR_ERR_INVALID_DOMAIN_SNAPSHOT,
+                                  __FUNCTION__);
+        virDispatchError(NULL);
+        return -1;
+    }
+    virMutexLock(&snapshot->domain->conn->lock);
+    VIR_DEBUG("snapshot=%p, refs=%d", snapshot, snapshot->refs);
+    snapshot->refs++;
+    virMutexUnlock(&snapshot->domain->conn->lock);
+    return 0;
+}
+
 /**
  * virDomainSnapshotFree:
  * @snapshot: a domain snapshot object
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 46c13fbfdc..ba61595be7 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -534,4 +534,9 @@ LIBVIRT_0.9.11 {
         virDomainPMWakeup;
 } LIBVIRT_0.9.10;
 
+LIBVIRT_0.9.13 {
+    global:
+        virDomainSnapshotRef;
+} LIBVIRT_0.9.11;
+
 # .... define new API here using predicted next version number ....