[libvirt] [PATCH] (not for inclusion) add virDomainRename API

[Daniel P. Berrange]

On Mon, Jun 08, 2009 at 04:31:35PM -0500, Doug Goldstein wrote:
> The following patch stubs out virDomainRename() as an available API
> function. I'm just making sure I'm doing this right. I know there were
> some plans to include documentation about adding API to the website
> but I don't see it. The included patch does not include my example
> driver for qemu and test.

Dave's docs are now online ina new 'Internals' section of the website
where we'll aim to provide more docs about developing libvirt APIs,
hypervisor drivers and general guidelines for libvirt internal development
(as distinct from application developers).


> diff --git a/docs/libvirt-api.xml b/docs/libvirt-api.xml
> index fc85acd..ec4131d 100644
> --- a/docs/libvirt-api.xml
> +++ b/docs/libvirt-api.xml
> @@ -202,6 +202,7 @@
>       <exports symbol='virDomainCreateLinux' type='function'/>
>       <exports symbol='virNodeDeviceGetXMLDesc' type='function'/>
>       <exports symbol='virEventUpdateHandleFunc' type='function'/>
> +     <exports symbol='virDomainRename' type='function'/>
>       <exports symbol='virDomainDestroy' type='function'/>
>       <exports symbol='virConnectNumOfNetworks' type='function'/>
>       <exports symbol='virStoragePoolLookupByUUIDString' type='function'/>
> @@ -1131,6 +1132,12 @@ see note above'/>
>        <arg name='conn' type='virConnectPtr' info='pointer to the hypervisor connection'/>
>        <arg name='xml' type='const char *' info='the XML description for the domain, preferably in UTF-8'/>
>      </function>
> +    <function name='virDomainRename' file='libvirt' module='libvirt'>
> +      <info>Rename the domain to the requested name. This function may require privileged access</info>
> +      <return type='int' info='0 in case of success and -1 in case of failure.'/>
> +      <arg name='domain' type='virDomainPtr' info='a domain object'/>
> +      <arg name='name' type='const char *' info='new name to rename domain to'/>
> +    </function>

It looks like you may have hand-written this. FYI, it is actally 
auto-generated from the inline comments in src/libvirt.c. If you
add comments to that file, then in the docs directory you can
type 'make api' to update the XML file.


>  
>  /**
> + * virDomainRename:
> + * @domain: a domain object
> + * @name: new name for the domain
> + *
> + * Try to rename the domain to the requested domain name.
> + *
> + * Returns 0 in case of success and -1 in case of failure.
> + */

I'd add a further comment here that this operation is only required
to work for inactive domains. Implementing this safely for active
QEMU domains will be very hard, because there are quite alot of
runtime files that are based on the VM name. We should say that
a driver returns VIR_ERR_OPERATION_INVALID error code if they do not
support rename of active guests.

> +int
> +virDomainRename(virDomainPtr domain, const char *name)
> +{
> +    virConnectPtr conn;
> +
> +    DEBUG("domain=%p", domain);
> +
> +    virResetLastError();
> +
> +    if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
> +        virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
> +        return (-1);
> +    }
> +
> +    conn = domain->conn;
> +    if (conn->flags & VIR_CONNECT_RO) {
> +        virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
> +        goto error;
> +    }
> +
> +    if (conn->driver->domainRename) {
> +        int ret;
> +        ret = conn->driver->domainRename(domain, name);
> +        if (ret < 0)
> +            goto error;
> +        return ret;
> +    }
> +
> +    virLibConnError(conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
> +
> +error: 
> +    /* Copy to connection error object for back compatability */
> +    virSetConnError(conn);
> +    return (-1);
> +}
> +
> +/**
>   * virDomainDestroy:
>   * @domain: a domain object
>   *



Looks like you're understanding the libvirt API/internals well enough,
so look forward to next versions of this patch....

Regards,
Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|