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/.
typedef enum virConnectDomainQemuMonitorEventRegisterFlags typedef enum virDomainQemuAgentCommandTimeoutValues typedef enum virDomainQemuMonitorCommandFlags
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)
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
|
}
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().
virConnectDomainQemuMonitorEventDeregister
¶
int virConnectDomainQemuMonitorEventDeregister (virConnectPtr conn, int callbackID)
Removes an event callback. The callbackID parameter should be the value obtained from a previous virConnectDomainQemuMonitorEventRegister() method.
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.
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
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).
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.
cmd