[libvirt] [PATCH] Update the documentation for virDomainMigrateToURI

[Daniel Veillard]

On Fri, Oct 23, 2009 at 01:01:40PM +0200, Chris Lalancette wrote:
> Signed-off-by: Chris Lalancette <clalance at redhat.com>
> ---
>  src/libvirt.c |   41 ++++++++++++++++++++++-------------------
>  1 files changed, 22 insertions(+), 19 deletions(-)
> 
> diff --git a/src/libvirt.c b/src/libvirt.c
> index 9e87900..5787f22 100644
> --- a/src/libvirt.c
> +++ b/src/libvirt.c
> @@ -3154,7 +3154,7 @@ virDomainMigrateDirect (virDomainPtr domain,
>   * XML includes details of the support URI schemes. If omitted
>   * the dconn will be asked for a default URI.
>   *
> - * In either case it is typically only neccessary to specify a
> + * In either case it is typically only necessary to specify a
>   * URI if the destination host has multiple interfaces and a
>   * specific interface is required to transmit migration data.
>   *
> @@ -3273,7 +3273,7 @@ error:
>  /**
>   * virDomainMigrateToURI:
>   * @domain: a domain object
> - * @duri: mandatory URI for the destination host
> + * @duri: mandatory URI for the destination host (see below)
>   * @flags: flags
>   * @dname: (optional) rename domain to this at destination
>   * @bandwidth: (optional) specify migration bandwidth limit in Mbps
> @@ -3285,28 +3285,31 @@ error:
>   *   VIR_MIGRATE_LIVE      Do not pause the VM during migration
>   *   VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts
>   *   VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel
> + *   VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain
> + *                            on the destination host.
> + *   VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the
> + *                               domain on the source host.
>   *
> - * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set.
> - * Applications using the VIR_MIGRATE_PEER2PEER flag will probably
> - * prefer to invoke virDomainMigrateToURI, avoiding the need to
> - * open connection to the destination host themselves.
> - *
> - * If a hypervisor supports renaming domains during migration,
> - * then you may set the dname parameter to the new name (otherwise
> - * it keeps the same name).  If this is not supported by the
> - * hypervisor, dname must be NULL or else you will get an error.
> - *
> - * If the VIR_MIGRATE_PEER2PEER flag is set, the duri parameter
> - * must be a valid libvirt connection URI, by which the source
> - * libvirt driver can connect to the destination libvirt.
> - *
> + * The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag.
>   * If the VIR_MIGRATE_PEER2PEER flag is NOT set, the duri parameter
>   * takes a hypervisor specific format. The hypervisor capabilities
> - * XML includes details of the support URI schemes. Not all hypervisors
> + * XML includes details of the supported URI schemes. Not all hypervisors
>   * will support this mode of migration, so if the VIR_MIGRATE_PEER2PEER
> - * flag is not set, then it may be neccessary to use the alternative
> + * flag is not set, then it may be necessary to use the alternative
>   * virDomainMigrate API providing an explicit virConnectPtr for the
> - * destination host
> + * destination host.
> + *
> + * If the VIR_MIGRATE_PEER2PEER flag IS set, the duri parameter
> + * must be a valid libvirt connection URI, by which the source
> + * libvirt driver can connect to the destination libvirt.
> + *
> + * VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set.
> + *
> + * If a hypervisor supports renaming domains during migration,
> + * the dname parameter specifies the new name for the domain.
> + * Setting dname to NULL keeps the domain name the same.  If domain
> + * renaming is not supported by the hypervisor, dname must be NULL or
> + * else an error will be returned.
>   *
>   * The maximum bandwidth (in Mbps) that will be used to do migration
>   * can be specified with the bandwidth parameter.  If set to 0,

  As danken pointed out before this function description really needed
a revamp, thanks for doing this, ACK !

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/