libvirt: Module libvirt-qemu from libvirt-qemu
Description: libvirt, virtualization, virtualization API

# Module libvirt-qemu from libvirt-qemu

Provides the interfaces of the libvirt library to handle qemu specific methods Copyright (C) 2010-2014 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.

## Table of Contents

### Types

    typedef enum virConnectDomainQemuMonitorEventRegisterFlags
    typedef enum virDomainQemuAgentCommandTimeoutValues
    typedef enum virDomainQemuMonitorCommandFlags

### Functions

    typedef virConnectDomainQemuMonitorEventCallback
    void	virConnectDomainQemuMonitorEventCallback	(virConnectPtr conn,
    							 virDomainPtr dom,
    							 const char * event,
    							 long long seconds,
    							 unsigned int micros,
    							 const char * details,
    							 void * opaque)

    int	virConnectDomainQemuMonitorEventDeregister	(virConnectPtr conn,
    							 int callbackID)
    int	virConnectDomainQemuMonitorEventRegister	(virConnectPtr conn,
    							 virDomainPtr dom,
    							 const char * event,
    							 virConnectDomainQemuMonitorEventCallback cb,
    							 void * opaque,
    							 virFreeCallback freecb,
    							 unsigned int flags)
    char *	virDomainQemuAgentCommand	(virDomainPtr domain,
    					 const char * cmd,
    					 int timeout,
    					 unsigned int flags)
    virDomainPtr	virDomainQemuAttach	(virConnectPtr conn,
    					 unsigned int pid_value,
    					 unsigned int flags)
    int	virDomainQemuMonitorCommand	(virDomainPtr domain,
    					 const char * cmd,
    					 char ** result,
    					 unsigned int flags)

## Description

### Types

### `virConnectDomainQemuMonitorEventRegisterFlags`

    enum virConnectDomainQemuMonitorEventRegisterFlags {

VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX | = | 1 (0x1; 1 << 0) | Event filter is a regex rather than a literal string
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE | = | 2 (0x2; 1 << 1) | Event filter is case insensitive

    }

### `virDomainQemuAgentCommandTimeoutValues`

    enum virDomainQemuAgentCommandTimeoutValues {

VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK
VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT
VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK
VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT | = | VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT
VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN | = | 60 (0x3c)

    }

### `virDomainQemuMonitorCommandFlags`

    enum virDomainQemuMonitorCommandFlags {

VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT | = | 0 (0x0)
VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP | = | 1 (0x1; 1 << 0) | cmd is in HMP

    }

### Functions

### `virConnectDomainQemuMonitorEventCallback`

    typedef void	(*virConnectDomainQemuMonitorEventCallback)	(virConnectPtr conn,
    							 virDomainPtr dom,
    							 const char * event,
    							 long long seconds,
    							 unsigned int micros,
    							 const char * details,
    							 void * opaque)

The callback signature to use when registering for a qemu monitor event with virConnectDomainQemuMonitorEventRegister().

conn
  the connection pointer
dom
  the domain pointer
event
  the name of the event
seconds
  the qemu timestamp of the event: seconds since Epoch, or -1 if not available
micros
  the qemu timestamp of the event: microseconds within the second
details
  the JSON details of the event, if any were given
opaque
  application specified data

### `virConnectDomainQemuMonitorEventDeregister`

    int	virConnectDomainQemuMonitorEventDeregister	(virConnectPtr conn,
    							 int callbackID)

Removes an event callback. The callbackID parameter should be the value obtained from a previous virConnectDomainQemuMonitorEventRegister() method.

conn
  pointer to the connection
callbackID
  the callback identifier
Returns
  0 on success, -1 on failure

### `virConnectDomainQemuMonitorEventRegister`

    int	virConnectDomainQemuMonitorEventRegister	(virConnectPtr conn,
    							 virDomainPtr dom,
    							 const char * event,
    							 virConnectDomainQemuMonitorEventCallback cb,
    							 void * opaque,
    							 virFreeCallback freecb,
    							 unsigned int flags)

This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver.

Adds a callback to receive notifications of arbitrary qemu monitor events occurring on a domain. Many qemu monitor events also result in a libvirt event which can be delivered via virConnectDomainEventRegisterAny(); this command is primarily for testing new qemu events that have not yet been given a libvirt counterpart event.

If `dom` is NULL, then events will be monitored for any domain. If `dom` is non-NULL, then only the specific domain will be monitored.

If `event` is NULL, then all monitor events will be reported. If `event` is non-NULL, then only specific monitor events will be reported. `flags` controls how the filtering is performed: 0 requests an exact match, while VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX states that `event` is a basic regular expression. Additionally, including VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE lets `event` match case-insensitively.

The virDomainPtr object handle passed into the callback upon delivery of an event is only valid for the duration of execution of the callback. If the callback wishes to keep the domain object after the callback returns, it shall take a reference to it, by calling virDomainRef(). The reference can be released once the object is no longer required by calling virDomainFree().

The return value from this method is a positive integer identifier for the callback. To unregister a callback, this callback ID should be passed to the virConnectDomainQemuMonitorEventDeregister() method.

conn
  pointer to the connection
dom
  pointer to the domain, or NULL
event
  name of the event, or NULL
cb
  callback to the function handling monitor events
opaque
  opaque data to pass on to the callback
freecb
  optional function to deallocate opaque when not used anymore
flags
  bitwise-OR of virConnectDomainQemuMonitorEventRegisterFlags
Returns
  a callback identifier on success, -1 on failure

### `virDomainQemuAgentCommand`

    char *	virDomainQemuAgentCommand	(virDomainPtr domain,
    					 const char * cmd,
    					 int timeout,
    					 unsigned int flags)

Execute an arbitrary Guest Agent command.

Issue `cmd` to the guest agent running in `domain`. `timeout` must be -2, -1, 0 or positive. VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for a result. VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT(-1): use default timeout value. VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait. positive value: wait for `timeout` seconds

domain
  a domain object
cmd
  the guest agent command string
timeout
  timeout seconds
flags
  execution flags
Returns
  strings if success, NULL in failure.

### `virDomainQemuAttach`

    virDomainPtr	virDomainQemuAttach	(virConnectPtr conn,
    					 unsigned int pid_value,
    					 unsigned int flags)

This API is QEMU specific, so it will only work with hypervisor connections to the QEMU driver.

This API will attach to an externally launched QEMU process identified by `pid`. There are several requirements to successfully attach to an external QEMU process:

    - It must have been started with a monitor socket using the UNIX
      domain socket protocol.
    - No device hotplug/unplug, 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)

To date, the only platforms we know of where pid_t is larger than unsigned int (64-bit Windows) also lack UNIX sockets, so the choice of `pid_value` as an unsigned int should not present any difficulties.

If successful, then the guest will appear in the list of running domains for this connection, and other APIs should operate normally (provided the above requirements were honored).

conn
  pointer to a hypervisor connection
pid_value
  the UNIX process ID of the external QEMU process
flags
  optional flags, currently unused
Returns
  a new domain object on success, NULL otherwise

### `virDomainQemuMonitorCommand`

    int	virDomainQemuMonitorCommand	(virDomainPtr domain,
    					 const char * cmd,
    					 char ** result,
    					 unsigned int flags)

This API is QEMU specific, so it 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 successfully use this API:

    - A @cmd that queries state without making any modifications is safe
    - A @cmd that alters state that is also tracked by libvirt is unsafe,
      and may cause libvirtd to crash
    - A @cmd that alters state not tracked by the current version of
      libvirt is possible as a means to test new qemu features before
      they have support in libvirt, but no guarantees are made to safety

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 with the string output of the `cmd`, and the caller must free this string.

domain
  a domain object
cmd
  the qemu monitor command string
result
  a string returned by `cmd`
flags
  bitwise-or of supported virDomainQemuMonitorCommandFlags
Returns
  0 in case of success, -1 in case of failure