<?xml version="1.0" encoding="UTF-8"?>
<api name='libvirt-qemu'>
  <files>
    <file name='libvirt-qemu'>
     <summary>qemu specific interfaces</summary>
     <description>Provides the interfaces of the libvirt library to handle qemu specific methods</description>
     <exports symbol='VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE' type='enum'/>
     <exports symbol='VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT' type='enum'/>
     <exports symbol='VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP' type='enum'/>
     <exports symbol='virConnectDomainQemuMonitorEventRegisterFlags' type='typedef'/>
     <exports symbol='virDomainQemuAgentCommandTimeoutValues' type='typedef'/>
     <exports symbol='virDomainQemuMonitorCommandFlags' type='typedef'/>
     <exports symbol='virConnectDomainQemuMonitorEventCallback' type='function'/>
     <exports symbol='virConnectDomainQemuMonitorEventDeregister' type='function'/>
     <exports symbol='virConnectDomainQemuMonitorEventRegister' type='function'/>
     <exports symbol='virDomainQemuAgentCommand' type='function'/>
     <exports symbol='virDomainQemuAttach' type='function'/>
     <exports symbol='virDomainQemuMonitorCommand' type='function'/>
     <exports symbol='virDomainQemuMonitorCommandWithFiles' type='function'/>
    </file>
  </files>
  <symbols>
    <enum name='VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE' file='libvirt-qemu' value='2' value_hex='0x2' value_bitshift='1' type='virConnectDomainQemuMonitorEventRegisterFlags' version='1.2.3' info='Event filter is case insensitive'/>
    <enum name='VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX' file='libvirt-qemu' value='1' value_hex='0x1' value_bitshift='0' type='virConnectDomainQemuMonitorEventRegisterFlags' version='1.2.3' info='Event filter is a regex rather than a literal string'/>
    <enum name='VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK' file='libvirt-qemu' value='VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK' type='virDomainQemuAgentCommandTimeoutValues' version='0.10.0'/>
    <enum name='VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT' file='libvirt-qemu' value='VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT' type='virDomainQemuAgentCommandTimeoutValues' version='0.10.0'/>
    <enum name='VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN' file='libvirt-qemu' value='VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK' type='virDomainQemuAgentCommandTimeoutValues' version='0.10.0'/>
    <enum name='VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT' file='libvirt-qemu' value='VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT' type='virDomainQemuAgentCommandTimeoutValues' version='0.10.0'/>
    <enum name='VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN' file='libvirt-qemu' value='60' value_hex='0x3c' type='virDomainQemuAgentCommandTimeoutValues' version='1.2.15'/>
    <enum name='VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT' file='libvirt-qemu' value='0' value_hex='0x0' type='virDomainQemuMonitorCommandFlags' version='0.8.8'/>
    <enum name='VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP' file='libvirt-qemu' value='1' value_hex='0x1' value_bitshift='0' type='virDomainQemuMonitorCommandFlags' version='0.8.8' info='cmd is in HMP'/>
    <typedef name='virConnectDomainQemuMonitorEventRegisterFlags' file='libvirt-qemu' type='enum' version='1.2.3'/>
    <typedef name='virDomainQemuAgentCommandTimeoutValues' file='libvirt-qemu' type='enum' version='0.10.0'/>
    <typedef name='virDomainQemuMonitorCommandFlags' file='libvirt-qemu' type='enum' version='0.8.8'/>
    <functype name='virConnectDomainQemuMonitorEventCallback' file='libvirt-qemu' module='libvirt-qemu' version='1.2.3'>
      <info><![CDATA[The callback signature to use when registering for a qemu monitor
event with virConnectDomainQemuMonitorEventRegister().]]></info>
      <return type='void'/>
      <arg name='conn' type='virConnectPtr' info='the connection pointer'/>
      <arg name='dom' type='virDomainPtr' info='the domain pointer'/>
      <arg name='event' type='const char *' info='the name of the event'/>
      <arg name='seconds' type='long long' info='the qemu timestamp of the event: seconds since Epoch, or -1 if not available'/>
      <arg name='micros' type='unsigned int' info='the qemu timestamp of the event: microseconds within the second'/>
      <arg name='details' type='const char *' info='the JSON details of the event, if any were given'/>
      <arg name='opaque' type='void *' info='application specified data'/>
    </functype>
    <function name='virConnectDomainQemuMonitorEventDeregister' file='libvirt-qemu' module='libvirt-qemu' version='1.2.3'>
      <info><![CDATA[Removes an event callback. The callbackID parameter should be the
value obtained from a previous virConnectDomainQemuMonitorEventRegister()
method.]]></info>
      <return type='int' info='0 on success, -1 on failure'/>
      <arg name='conn' type='virConnectPtr' info='pointer to the connection'/>
      <arg name='callbackID' type='int' info='the callback identifier'/>
      <acls>
        <check object='connect' perm='write'/>
      </acls>
    </function>
    <function name='virConnectDomainQemuMonitorEventRegister' file='libvirt-qemu' module='libvirt-qemu' version='1.2.3'>
      <info><![CDATA[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.]]></info>
      <return type='int' info='a callback identifier on success, -1 on failure'/>
      <arg name='conn' type='virConnectPtr' info='pointer to the connection'/>
      <arg name='dom' type='virDomainPtr' info='pointer to the domain, or NULL'/>
      <arg name='event' type='const char *' info='name of the event, or NULL'/>
      <arg name='cb' type='virConnectDomainQemuMonitorEventCallback' info='callback to the function handling monitor events'/>
      <arg name='opaque' type='void *' info='opaque data to pass on to the callback'/>
      <arg name='freecb' type='virFreeCallback' info='optional function to deallocate opaque when not used anymore'/>
      <arg name='flags' type='unsigned int' info='bitwise-OR of virConnectDomainQemuMonitorEventRegisterFlags'/>
      <acls>
        <check object='connect' perm='search-domains'/>
        <check object='connect' perm='write'/>
        <filter object='domain' perm='getattr'/>
      </acls>
    </function>
    <function name='virDomainQemuAgentCommand' file='libvirt-qemu' module='libvirt-qemu' version='0.10.0'>
      <info><![CDATA[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]]></info>
      <return type='char *' info='strings if success, NULL in failure.'/>
      <arg name='domain' type='virDomainPtr' info='a domain object'/>
      <arg name='cmd' type='const char *' info='the guest agent command string'/>
      <arg name='timeout' type='int' info='timeout seconds'/>
      <arg name='flags' type='unsigned int' info='execution flags'/>
      <acls>
        <check object='domain' perm='write'/>
      </acls>
    </function>
    <function name='virDomainQemuAttach' file='libvirt-qemu' module='libvirt-qemu' version='0.9.4'>
      <info><![CDATA[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).]]></info>
      <return type='virDomainPtr' info='a new domain object on success, NULL otherwise'/>
      <arg name='conn' type='virConnectPtr' info='pointer to a hypervisor connection'/>
      <arg name='pid_value' type='unsigned int' info='the UNIX process ID of the external QEMU process'/>
      <arg name='flags' type='unsigned int' info='optional flags, currently unused'/>
      <acls>
        <check object='domain' perm='start'/>
        <check object='domain' perm='write'/>
      </acls>
    </function>
    <function name='virDomainQemuMonitorCommand' file='libvirt-qemu' module='libvirt-qemu' version='0.8.3'>
      <info><![CDATA[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.]]></info>
      <return type='int' info='0 in case of success, -1 in case of failure'/>
      <arg name='domain' type='virDomainPtr' info='a domain object'/>
      <arg name='cmd' type='const char *' info='the QEMU monitor command string'/>
      <arg name='result' type='char **' info='a string returned by @cmd'/>
      <arg name='flags' type='unsigned int' info='bitwise-or of supported virDomainQemuMonitorCommandFlags'/>
      <acls>
        <check object='domain' perm='write'/>
      </acls>
    </function>
    <function name='virDomainQemuMonitorCommandWithFiles' file='libvirt-qemu' module='libvirt-qemu' version='8.2.0'>
      <info><![CDATA[This API is QEMU specific, so it will only work with hypervisor
connections to the QEMU driver with local connections using the unix socket.

Send an arbitrary monitor command @cmd with file descriptors @infiles to
@domain through the QEMU monitor and optionally return file descriptors via
@outfiles. 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.]]></info>
      <return type='int' info='0 in case of success, -1 in case of failure'/>
      <arg name='domain' type='virDomainPtr' info='a domain object'/>
      <arg name='cmd' type='const char *' info='the QEMU monitor command string'/>
      <arg name='ninfiles' type='unsigned int' info='number of filedescriptors passed in @infiles'/>
      <arg name='infiles' type='int *' info='filedescriptors to be passed to QEMU with the command'/>
      <arg name='noutfiles' type='unsigned int *' info='if non-NULL filled with number of returned file descriptors'/>
      <arg name='outfiles' type='int **' info='if non-NULL filled with an array of returned file descriptors'/>
      <arg name='result' type='char **' info='a string returned by @cmd'/>
      <arg name='flags' type='unsigned int' info='bitwise-or of supported virDomainQemuMonitorCommandFlags'/>
      <acls>
        <check object='domain' perm='write'/>
      </acls>
    </function>
  </symbols>
</api>
