From 4e53546911c42ee871f8e7650e8a84593f0e8ddd Mon Sep 17 00:00:00 2001
From: Osier Yang <jyang@redhat.com>
Date: Fri, 9 Sep 2011 19:00:09 +0800
Subject: [PATCH] qemu_api: Add comments for API virDomainQemuMonitorCommand

And fix argument @pid's type of virDomainQemuAttach.
---
 src/libvirt-qemu.c | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
index 9481e01944..b46868f713 100644
--- a/src/libvirt-qemu.c
+++ b/src/libvirt-qemu.c
@@ -36,6 +36,43 @@
     virReportErrorHelper(VIR_FROM_DOM, error, NULL, __FUNCTION__,       \
                          __LINE__, info)
 
+/**
+ * virDomainQemuMonitorCommand:
+ * @domain: a domain object
+ * @cmd: the qemu monitor command string
+ * @result: a string returned by @cmd
+ * @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags
+ *
+ * This API is QEMU specific, so will only work with hypervisor
+ * connections to the QEMU driver.
+ *
+ * Send an arbitrary monitor command @cmd to @domain through the
+ * qemu monitor. There are several requirements to safely and
+ * succcesfully to use this API:
+ *
+ *   - It must have been started with a monitor socket using the UNIX
+ *     domain socket protocol.
+ *   - No other operations which are changing the domain state or
+ *     configuration at the same time, e.g. domain saving, it might
+ *     cause libvirtd crashed.
+ *   - If the @cmd is intend to change domain configuration, it must
+ *     be no or other configuration changes can have been made via
+ *     the monitor since it started.
+ *   - The '-name' and '-uuid' arguments should have been set (not
+ *     mandatory, but strongly recommended)
+ *
+ * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is
+ * considered to be a human monitor command and libvirt will automatically
+ * convert it into QMP if needed.  In that case the @result will also
+ * be converted back from QMP.
+ *
+ * If successful, @result will be filled as a string with the output
+ * of the @cmd. And other APIs should operate normally (provided the
+ * above requirements were honoured
+ *
+ * Returns 0 in case of success, -1 in case of failure
+ *
+ */
 int
 virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
                             char **result, unsigned int flags)
@@ -81,8 +118,6 @@ error:
     return -1;
 }
 
-
-
 /**
  * virDomainQemuAttach:
  * @conn: pointer to a hypervisor connection
@@ -111,7 +146,7 @@ error:
  */
 virDomainPtr
 virDomainQemuAttach(virConnectPtr conn,
-                    unsigned pid,
+                    unsigned int pid,
                     unsigned int flags)
 {
     VIR_DEBUG("conn=%p, pid=%u, flags=%x", conn, pid, flags);
-- 
GitLab