/**
* virNWFilterBindingDelete:
* @binding: a binding object
*
* Delete the binding object. This does not free the
* associated virNWFilterBindingPtr object. This API
* may be used to remove the network port binding filter
* currently in use for the guest while the guest is
* running without needing to restart the guest. Restoring
* the network port binding filter for the running guest
* would be accomplished by using virNWFilterBindingCreateXML.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virNWFilterBindingDelete(virNWFilterBindingPtr binding)
{
virConnectPtr conn;
VIR_DEBUG("binding=%p", binding);
virResetLastError();
virCheckNWFilterBindingReturn(binding, -1);
conn = binding->conn;
virCheckReadOnlyGoto(conn->flags, error);
if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingDelete) {
int ret;
ret = conn->nwfilterDriver->nwfilterBindingDelete(binding);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(binding->conn);
return -1;
}
/**
* virDomainSnapshotGetXMLDesc:
* @snapshot: a domain snapshot object
* @flags: bitwise-OR of supported virDomainSnapshotXMLFlags
*
* Provide an XML description of the domain snapshot, with a top-level
* element of <domainsnapshot>.
*
* No security-sensitive data will be included unless @flags contains
* VIR_DOMAIN_SNAPSHOT_XML_SECURE; this flag is rejected on read-only
* connections.
*
* Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
* of error. The caller must free() the returned value.
*/
char *
virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
virResetLastError();
virCheckDomainSnapshotReturn(snapshot, NULL);
conn = snapshot->domain->conn;
if ((conn->flags & VIR_CONNECT_RO) &&
(flags & VIR_DOMAIN_SNAPSHOT_XML_SECURE)) {
virReportError(VIR_ERR_OPERATION_DENIED, "%s",
_("virDomainSnapshotGetXMLDesc with secure flag"));
goto error;
}
if (conn->driver->domainSnapshotGetXMLDesc) {
char *ret;
ret = conn->driver->domainSnapshotGetXMLDesc(snapshot, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virDomainSnapshotListChildrenNames:
* @snapshot: a domain snapshot object
* @names: array to collect the list of names of snapshots
* @nameslen: size of @names
* @flags: bitwise-OR of supported virDomainSnapshotListFlags
*
* Collect the list of domain snapshots that are children of the given
* snapshot, and store their names in @names. The value to use for
* @nameslen can be determined by virDomainSnapshotNumChildren() with
* the same @flags.
*
* If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains
* VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, and no other connection is
* modifying snapshots, then it is guaranteed that for any snapshot in
* the resulting list, no snapshots later in the list can be reached
* by a sequence of virDomainSnapshotGetParent() starting from that
* earlier snapshot; otherwise, the order of snapshots in the
* resulting list is unspecified.
*
* By default, this command covers only direct children. It is also
* possible to expand things to cover all descendants, when @flags
* includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
* are provided via the same @flags values as documented in
* virDomainSnapshotListAllChildren().
*
* Note that this command is inherently racy: another connection can
* define a new snapshot between a call to virDomainSnapshotNumChildren()
* and this call. You are only guaranteed that all currently defined
* snapshots were listed if the return is less than @nameslen. Likewise,
* you should be prepared for virDomainSnapshotLookupByName() to fail when
* converting a name from this call into a snapshot object, if another
* connection deletes the snapshot in the meantime. For more control over
* the results, see virDomainSnapshotListAllChildren().
*
* Returns the number of domain snapshots found or -1 in case of error.
* The caller is responsible to call free() for each member of the array.
*/
int
virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
char **names, int nameslen,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("snapshot=%p, names=%p, nameslen=%d, flags=0x%x",
snapshot, names, nameslen, flags);
virResetLastError();
virCheckDomainSnapshotReturn(snapshot, -1);
conn = snapshot->domain->conn;
virCheckNonNullArgGoto(names, error);
virCheckNonNegativeArgGoto(nameslen, error);
if (conn->driver->domainSnapshotListChildrenNames) {
int ret = conn->driver->domainSnapshotListChildrenNames(snapshot,
names,
nameslen,
flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virDomainQemuAttach:
* @conn: pointer to a hypervisor connection
* @pid_value: the UNIX process ID of the external QEMU process
* @flags: optional flags, currently unused
*
* 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).
*
* Returns a new domain object on success, NULL otherwise
*/
virDomainPtr
virDomainQemuAttach(virConnectPtr conn,
unsigned int pid_value,
unsigned int flags)
{
pid_t pid = pid_value;
VIR_DEBUG("conn=%p, pid=%u, flags=%x", conn, pid_value, flags);
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckPositiveArgGoto(pid_value, error);
if (pid != pid_value) {
virReportInvalidArg(pid_value,
_("pid_value in %s is too large"),
__FUNCTION__);
goto error;
}
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuAttach) {
virDomainPtr ret;
ret = conn->driver->domainQemuAttach(conn, pid_value, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virDomainQemuMonitorCommand:
* @domain: a domain object
* @cmd: the qemu monitor command string
* @result: a string returned by @cmd
* @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags
*
* 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.
*
* Returns 0 in case of success, -1 in case of failure
*
*/
int
virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
char **result, unsigned int flags)
{
virConnectPtr conn;
VIR_DOMAIN_DEBUG(domain, "cmd=%s, result=%p, flags=%x",
cmd, result, flags);
virResetLastError();
virCheckDomainReturn(domain, -1);
conn = domain->conn;
virCheckNonNullArgGoto(result, error);
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuMonitorCommand) {
int ret;
ret = conn->driver->domainQemuMonitorCommand(domain, cmd, result,
flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virNodeDeviceDetachFlags:
* @dev: pointer to the node device
* @driverName: name of backend driver that will be used
* for later device assignment to a domain. NULL
* means "use the hypervisor default driver"
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Detach the node device from the node itself so that it may be
* assigned to a guest domain.
*
* Depending on the hypervisor, this may involve operations such as
* unbinding any device drivers from the device, binding the device to
* a dummy device driver and resetting the device. Different backend
* drivers expect the device to be bound to different dummy
* devices. For example, QEMU's "kvm" backend driver (the default)
* expects the device to be bound to "pci-stub", but its "vfio"
* backend driver expects the device to be bound to "vfio-pci".
*
* If the device is currently in use by the node, this method may
* fail.
*
* Once the device is not assigned to any guest, it may be re-attached
* to the node using the virNodeDeviceReAttach() method.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virNodeDeviceDetachFlags(virNodeDevicePtr dev,
const char *driverName,
unsigned int flags)
{
VIR_DEBUG("dev=%p, conn=%p driverName=%s flags=%x",
dev, dev ? dev->conn : NULL,
driverName ? driverName : "(default)", flags);
virResetLastError();
virCheckNodeDeviceReturn(dev, -1);
virCheckReadOnlyGoto(dev->conn->flags, error);
if (dev->conn->driver->nodeDeviceDetachFlags) {
int ret;
ret = dev->conn->driver->nodeDeviceDetachFlags(dev, driverName, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(dev->conn);
return -1;
}
/**
* virNodeDeviceDestroy:
* @dev: a device object
*
* Destroy the device object. The virtual device (only works for vHBA
* currently) is removed from the host operating system. This function
* may require privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virNodeDeviceDestroy(virNodeDevicePtr dev)
{
VIR_DEBUG("dev=%p", dev);
virResetLastError();
virCheckNodeDeviceReturn(dev, -1);
virCheckReadOnlyGoto(dev->conn->flags, error);
if (dev->conn->nodeDeviceDriver &&
dev->conn->nodeDeviceDriver->nodeDeviceDestroy) {
int retval = dev->conn->nodeDeviceDriver->nodeDeviceDestroy(dev);
if (retval < 0) {
goto error;
}
return 0;
}
virReportUnsupportedError();
error:
virDispatchError(dev->conn);
return -1;
}
/**
* virNetworkDefineXML:
* @conn: pointer to the hypervisor connection
* @xml: the XML description for the network, preferably in UTF-8
*
* Define an inactive persistent virtual network or modify an existing
* persistent one from the XML description.
*
* virNetworkFree should be used to free the resources after the
* network object is no longer needed.
*
* Returns NULL in case of error, a pointer to the network otherwise
*/
virNetworkPtr
virNetworkDefineXML(virConnectPtr conn, const char *xml)
{
VIR_DEBUG("conn=%p, xml=%s", conn, NULLSTR(xml));
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckReadOnlyGoto(conn->flags, error);
virCheckNonNullArgGoto(xml, error);
if (conn->networkDriver && conn->networkDriver->networkDefineXML) {
virNetworkPtr ret;
ret = conn->networkDriver->networkDefineXML(conn, xml);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virNetworkUpdate:
* @network: pointer to a defined network
* @section: which section of the network to update
* (see virNetworkUpdateSection for descriptions)
* @command: what action to perform (add/delete/modify)
* (see virNetworkUpdateCommand for descriptions)
* @parentIndex: which parent element, if there are multiple parents
* of the same type (e.g. which <ip> element when modifying
* a <dhcp>/<host> element), or "-1" for "don't care" or
* "automatically find appropriate one".
* @xml: the XML description for the network, preferably in UTF-8
* @flags: bitwise OR of virNetworkUpdateFlags.
*
* Update the definition of an existing network, either its live
* running state, its persistent configuration, or both.
*
* Returns 0 in case of success, -1 in case of error
*/
int
virNetworkUpdate(virNetworkPtr network,
unsigned int command, /* virNetworkUpdateCommand */
unsigned int section, /* virNetworkUpdateSection */
int parentIndex,
const char *xml,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("network=%p, section=%d, parentIndex=%d, xml=%s, flags=0x%x",
network, section, parentIndex, xml, flags);
virResetLastError();
virCheckNetworkReturn(network, -1);
conn = network->conn;
virCheckReadOnlyGoto(conn->flags, error);
virCheckNonNullArgGoto(xml, error);
if (conn->networkDriver && conn->networkDriver->networkUpdate) {
int ret;
ret = conn->networkDriver->networkUpdate(network, section, command,
parentIndex, xml, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(network->conn);
return -1;
}
/**
* virNetworkGetDHCPLeases:
* @network: Pointer to network object
* @mac: Optional ASCII formatted MAC address of an interface
* @leases: Pointer to a variable to store the array containing details on
* obtained leases, or NULL if the list is not required (just returns
* number of leases).
* @flags: Extra flags, not used yet, so callers should always pass 0
*
* For DHCPv4, the information returned:
* - Network Interface Name
* - Expiry Time
* - MAC address
* - IAID (NULL)
* - IPv4 address (with type and prefix)
* - Hostname (can be NULL)
* - Client ID (can be NULL)
*
* For DHCPv6, the information returned:
* - Network Interface Name
* - Expiry Time
* - MAC address
* - IAID (can be NULL, only in rare cases)
* - IPv6 address (with type and prefix)
* - Hostname (can be NULL)
* - Client DUID
*
* Note: @mac, @iaid, @ipaddr, @clientid are in ASCII form, not raw bytes.
* Note: @expirytime can 0, in case the lease is for infinite time.
*
* The API fetches leases info of guests in the specified network. If the
* optional parameter @mac is specified, the returned list will contain only
* lease info about a specific guest interface with @mac. There can be
* multiple leases for a single @mac because this API supports DHCPv6 too.
*
* Returns the number of leases found or -1 and sets @leases to NULL in
* case of error. On success, the array stored into @leases is guaranteed to
* have an extra allocated element set to NULL but not included in the return
* count, to make iteration easier. The caller is responsible for calling
* virNetworkDHCPLeaseFree() on each array element, then calling free() on @leases.
*
* See also virNetworkGetDHCPLeasesForMAC() as a convenience for filtering
* the list to a single MAC address.
*
* Example of usage:
*
* virNetworkDHCPLeasePtr *leases = NULL;
* virNetworkPtr network = ... obtain a network pointer here ...;
* size_t i;
* int nleases;
* unsigned int flags = 0;
*
* nleases = virNetworkGetDHCPLeases(network, NULL, &leases, flags);
* if (nleases < 0)
* error();
*
* ... do something with returned values, for example:
*
* for (i = 0; i < nleases; i++) {
* virNetworkDHCPLeasePtr lease = leases[i];
*
* printf("Time(epoch): %lu, MAC address: %s, "
* "IP address: %s, Hostname: %s, ClientID: %s\n",
* lease->expirytime, lease->mac, lease->ipaddr,
* lease->hostname, lease->clientid);
*
* virNetworkDHCPLeaseFree(leases[i]);
* }
*
* free(leases);
*
*/
int
virNetworkGetDHCPLeases(virNetworkPtr network,
const char *mac,
virNetworkDHCPLeasePtr **leases,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("network=%p, mac='%s' leases=%p, flags=0x%x",
network, NULLSTR(mac), leases, flags);
virResetLastError();
if (leases)
*leases = NULL;
virCheckNetworkReturn(network, -1);
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkGetDHCPLeases) {
int ret;
ret = conn->networkDriver->networkGetDHCPLeases(network, mac, leases, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(network->conn);
return -1;
}
/**
* virConnectListDefinedNetworks:
* @conn: pointer to the hypervisor connection
* @names: pointer to an array to store the names
* @maxnames: size of the array
*
* list the inactive networks, stores the pointers to the names in @names
*
* For more control over the results, see virConnectListAllNetworks().
*
* Returns the number of names provided in the array or -1 in case of error.
* Note that this command is inherently racy; a network can be defined between
* a call to virConnectNumOfDefinedNetworks() and this call; you are only
* guaranteed that all currently defined networks were listed if the return
* is less than @maxnames. The client must call free() on each returned name.
*/
int
virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
int maxnames)
{
VIR_DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
virCheckConnectReturn(conn, -1);
virCheckNonNullArgGoto(names, error);
virCheckNonNegativeArgGoto(maxnames, error);
if (conn->networkDriver && conn->networkDriver->connectListDefinedNetworks) {
int ret;
ret = conn->networkDriver->connectListDefinedNetworks(conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virConnectNetworkEventDeregisterAny:
* @conn: pointer to the connection
* @callbackID: the callback identifier
*
* Removes an event callback. The callbackID parameter should be the
* value obtained from a previous virConnectNetworkEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
*/
int
virConnectNetworkEventDeregisterAny(virConnectPtr conn,
int callbackID)
{
VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID);
virResetLastError();
virCheckConnectReturn(conn, -1);
virCheckNonNegativeArgGoto(callbackID, error);
if (conn->networkDriver &&
conn->networkDriver->connectNetworkEventDeregisterAny) {
int ret;
ret = conn->networkDriver->connectNetworkEventDeregisterAny(conn,
callbackID);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virConnectListAllNWFilters:
* @conn: Pointer to the hypervisor connection.
* @filters: Pointer to a variable to store the array containing the network
* filter objects or NULL if the list is not required (just returns
* number of network filters).
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Collect the list of network filters, and allocate an array to store those
* objects.
*
* Returns the number of network filters found or -1 and sets @filters to NULL
* in case of error. On success, the array stored into @filters is guaranteed to
* have an extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNWFilterFree() on each array element, then calling free() on @filters.
*/
int
virConnectListAllNWFilters(virConnectPtr conn,
virNWFilterPtr **filters,
unsigned int flags)
{
VIR_DEBUG("conn=%p, filters=%p, flags=0x%x", conn, filters, flags);
virResetLastError();
if (filters)
*filters = NULL;
virCheckConnectReturn(conn, -1);
if (conn->nwfilterDriver &&
conn->nwfilterDriver->connectListAllNWFilters) {
int ret;
ret = conn->nwfilterDriver->connectListAllNWFilters(conn, filters, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virNWFilterBindingGetXMLDesc:
* @binding: a binding object
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Provide an XML description of the network filter. The description may be
* reused later to redefine the network filter with virNWFilterCreateXML().
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
char *
virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("binding=%p, flags=0x%x", binding, flags);
virResetLastError();
virCheckNWFilterBindingReturn(binding, NULL);
conn = binding->conn;
if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingGetXMLDesc) {
char *ret;
ret = conn->nwfilterDriver->nwfilterBindingGetXMLDesc(binding, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(binding->conn);
return NULL;
}
/**
* virNodeDeviceLookupSCSIHostByWWN:
* @conn: pointer to the hypervisor connection
* @wwnn: WWNN of the SCSI Host.
* @wwpn: WWPN of the SCSI Host.
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Lookup SCSI Host which is capable with 'fc_host' by its WWNN and WWPN.
*
* virNodeDeviceFree should be used to free the resources after the
* node device object is no longer needed.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
*/
virNodeDevicePtr
virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn,
const char *wwnn,
const char *wwpn,
unsigned int flags)
{
VIR_DEBUG("conn=%p, wwnn=%p, wwpn=%p, flags=%x", conn, wwnn, wwpn, flags);
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckNonNullArgGoto(wwnn, error);
virCheckNonNullArgGoto(wwpn, error);
if (conn->nodeDeviceDriver &&
conn->nodeDeviceDriver->nodeDeviceLookupSCSIHostByWWN) {
virNodeDevicePtr ret;
ret = conn->nodeDeviceDriver->nodeDeviceLookupSCSIHostByWWN(conn, wwnn,
wwpn, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virNetworkGetXMLDesc:
* @network: a network object
* @flags: bitwise-OR of virNetworkXMLFlags
*
* Provide an XML description of the network. The description may be reused
* later to relaunch the network with virNetworkCreateXML().
*
* Normally, if a network included a physical function, the output includes
* all virtual functions tied to that physical interface. If @flags includes
* VIR_NETWORK_XML_INACTIVE, then the expansion of virtual interfaces is
* not performed.
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
char *
virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("network=%p, flags=0x%x", network, flags);
virResetLastError();
virCheckNetworkReturn(network, NULL);
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkGetXMLDesc) {
char *ret;
ret = conn->networkDriver->networkGetXMLDesc(network, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(network->conn);
return NULL;
}
/**
* virNodeDeviceListCaps:
* @dev: the device
* @names: array to collect the list of capability names
* @maxnames: size of @names
*
* Lists the names of the capabilities supported by the device.
*
* Returns the number of capability names listed in @names or -1
* in case of error.
*/
int
virNodeDeviceListCaps(virNodeDevicePtr dev,
char **const names,
int maxnames)
{
VIR_DEBUG("dev=%p, conn=%p, names=%p, maxnames=%d",
dev, dev ? dev->conn : NULL, names, maxnames);
virResetLastError();
virCheckNodeDeviceReturn(dev, -1);
virCheckNonNullArgGoto(names, error);
virCheckNonNegativeArgGoto(maxnames, error);
if (dev->conn->nodeDeviceDriver && dev->conn->nodeDeviceDriver->nodeDeviceListCaps) {
int ret;
ret = dev->conn->nodeDeviceDriver->nodeDeviceListCaps(dev, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(dev->conn);
return -1;
}
/**
* virNetworkGetBridgeName:
* @network: a network object
*
* Provides a bridge interface name to which a domain may connect
* a network interface in order to join the network.
*
* Returns a 0 terminated interface name, or NULL in case of error.
* the caller must free() the returned value.
*/
char *
virNetworkGetBridgeName(virNetworkPtr network)
{
virConnectPtr conn;
VIR_DEBUG("network=%p", network);
virResetLastError();
virCheckNetworkReturn(network, NULL);
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkGetBridgeName) {
char *ret;
ret = conn->networkDriver->networkGetBridgeName(network);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(network->conn);
return NULL;
}
/**
* virNodeDeviceCreateXML:
* @conn: pointer to the hypervisor connection
* @xmlDesc: string containing an XML description of the device to be created
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Create a new device on the VM host machine, for example, virtual
* HBAs created using vport_create.
*
* virNodeDeviceFree should be used to free the resources after the
* node device object is no longer needed.
*
* Returns a node device object if successful, NULL in case of failure
*/
virNodeDevicePtr
virNodeDeviceCreateXML(virConnectPtr conn,
const char *xmlDesc,
unsigned int flags)
{
VIR_DEBUG("conn=%p, xmlDesc=%s, flags=%x", conn, xmlDesc, flags);
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckReadOnlyGoto(conn->flags, error);
virCheckNonNullArgGoto(xmlDesc, error);
if (conn->nodeDeviceDriver &&
conn->nodeDeviceDriver->nodeDeviceCreateXML) {
virNodeDevicePtr dev = conn->nodeDeviceDriver->nodeDeviceCreateXML(conn, xmlDesc, flags);
if (dev == NULL)
goto error;
return dev;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virConnectListAllNetworks:
* @conn: Pointer to the hypervisor connection.
* @nets: Pointer to a variable to store the array containing the network
* objects or NULL if the list is not required (just returns number
* of networks).
* @flags: bitwise-OR of virConnectListAllNetworksFlags.
*
* Collect the list of networks, and allocate an array to store those
* objects. This API solves the race inherent between virConnectListNetworks
* and virConnectListDefinedNetworks.
*
* Normally, all networks are returned; however, @flags can be used to
* filter the results for a smaller list of targeted networks. The valid
* flags are divided into groups, where each group contains bits that
* describe mutually exclusive attributes of a network, and where all bits
* within a group describe all possible networks.
*
* The first group of @flags is VIR_CONNECT_LIST_NETWORKS_ACTIVE (up) and
* VIR_CONNECT_LIST_NETWORKS_INACTIVE (down) to filter the networks by state.
*
* The second group of @flags is VIR_CONNECT_LIST_NETWORKS_PERSISTENT (defined)
* and VIR_CONNECT_LIST_NETWORKS_TRANSIENT (running but not defined), to filter
* the networks by whether they have persistent config or not.
*
* The third group of @flags is VIR_CONNECT_LIST_NETWORKS_AUTOSTART
* and VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART, to filter the networks by
* whether they are marked as autostart or not.
*
* Returns the number of networks found or -1 and sets @nets to NULL in case
* of error. On success, the array stored into @nets is guaranteed to have an
* extra allocated element set to NULL but not included in the return count,
* to make iteration easier. The caller is responsible for calling
* virNetworkFree() on each array element, then calling free() on @nets.
*/
int
virConnectListAllNetworks(virConnectPtr conn,
virNetworkPtr **nets,
unsigned int flags)
{
VIR_DEBUG("conn=%p, nets=%p, flags=0x%x", conn, nets, flags);
virResetLastError();
if (nets)
*nets = NULL;
virCheckConnectReturn(conn, -1);
if (conn->networkDriver &&
conn->networkDriver->connectListAllNetworks) {
int ret;
ret = conn->networkDriver->connectListAllNetworks(conn, nets, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
int virSecurityManagerVerify(virSecurityManagerPtr mgr,
virDomainDefPtr def)
{
virSecurityLabelDefPtr secdef;
if (mgr == NULL || mgr->drv == NULL)
return 0;
/* NULL model == dynamic labelling, with whatever driver
* is active, so we can short circuit verify check to
* avoid drivers de-referencing NULLs by accident
*/
secdef = virDomainDefGetSecurityLabelDef(def, mgr->drv->name);
if (secdef == NULL || secdef->model == NULL)
return 0;
if (mgr->drv->domainSecurityVerify) {
int ret;
virObjectLock(mgr);
ret = mgr->drv->domainSecurityVerify(mgr, def);
virObjectUnlock(mgr);
return ret;
}
virReportUnsupportedError();
return -1;
}
/**
* virNetworkSetAutostart:
* @network: a network object
* @autostart: whether the network should be automatically started 0 or 1
*
* Configure the network to be automatically started
* when the host machine boots.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virNetworkSetAutostart(virNetworkPtr network,
int autostart)
{
virConnectPtr conn;
VIR_DEBUG("network=%p, autostart=%d", network, autostart);
virResetLastError();
virCheckNetworkReturn(network, -1);
conn = network->conn;
virCheckReadOnlyGoto(conn->flags, error);
if (conn->networkDriver && conn->networkDriver->networkSetAutostart) {
int ret;
ret = conn->networkDriver->networkSetAutostart(network, autostart);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(network->conn);
return -1;
}
/**
* virDomainQemuAgentCommand:
* @domain: a domain object
* @cmd: the guest agent command string
* @timeout: timeout seconds
* @flags: execution 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
*
* Returns strings if success, NULL in failure.
*/
char *
virDomainQemuAgentCommand(virDomainPtr domain,
const char *cmd,
int timeout,
unsigned int flags)
{
virConnectPtr conn;
char *ret;
VIR_DOMAIN_DEBUG(domain, "cmd=%s, timeout=%d, flags=%x",
cmd, timeout, flags);
virResetLastError();
virCheckDomainReturn(domain, NULL);
conn = domain->conn;
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuAgentCommand) {
ret = conn->driver->domainQemuAgentCommand(domain, cmd,
timeout, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virDomainLxcOpenNamespace:
* @domain: a domain object
* @fdlist: pointer to an array to be filled with FDs
* @flags: currently unused, pass 0
*
* This API is LXC specific, so it will only work with hypervisor
* connections to the LXC driver.
*
* Open the namespaces associated with the container @domain.
* The @fdlist array will be allocated to a suitable size,
* and filled with file descriptors for the namespaces. It
* is the caller's responsibility to close the file descriptors
*
* The returned file descriptors are intended to be used with
* the setns() system call.
*
* Returns the number of opened file descriptors, or -1 on error
*/
int
virDomainLxcOpenNamespace(virDomainPtr domain,
int **fdlist,
unsigned int flags)
{
virConnectPtr conn;
VIR_DOMAIN_DEBUG(domain, "fdlist=%p flags=%x", fdlist, flags);
virResetLastError();
virCheckDomainReturn(domain, -1);
conn = domain->conn;
virCheckNonNullArgGoto(fdlist, error);
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainLxcOpenNamespace) {
int ret;
ret = conn->driver->domainLxcOpenNamespace(domain,
fdlist,
flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virDomainSnapshotDelete:
* @snapshot: a domain snapshot object
* @flags: bitwise-OR of supported virDomainSnapshotDeleteFlags
*
* Delete the snapshot.
*
* If @flags is 0, then just this snapshot is deleted, and changes
* from this snapshot are automatically merged into children
* snapshots. If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN,
* then this snapshot and any descendant snapshots are deleted. If
* @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, then any
* descendant snapshots are deleted, but this snapshot remains. These
* two flags are mutually exclusive.
*
* If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY, then
* any snapshot metadata tracked by libvirt is removed while keeping
* the snapshot contents intact; if a hypervisor does not require any
* libvirt metadata to track snapshots, then this flag is silently
* ignored.
*
* Returns 0 if the selected snapshot(s) were successfully deleted,
* -1 on error.
*/
int
virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
virResetLastError();
virCheckDomainSnapshotReturn(snapshot, -1);
conn = snapshot->domain->conn;
virCheckReadOnlyGoto(conn->flags, error);
VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN,
VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY,
error);
if (conn->driver->domainSnapshotDelete) {
int ret = conn->driver->domainSnapshotDelete(snapshot, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virConnectListAllNodeDevices:
* @conn: Pointer to the hypervisor connection.
* @devices: Pointer to a variable to store the array containing the node
* device objects or NULL if the list is not required (just returns
* number of node devices).
* @flags: bitwise-OR of virConnectListAllNodeDevices.
*
* Collect the list of node devices, and allocate an array to store those
* objects.
*
* Normally, all node devices are returned; however, @flags can be used to
* filter the results for a smaller list of targeted node devices. The valid
* flags are divided into groups, where each group contains bits that
* describe mutually exclusive attributes of a node device, and where all bits
* within a group describe all possible node devices.
*
* Only one group of the @flags is provided to filter the node devices by
* capability type, flags include:
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS
* VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC
*
* Returns the number of node devices found or -1 and sets @devices to NULL in
* case of error. On success, the array stored into @devices is guaranteed to
* have an extra allocated element set to NULL but not included in the return
* count, to make iteration easier. The caller is responsible for calling
* virNodeDeviceFree() on each array element, then calling free() on
* @devices.
*/
int
virConnectListAllNodeDevices(virConnectPtr conn,
virNodeDevicePtr **devices,
unsigned int flags)
{
VIR_DEBUG("conn=%p, devices=%p, flags=%x", conn, devices, flags);
virResetLastError();
if (devices)
*devices = NULL;
virCheckConnectReturn(conn, -1);
if (conn->nodeDeviceDriver &&
conn->nodeDeviceDriver->connectListAllNodeDevices) {
int ret;
ret = conn->nodeDeviceDriver->connectListAllNodeDevices(conn, devices, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virDomainListAllSnapshots:
* @domain: a domain object
* @snaps: pointer to variable to store the array containing snapshot objects
* or NULL if the list is not required (just returns number of
* snapshots)
* @flags: bitwise-OR of supported virDomainSnapshotListFlags
*
* Collect the list of domain snapshots for the given domain and allocate
* an array to store those objects. This API solves the race inherent in
* virDomainSnapshotListNames().
*
* If @flags contains VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL and @snaps
* is non-NULL, and no other connection is modifying snapshots, then
* it is guaranteed that for any snapshot in the resulting list, no
* snapshots later in the list can be reached by a sequence of
* virDomainSnapshotGetParent() starting from that earlier snapshot;
* otherwise, the order of snapshots in the resulting list is
* unspecified.
*
* By default, this command covers all snapshots. It is also possible
* to limit things to just snapshots with no parents, when @flags
* includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are
* provided in groups listed below. Within a group, bits are mutually
* exclusive, where all possible snapshots are described by exactly
* one bit from the group. Some hypervisors might reject particular
* flags where it cannot make a distinction for filtering. If the set
* of filter flags selected forms an impossible combination, the
* hypervisor may return either 0 or an error.
*
* The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
* VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
* have no further children (a leaf snapshot).
*
* The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
* VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
* whether they have metadata that would prevent the removal of the last
* reference to a domain.
*
* The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
* VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
* for filtering snapshots based on what domain state is tracked by the
* snapshot.
*
* The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
* VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
* whether the snapshot is stored inside the disk images or as
* additional files.
*
* Returns the number of domain snapshots found or -1 and sets @snaps to
* NULL in case of error. On success, the array stored into @snaps is
* guaranteed to have an extra allocated element set to NULL but not included
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
*/
int
virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
unsigned int flags)
{
virConnectPtr conn;
VIR_DOMAIN_DEBUG(domain, "snaps=%p, flags=0x%x", snaps, flags);
virResetLastError();
if (snaps)
*snaps = NULL;
virCheckDomainReturn(domain, -1);
conn = domain->conn;
if (conn->driver->domainListAllSnapshots) {
int ret = conn->driver->domainListAllSnapshots(domain, snaps, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virNodeListDevices:
* @conn: pointer to the hypervisor connection
* @cap: capability name
* @names: array to collect the list of node device names
* @maxnames: size of @names
* @flags: extra flags; not used yet, so callers should always pass 0
*
* Collect the list of node devices, and store their names in @names
*
* For more control over the results, see virConnectListAllNodeDevices().
*
* If the optional 'cap' argument is non-NULL, then the count
* will be restricted to devices with the specified capability
*
* Returns the number of node devices found or -1 in case of error
*/
int
virNodeListDevices(virConnectPtr conn,
const char *cap,
char **const names, int maxnames,
unsigned int flags)
{
VIR_DEBUG("conn=%p, cap=%s, names=%p, maxnames=%d, flags=%x",
conn, cap, names, maxnames, flags);
virResetLastError();
virCheckConnectReturn(conn, -1);
virCheckNonNullArgGoto(names, error);
virCheckNonNegativeArgGoto(maxnames, error);
if (conn->nodeDeviceDriver && conn->nodeDeviceDriver->nodeListDevices) {
int ret;
ret = conn->nodeDeviceDriver->nodeListDevices(conn, cap, names, maxnames, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virDomainSnapshotListAllChildren:
* @snapshot: a domain snapshot object
* @snaps: pointer to variable to store the array containing snapshot objects
* or NULL if the list is not required (just returns number of
* snapshots)
* @flags: bitwise-OR of supported virDomainSnapshotListFlags
*
* Collect the list of domain snapshots that are children of the given
* snapshot, and allocate an array to store those objects. This API solves
* the race inherent in virDomainSnapshotListChildrenNames().
*
* If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains
* VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, @snaps is non-NULL, and no
* other connection is modifying snapshots, then it is guaranteed that
* for any snapshot in the resulting list, no snapshots later in the
* list can be reached by a sequence of virDomainSnapshotGetParent()
* starting from that earlier snapshot; otherwise, the order of
* snapshots in the resulting list is unspecified.
*
* By default, this command covers only direct children. It is also
* possible to expand things to cover all descendants, when @flags
* includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
* are provided via the remaining @flags values as documented in
* virDomainListAllSnapshots(), with the exception that
* VIR_DOMAIN_SNAPSHOT_LIST_ROOTS is not supported (in fact,
* VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS has the same bit value but
* opposite semantics of widening rather than narrowing the listing).
*
* Returns the number of domain snapshots found or -1 and sets @snaps to
* NULL in case of error. On success, the array stored into @snaps is
* guaranteed to have an extra allocated element set to NULL but not included
* in the return count, to make iteration easier. The caller is responsible
* for calling virDomainSnapshotFree() on each array element, then calling
* free() on @snaps.
*/
int
virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
virDomainSnapshotPtr **snaps,
unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("snapshot=%p, snaps=%p, flags=0x%x", snapshot, snaps, flags);
virResetLastError();
if (snaps)
*snaps = NULL;
virCheckDomainSnapshotReturn(snapshot, -1);
conn = snapshot->domain->conn;
if (conn->driver->domainSnapshotListAllChildren) {
int ret = conn->driver->domainSnapshotListAllChildren(snapshot, snaps,
flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virNWFilterBindingCreateXML:
* @conn: pointer to the hypervisor connection
* @xml: an XML description of the binding
* @flags: currently unused, pass 0
*
* Define a new network filter, based on an XML description
* similar to the one returned by virNWFilterGetXMLDesc(). This
* API may be used to associate a filter with a currently running
* guest that does not have a filter defined for a specific network
* port. Since the bindings are generally automatically managed by
* the hypervisor, using this command to define a filter for a network
* port and then starting the guest afterwards may prevent the guest
* from starting if it attempts to use the network port and finds a
* filter already defined.
*
* virNWFilterFree should be used to free the resources after the
* binding object is no longer needed.
*
* Returns a new binding object or NULL in case of failure
*/
virNWFilterBindingPtr
virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int flags)
{
VIR_DEBUG("conn=%p, xml=%s", conn, NULLSTR(xml));
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckNonNullArgGoto(xml, error);
virCheckReadOnlyGoto(conn->flags, error);
if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingCreateXML) {
virNWFilterBindingPtr ret;
ret = conn->nwfilterDriver->nwfilterBindingCreateXML(conn, xml, flags);
if (!ret)
goto error;
return ret;
}
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
