Changes since V4: - Split out BlockPull() and BlockPullAll(). - BlockPull() cursor changed to a virDomainBlockPullInfo for progress reporting only (from in/out to out-only parameter). /* An iterator for initiating and monitoring block pull operations */ typedef unsigned long long virDomainBlockPullCursor; typedef struct _virDomainBlockPullInfo virDomainBlockPullInfo; struct _virDomainBlockPullInfo { /* * The following fields provide an indication of block pull progress. @cur * indicates the current position and will be between 0 and @end. @end is * the final cursor position for this operation and represents completion. * To approximate progress, divide @cur by @end. */ virDomainBlockPullCursor cur; virDomainBlockPullCursor end; }; typedef virDomainBlockPullInfo *virDomainBlockPullInfoPtr; /** * virDomainBlockPull: * @dom: pointer to domain object * @path: Fully-qualified filename of disk * @pos: A pointer to a virDomainBlockPullInfo structure, or NULL * @flags: currently unused, for future extension * * Populate a disk image with data from its backing image. Once all data from * its backing image has been pulled, the disk no longer depends on a backing * image. This function works incrementally, performing a small amount of work * each time it is called. When successful, @pos is updated with the current * progress. * * Returns -1 in case of failure, 0 when successful. */ int virDomainBlockPull(virDomainPtr dom, const char *path, virDomainBlockPullInfoPtr *pos, unsigned int flags); /** * virDomainBlockPullAll: * @dom: pointer to domain object * @path: Fully-qualified filename of disk * @flags: currently unused, for future extension * * Populate a disk image with data from its backing image. Once all data from * its backing image has been pulled, the disk no longer depends on a backing * image. This function pulls data for the entire device in the background. * Progress of the operation can be checked with virDomainGetBlockPullInfo() and * the operation can be aborted with virDomainBlockPullAbort(). When finished, * an asynchronous event is raised to indicate the final status. * * Returns 0 if the operation has started, -1 on failure. */ int virDomainBlockPullAll(virDomainPtr dom, const char *path, unsigned int flags); /** * virDomainBlockPullAbort: * @dom: pointer to domain object * @path: fully-qualified filename of disk * @flags: currently unused, for future extension * * Cancel a pull operation previously started by virDomainBlockPullAll(). * * Returns -1 in case of failure, 0 when successful. */ int virDomainBlockPullAbort(virDomainPtr dom, const char *path, unsigned int flags); /** * virDomainGetBlockPullInfo: * @dom: pointer to domain object * @path: fully-qualified filename of disk * @info: pointer to a virDomainBlockPullInfo structure * @flags: currently unused, for future extension * * Request progress information on a block pull operation that has been started * with virDomainBlockPullAll(). If an operation is active for the given * parameters, @info will be updated with the current progress. * * Returns -1 in case of failure, 0 when successful. */ int virDomainGetBlockPullInfo(virDomainPtr dom, const char *path, virDomainBlockStreamInfoPtr info, unsigned int flags); The following new asynchronous event will be made available for subscription: VIR_DOMAIN_EVENT_ID_BLOCK_PULL = 7, typedef enum { VIR_DOMAIN_BLOCK_PULL_COMPLETED, VIR_DOMAIN_BLOCK_PULL_FAILED, } virConnectDomainEventBlockPullStatus; typedef void (*virConnectDomainEventBlockPullCallback(virConnectPtr conn, virDomainPtr dom, const char *path, int status); Upon receipt of this event and when the status field indicates success, libvirt will revoke access to the backing file which is no longer needed by the domain. NOTE: Qemu will emit an asynchronous event (VIR_DOMAIN_BLOCK_PULL_COMPLETED) after any operation that eliminates the dependency on the backing file. This will allow libvirt to manage backing file security. If the operation failed, an event (VIR_DOMAIN_BLOCK_PULL_FAILED) will indicate that the backing file has not been removed. -- Adam Litke IBM Linux Technology Center