[libvirt] [PATCH 3/7] qemu_api: Add comments for API virDomainQemuMonitorCommand

[Daniel Veillard]

On Fri, Sep 09, 2011 at 07:24:43PM +0800, Osier Yang wrote:
> And fix argument @pid's type of virDomainQemuAttach.
> ---
>  src/libvirt-qemu.c |   41 ++++++++++++++++++++++++++++++++++++++---
>  1 files changed, 38 insertions(+), 3 deletions(-)
> 
> diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
> index 9481e01..b46868f 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);
> -- 
> 1.7.6

  ACK, that could be carried separately too,

Daniel

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/