自学教程：C++ virReportUnsupportedError函数代码示例

/** * 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. */intvirNWFilterBindingDelete(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. */intvirDomainSnapshotListChildrenNames(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 */virDomainPtrvirDomainQemuAttach(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 * */intvirDomainQemuMonitorCommand(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. */intvirNodeDeviceDetachFlags(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. */intvirNodeDeviceDestroy(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 */virNetworkPtrvirNetworkDefineXML(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 */intvirNetworkUpdate(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); * */intvirNetworkGetDHCPLeases(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();//.........这里部分代码省略.........

/** * 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. */intvirConnectListDefinedNetworks(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 */intvirConnectNetworkEventDeregisterAny(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. */intvirConnectListAllNWFilters(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. */virNodeDevicePtrvirNodeDeviceLookupSCSIHostByWWN(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. */intvirNodeDeviceListCaps(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 */virNodeDevicePtrvirNodeDeviceCreateXML(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. */intvirConnectListAllNetworks(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 */intvirNetworkSetAutostart(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 */intvirDomainLxcOpenNamespace(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. */intvirDomainSnapshotDelete(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. */intvirConnectListAllNodeDevices(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. */intvirDomainListAllSnapshots(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 */intvirNodeListDevices(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. */intvirDomainSnapshotListAllChildren(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 */virNWFilterBindingPtrvirNWFilterBindingCreateXML(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;}