External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-02 19:31:18 +00:00
Code Issues Packages Projects Releases Wiki Activity
d7a3c8352e
libvirt/src/libvirt.c
Daniel P. Berrange 5486abfe4e Fix API doc extractor to stop munging comment formatting 
The python method help docs are copied across from the C
funtion comments, but in the process all line breaks and
indentation was being lost. This made the resulting text
and code examples completely unreadable. Both the API
doc extractor and the python generator were destroying
whitespace & this fixes them to preserve it exactly.

* docs/apibuild.py: Preserve all whitespace when extracting
  function comments. Print function comment inside a <![CDATA[
  section to fully preserve all whitespace. Look for the
  word 'returns' to describe return values, instead of 'return'
  to avoid getting confused with code examples including the
  C 'return' statement.
* python/generator.py: Preserve all whitespace when printing
  function help docs
* src/libvirt.c: Change any return parameter indicated by
  'return' to be 'returns', to avoid confusing the API extractor
* docs/libvirt-api.xml: Re-build for fixed descriptions
2009-09-28 14:08:25 +01:00

9397 lines
250 KiB
C
Raw Blame History

/*
* libvirt.c: Main interfaces for the libvirt library to handle virtualization
* domains from a process running in domain 0
*
* Copyright (C) 2005,2006,2008,2009 Red Hat, Inc.
*
* See COPYING.LIB for the License of this software
*
* Daniel Veillard <veillard@redhat.com>
*/
#include <config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <assert.h>
#ifdef HAVE_SYS_WAIT_H
#include <sys/wait.h>
#endif
#include <time.h>
#include <libxml/parser.h>
#include <libxml/xpath.h>
#include <libxml/uri.h>
#include "getpass.h"
#ifdef HAVE_WINSOCK2_H
#include <winsock2.h>
#endif
#include "virterror_internal.h"
#include "logging.h"
#include "datatypes.h"
#include "libvirt_internal.h"
#include "driver.h"
#include "uuid.h"
#include "util.h"
#include "memory.h"
#ifndef WITH_DRIVER_MODULES
#ifdef WITH_TEST
#include "test/test_driver.h"
#endif
#ifdef WITH_XEN
#include "xen/xen_driver.h"
#endif
#ifdef WITH_REMOTE
#include "remote/remote_driver.h"
#endif
#ifdef WITH_OPENVZ
#include "openvz/openvz_driver.h"
#endif
#ifdef WITH_PHYP
#include "phyp/phyp_driver.h"
#endif
#ifdef WITH_VBOX
#include "vbox/vbox_driver.h"
#endif
#ifdef WITH_ESX
#include "esx/esx_driver.h"
#endif
#endif
#define VIR_FROM_THIS VIR_FROM_NONE
/*
* TODO:
* - use lock to protect against concurrent accesses ?
* - use reference counting to guarantee coherent pointer state ?
*/
#define MAX_DRIVERS 10
static virDriverPtr virDriverTab[MAX_DRIVERS];
static int virDriverTabCount = 0;
static virNetworkDriverPtr virNetworkDriverTab[MAX_DRIVERS];
static int virNetworkDriverTabCount = 0;
static virInterfaceDriverPtr virInterfaceDriverTab[MAX_DRIVERS];
static int virInterfaceDriverTabCount = 0;
static virStorageDriverPtr virStorageDriverTab[MAX_DRIVERS];
static int virStorageDriverTabCount = 0;
static virDeviceMonitorPtr virDeviceMonitorTab[MAX_DRIVERS];
static int virDeviceMonitorTabCount = 0;
static virSecretDriverPtr virSecretDriverTab[MAX_DRIVERS];
static int virSecretDriverTabCount = 0;
#ifdef WITH_LIBVIRTD
static virStateDriverPtr virStateDriverTab[MAX_DRIVERS];
static int virStateDriverTabCount = 0;
#endif
static int initialized = 0;
#if defined(POLKIT_AUTH)
static int virConnectAuthGainPolkit(const char *privilege) {
const char *const args[] = {
POLKIT_AUTH, "--obtain", privilege, NULL
};
int childpid, status, ret;
/* Root has all rights */
if (getuid() == 0)
return 0;
if ((childpid = fork()) < 0)
return -1;
if (!childpid) {
execvp(args[0], (char **)args);
_exit(-1);
}
while ((ret = waitpid(childpid, &status, 0) == -1) && errno == EINTR);
if (ret == -1) {
return -1;
}
if (!WIFEXITED(status) ||
(WEXITSTATUS(status) != 0 && WEXITSTATUS(status) != 1)) {
return -1;
}
return 0;
}
#endif
static int virConnectAuthCallbackDefault(virConnectCredentialPtr cred,
unsigned int ncred,
void *cbdata ATTRIBUTE_UNUSED) {
int i;
for (i = 0 ; i < ncred ; i++) {
char buf[1024];
char *bufptr = buf;
size_t len;
switch (cred[i].type) {
case VIR_CRED_EXTERNAL: {
if (STRNEQ(cred[i].challenge, "PolicyKit"))
return -1;
#if defined(POLKIT_AUTH)
if (virConnectAuthGainPolkit(cred[i].prompt) < 0)
return -1;
#else
/*
* Ignore & carry on. Although we can't auth
* directly, the user may have authenticated
* themselves already outside context of libvirt
*/
#endif
break;
}
case VIR_CRED_USERNAME:
case VIR_CRED_AUTHNAME:
case VIR_CRED_ECHOPROMPT:
case VIR_CRED_REALM:
if (printf("%s:", cred[i].prompt) < 0)
return -1;
if (fflush(stdout) != 0)
return -1;
if (!fgets(buf, sizeof(buf), stdin)) {
if (feof(stdin)) { /* Treat EOF as "" */
buf[0] = '\0';
break;
}
return -1;
}
len = strlen(buf);
if (len != 0 && buf[len-1] == '\n')
buf[len-1] = '\0';
break;
case VIR_CRED_PASSPHRASE:
case VIR_CRED_NOECHOPROMPT:
if (printf("%s:", cred[i].prompt) < 0)
return -1;
if (fflush(stdout) != 0)
return -1;
bufptr = getpass("");
if (!bufptr)
return -1;
break;
default:
return -1;
}
if (cred[i].type != VIR_CRED_EXTERNAL) {
if (STREQ(bufptr, "") && cred[i].defresult)
cred[i].result = strdup(cred[i].defresult);
else
cred[i].result = strdup(bufptr);
if (!cred[i].result)
return -1;
cred[i].resultlen = strlen(cred[i].result);
}
}
return 0;
}
/* Don't typically want VIR_CRED_USERNAME. It enables you to authenticate
* as one user, and act as another. It just results in annoying
* prompts for the username twice & is very rarely what you want
*/
static int virConnectCredTypeDefault[] = {
VIR_CRED_AUTHNAME,
VIR_CRED_ECHOPROMPT,
VIR_CRED_REALM,
VIR_CRED_PASSPHRASE,
VIR_CRED_NOECHOPROMPT,
VIR_CRED_EXTERNAL,
};
static virConnectAuth virConnectAuthDefault = {
virConnectCredTypeDefault,
sizeof(virConnectCredTypeDefault)/sizeof(int),
virConnectAuthCallbackDefault,
NULL,
};
/*
* virConnectAuthPtrDefault
*
* A default implementation of the authentication callbacks. This
* implementation is suitable for command line based tools. It will
* prompt for username, passwords, realm and one time keys as needed.
* It will print on STDOUT, and read from STDIN. If this is not
* suitable for the application's needs an alternative implementation
* should be provided.
*/
virConnectAuthPtr virConnectAuthPtrDefault = &virConnectAuthDefault;
#if HAVE_WINSOCK2_H
static int
winsock_init (void)
{
WORD winsock_version, err;
WSADATA winsock_data;
/* http://msdn2.microsoft.com/en-us/library/ms742213.aspx */
winsock_version = MAKEWORD (2, 2);
err = WSAStartup (winsock_version, &winsock_data);
return err == 0 ? 0 : -1;
}
#endif
/**
* virInitialize:
*
* Initialize the library. It's better to call this routine at startup
* in multithreaded applications to avoid potential race when initializing
* the library.
*
* Returns 0 in case of success, -1 in case of error
*/
int
virInitialize(void)
{
if (initialized)
return(0);
initialized = 1;
if (virThreadInitialize() < 0 ||
virErrorInitialize() < 0 ||
virRandomInitialize(time(NULL) ^ getpid()))
return -1;
virLogSetFromEnv();
DEBUG0("register drivers");
#if HAVE_WINSOCK2_H
if (winsock_init () == -1) return -1;
#endif
if (!bindtextdomain(GETTEXT_PACKAGE, LOCALEBASEDIR))
return (-1);
/*
* Note that the order is important: the first ones have a higher
* priority when calling virConnectOpen.
*/
#ifdef WITH_DRIVER_MODULES
/* We don't care if any of these fail, because the whole point
* is to allow users to only install modules they want to use.
* If they try to use a open a connection for a module that
* is not loaded they'll get a suitable error at that point
*/
virDriverLoadModule("test");
virDriverLoadModule("xen");
virDriverLoadModule("openvz");
virDriverLoadModule("vbox");
virDriverLoadModule("esx");
virDriverLoadModule("remote");
#else
#ifdef WITH_TEST
if (testRegister() == -1) return -1;
#endif
#ifdef WITH_XEN
if (xenRegister () == -1) return -1;
#endif
#ifdef WITH_OPENVZ
if (openvzRegister() == -1) return -1;
#endif
#ifdef WITH_PHYP
if (phypRegister() == -1) return -1;
#endif
#ifdef WITH_VBOX
if (vboxRegister() == -1) return -1;
#endif
#ifdef WITH_ESX
if (esxRegister() == -1) return -1;
#endif
#ifdef WITH_REMOTE
if (remoteRegister () == -1) return -1;
#endif
#endif
return(0);
}
#ifdef WIN32
BOOL WINAPI
DllMain (HINSTANCE instance, DWORD reason, LPVOID ignore);
BOOL WINAPI
DllMain (HINSTANCE instance ATTRIBUTE_UNUSED,
DWORD reason,
LPVOID ignore ATTRIBUTE_UNUSED)
{
switch (reason) {
case DLL_PROCESS_ATTACH:
virInitialize();
break;
case DLL_THREAD_ATTACH:
/* Nothing todo in libvirt yet */
break;
case DLL_THREAD_DETACH:
/* Release per-thread local data */
virThreadOnExit();
break;
case DLL_PROCESS_DETACH:
/* Don't bother releasing per-thread data
since (hopefully) windows cleans up
everything on process exit */
break;
}
return TRUE;
}
#endif
/**
* virLibConnError:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibConnError(virConnectPtr conn, virErrorNumber error, const char *info)
{
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
virRaiseError(conn, NULL, NULL, VIR_FROM_NONE, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibConnWarning:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibConnWarning(virConnectPtr conn, virErrorNumber error, const char *info)
{
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
virRaiseError(conn, NULL, NULL, VIR_FROM_NONE, error, VIR_ERR_WARNING,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibDomainError:
* @domain: the domain if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibDomainError(virDomainPtr domain, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_DOMAIN) {
conn = domain->conn;
}
virRaiseError(conn, domain, NULL, VIR_FROM_DOM, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibNetworkError:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibNetworkError(virNetworkPtr network, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_NETWORK) {
conn = network->conn;
}
virRaiseError(conn, NULL, network, VIR_FROM_NET, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibInterfaceError:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibInterfaceError(virInterfacePtr iface, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_INTERFACE) {
conn = iface->conn;
}
virRaiseError(conn, NULL, NULL, VIR_FROM_INTERFACE, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibStoragePoolError:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibStoragePoolError(virStoragePoolPtr pool, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_STORAGE_POOL)
conn = pool->conn;
virRaiseError(conn, NULL, NULL, VIR_FROM_STORAGE, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibStorageVolError:
* @conn: the connection if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the connection level
*/
static void
virLibStorageVolError(virStorageVolPtr vol, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_STORAGE_VOL)
conn = vol->conn;
virRaiseError(conn, NULL, NULL, VIR_FROM_STORAGE, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibNodeDeviceError:
* @dev: the device if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the node device level
*/
static void
virLibNodeDeviceError(virNodeDevicePtr dev, virErrorNumber error,
const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_NODE_DEVICE)
conn = dev->conn;
virRaiseError(conn, NULL, NULL, VIR_FROM_NODEDEV, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virLibSecretError:
* @secret: the secret if available
* @error: the error number
* @info: extra information string
*
* Handle an error at the secret level
*/
static void
virLibSecretError(virSecretPtr secret, virErrorNumber error, const char *info)
{
virConnectPtr conn = NULL;
const char *errmsg;
if (error == VIR_ERR_OK)
return;
errmsg = virErrorMsg(error, info);
if (error != VIR_ERR_INVALID_SECRET)
conn = secret->conn;
virRaiseError(conn, NULL, NULL, VIR_FROM_SECRET, error, VIR_ERR_ERROR,
errmsg, info, NULL, 0, 0, errmsg, info);
}
/**
* virRegisterNetworkDriver:
* @driver: pointer to a network driver block
*
* Register a network virtualization driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterNetworkDriver(virNetworkDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virNetworkDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
DEBUG ("registering %s as network driver %d",
driver->name, virNetworkDriverTabCount);
virNetworkDriverTab[virNetworkDriverTabCount] = driver;
return virNetworkDriverTabCount++;
}
/**
* virRegisterInterfaceDriver:
* @driver: pointer to an interface driver block
*
* Register an interface virtualization driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterInterfaceDriver(virInterfaceDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virInterfaceDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
DEBUG ("registering %s as interface driver %d",
driver->name, virInterfaceDriverTabCount);
virInterfaceDriverTab[virInterfaceDriverTabCount] = driver;
return virInterfaceDriverTabCount++;
}
/**
* virRegisterStorageDriver:
* @driver: pointer to a storage driver block
*
* Register a storage virtualization driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterStorageDriver(virStorageDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virStorageDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
DEBUG ("registering %s as storage driver %d",
driver->name, virStorageDriverTabCount);
virStorageDriverTab[virStorageDriverTabCount] = driver;
return virStorageDriverTabCount++;
}
/**
* virRegisterDeviceMonitor:
* @driver: pointer to a device monitor block
*
* Register a device monitor
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterDeviceMonitor(virDeviceMonitorPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virDeviceMonitorTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
DEBUG ("registering %s as device driver %d",
driver->name, virDeviceMonitorTabCount);
virDeviceMonitorTab[virDeviceMonitorTabCount] = driver;
return virDeviceMonitorTabCount++;
}
/**
* virRegisterSecretDriver:
* @driver: pointer to a secret driver block
*
* Register a secret driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterSecretDriver(virSecretDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virSecretDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
DEBUG ("registering %s as secret driver %d",
driver->name, virSecretDriverTabCount);
virSecretDriverTab[virSecretDriverTabCount] = driver;
return virSecretDriverTabCount++;
}
/**
* virRegisterDriver:
* @driver: pointer to a driver block
*
* Register a virtualization driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterDriver(virDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (driver->no < 0) {
virLibConnError
(NULL, VIR_ERR_INVALID_ARG,
"virRegisterDriver: tried to register an internal Xen driver");
return -1;
}
DEBUG ("registering %s as driver %d",
driver->name, virDriverTabCount);
virDriverTab[virDriverTabCount] = driver;
return virDriverTabCount++;
}
#ifdef WITH_LIBVIRTD
/**
* virRegisterStateDriver:
* @driver: pointer to a driver block
*
* Register a virtualization driver
*
* Returns the driver priority or -1 in case of error.
*/
int
virRegisterStateDriver(virStateDriverPtr driver)
{
if (virInitialize() < 0)
return -1;
if (driver == NULL) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
if (virStateDriverTabCount >= MAX_DRIVERS) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virStateDriverTab[virStateDriverTabCount] = driver;
return virStateDriverTabCount++;
}
/**
* virStateInitialize:
* @privileged: set to 1 if running with root priviledge, 0 otherwise
*
* Initialize all virtualization drivers.
*
* Returns 0 if all succeed, -1 upon any failure.
*/
int virStateInitialize(int privileged) {
int i, ret = 0;
if (virInitialize() < 0)
return -1;
for (i = 0 ; i < virStateDriverTabCount ; i++) {
if (virStateDriverTab[i]->initialize &&
virStateDriverTab[i]->initialize(privileged) < 0)
ret = -1;
}
return ret;
}
/**
* virStateCleanup:
*
* Run each virtualization driver's cleanup method.
*
* Returns 0 if all succeed, -1 upon any failure.
*/
int virStateCleanup(void) {
int i, ret = 0;
for (i = 0 ; i < virStateDriverTabCount ; i++) {
if (virStateDriverTab[i]->cleanup &&
virStateDriverTab[i]->cleanup() < 0)
ret = -1;
}
return ret;
}
/**
* virStateReload:
*
* Run each virtualization driver's reload method.
*
* Returns 0 if all succeed, -1 upon any failure.
*/
int virStateReload(void) {
int i, ret = 0;
for (i = 0 ; i < virStateDriverTabCount ; i++) {
if (virStateDriverTab[i]->reload &&
virStateDriverTab[i]->reload() < 0)
ret = -1;
}
return ret;
}
/**
* virStateActive:
*
* Run each virtualization driver's "active" method.
*
* Returns 0 if none are active, 1 if at least one is.
*/
int virStateActive(void) {
int i, ret = 0;
for (i = 0 ; i < virStateDriverTabCount ; i++) {
if (virStateDriverTab[i]->active &&
virStateDriverTab[i]->active())
ret = 1;
}
return ret;
}
#endif
/**
* virGetVersion:
* @libVer: return value for the library version (OUT)
* @type: the type of connection/driver looked at
* @typeVer: return value for the version of the hypervisor (OUT)
*
* Provides two information back, @libVer is the version of the library
* while @typeVer will be the version of the hypervisor type @type against
* which the library was compiled. If @type is NULL, "Xen" is assumed, if
* @type is unknown or not available, an error code will be returned and
* @typeVer will be 0.
*
* Returns -1 in case of failure, 0 otherwise, and values for @libVer and
* @typeVer have the format major * 1,000,000 + minor * 1,000 + release.
*/
int
virGetVersion(unsigned long *libVer, const char *type,
unsigned long *typeVer)
{
DEBUG("libVir=%p, type=%s, typeVer=%p", libVer, type, typeVer);
if (!initialized)
if (virInitialize() < 0)
return -1;
if (libVer == NULL)
return (-1);
*libVer = LIBVIR_VERSION_NUMBER;
if (typeVer != NULL) {
if (type == NULL)
type = "Xen";
/* FIXME: Add _proper_ type version handling for loadable driver modules... */
#ifdef WITH_DRIVER_MODULES
*typeVer = LIBVIR_VERSION_NUMBER;
#else
*typeVer = 0;
#if WITH_XEN
if (STRCASEEQ(type, "Xen"))
*typeVer = xenUnifiedVersion();
#endif
#if WITH_TEST
if (STRCASEEQ(type, "Test"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_QEMU
if (STRCASEEQ(type, "QEMU"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_LXC
if (STRCASEEQ(type, "LXC"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_PHYP
if (STRCASEEQ(type, "phyp"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_OPENVZ
if (STRCASEEQ(type, "OpenVZ"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_VBOX
if (STRCASEEQ(type, "VBox"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_UML
if (STRCASEEQ(type, "UML"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_ONE
if (STRCASEEQ(type, "ONE"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_ESX
if (STRCASEEQ(type, "ESX"))
*typeVer = LIBVIR_VERSION_NUMBER;
#endif
#if WITH_REMOTE
if (STRCASEEQ(type, "Remote"))
*typeVer = remoteVersion();
#endif
if (*typeVer == 0) {
virLibConnError(NULL, VIR_ERR_NO_SUPPORT, type);
return (-1);
}
#endif /* WITH_DRIVER_MODULES */
}
return (0);
}
static virConnectPtr
do_open (const char *name,
virConnectAuthPtr auth,
int flags)
{
int i, res;
virConnectPtr ret;
virResetLastError();
ret = virGetConnect();
if (ret == NULL)
return NULL;
/*
* If no URI is passed, then check for an environment string if not
* available probe the compiled in drivers to find a default hypervisor
* if detectable.
*/
if (!name || name[0] == '\0') {
char *defname = getenv("LIBVIRT_DEFAULT_URI");
if (defname && *defname) {
DEBUG("Using LIBVIRT_DEFAULT_URI %s", defname);
name = defname;
} else {
name = NULL;
}
}
if (name) {
/* Convert xen -> xen:/// for back compat */
if (STRCASEEQ(name, "xen"))
name = "xen:///";
/* Convert xen:// -> xen:/// because xmlParseURI cannot parse the
* former. This allows URIs such as xen://localhost to work.
*/
if (STREQ (name, "xen://"))
name = "xen:///";
ret->uri = xmlParseURI (name);
if (!ret->uri) {
virLibConnError (ret, VIR_ERR_INVALID_ARG,
_("could not parse connection URI"));
goto failed;
}
DEBUG("name \"%s\" to URI components:\n"
" scheme %s\n"
" opaque %s\n"
" authority %s\n"
" server %s\n"
" user %s\n"
" port %d\n"
" path %s\n",
name,
NULLSTR(ret->uri->scheme), NULLSTR(ret->uri->opaque),
NULLSTR(ret->uri->authority), NULLSTR(ret->uri->server),
NULLSTR(ret->uri->user), ret->uri->port,
NULLSTR(ret->uri->path));
} else {
DEBUG0("no name, allowing driver auto-select");
}
/* Cleansing flags */
ret->flags = flags & VIR_CONNECT_RO;
for (i = 0; i < virDriverTabCount; i++) {
DEBUG("trying driver %d (%s) ...",
i, virDriverTab[i]->name);
res = virDriverTab[i]->open (ret, auth, flags);
DEBUG("driver %d %s returned %s",
i, virDriverTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) goto failed;
else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->driver = virDriverTab[i];
break;
}
}
if (!ret->driver) {
/* If we reach here, then all drivers declined the connection. */
virLibConnError (NULL, VIR_ERR_NO_CONNECT, name);
goto failed;
}
for (i = 0; i < virNetworkDriverTabCount; i++) {
res = virNetworkDriverTab[i]->open (ret, auth, flags);
DEBUG("network driver %d %s returned %s",
i, virNetworkDriverTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) {
if (STREQ(virNetworkDriverTab[i]->name, "remote")) {
virLibConnWarning (NULL, VIR_WAR_NO_NETWORK,
"Is the daemon running ?");
}
break;
} else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->networkDriver = virNetworkDriverTab[i];
break;
}
}
for (i = 0; i < virInterfaceDriverTabCount; i++) {
res = virInterfaceDriverTab[i]->open (ret, auth, flags);
DEBUG("interface driver %d %s returned %s",
i, virInterfaceDriverTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) {
if (STREQ(virInterfaceDriverTab[i]->name, "remote")) {
virLibConnWarning (NULL, VIR_WAR_NO_INTERFACE,
"Is the daemon running ?");
}
break;
} else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->interfaceDriver = virInterfaceDriverTab[i];
break;
}
}
/* Secondary driver for storage. Optional */
for (i = 0; i < virStorageDriverTabCount; i++) {
res = virStorageDriverTab[i]->open (ret, auth, flags);
DEBUG("storage driver %d %s returned %s",
i, virStorageDriverTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) {
if (0 && STREQ(virStorageDriverTab[i]->name, "remote")) {
virLibConnWarning (NULL, VIR_WAR_NO_STORAGE,
"Is the daemon running ?");
}
break;
} else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->storageDriver = virStorageDriverTab[i];
break;
}
}
/* Node driver (optional) */
for (i = 0; i < virDeviceMonitorTabCount; i++) {
res = virDeviceMonitorTab[i]->open (ret, auth, flags);
DEBUG("node driver %d %s returned %s",
i, virDeviceMonitorTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) {
if (STREQ(virDeviceMonitorTab[i]->name, "remote")) {
virLibConnWarning (NULL, VIR_WAR_NO_NODE,
"Is the libvirtd daemon running ?");
} else {
char *msg;
if (virAsprintf(&msg, "Is the %s daemon running?",
virDeviceMonitorTab[i]->name) > 0) {
virLibConnWarning (NULL, VIR_WAR_NO_NODE, msg);
VIR_FREE(msg);
}
}
break;
} else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->deviceMonitor = virDeviceMonitorTab[i];
break;
}
}
/* Secret manipulation driver. Optional */
for (i = 0; i < virSecretDriverTabCount; i++) {
res = virSecretDriverTab[i]->open (ret, auth, flags);
DEBUG("secret driver %d %s returned %s",
i, virSecretDriverTab[i]->name,
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
if (res == VIR_DRV_OPEN_ERROR) {
if (STREQ(virSecretDriverTab[i]->name, "remote")) {
virLibConnWarning (NULL, VIR_WAR_NO_SECRET,
"Is the daemon running ?");
}
break;
} else if (res == VIR_DRV_OPEN_SUCCESS) {
ret->secretDriver = virSecretDriverTab[i];
break;
}
}
return ret;
failed:
/* Ensure a global error is set in case driver forgot */
virSetGlobalError();
virUnrefConnect(ret);
return NULL;
}
/**
* virConnectOpen:
* @name: URI of the hypervisor
*
* This function should be called first to get a connection to the
* Hypervisor and xen store
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* If @name is NULL then probing will be done to determine a suitable
* default driver to activate. This involves trying each hypervisor
* in turn until one successfully opens. If the LIBVIRT_DEFAULT_URI
* environment variable is set, then it will be used in preference
* to probing for a driver.
*
* If connecting to an unprivileged hypervisor driver which requires
* the libvirtd daemon to be active, it will automatically be launched
* if not already running. This can be prevented by setting the
* environment variable LIBVIRT_AUTOSTART=0
*
* URIs are documented at http://libvirt.org/uri.html
*/
virConnectPtr
virConnectOpen (const char *name)
{
if (!initialized)
if (virInitialize() < 0)
return NULL;
DEBUG("name=%s", name);
return do_open (name, NULL, 0);
}
/**
* virConnectOpenReadOnly:
* @name: URI of the hypervisor
*
* This function should be called first to get a restricted connection to the
* library functionalities. The set of APIs usable are then restricted
* on the available methods to control the domains.
*
* See virConnectOpen for notes about environment variables which can
* have an effect on opening drivers
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* URIs are documented at http://libvirt.org/uri.html
*/
virConnectPtr
virConnectOpenReadOnly(const char *name)
{
if (!initialized)
if (virInitialize() < 0)
return NULL;
DEBUG("name=%s", name);
return do_open (name, NULL, VIR_CONNECT_RO);
}
/**
* virConnectOpenAuth:
* @name: URI of the hypervisor
* @auth: Authenticate callback parameters
* @flags: Open flags
*
* This function should be called first to get a connection to the
* Hypervisor. If necessary, authentication will be performed fetching
* credentials via the callback
*
* See virConnectOpen for notes about environment variables which can
* have an effect on opening drivers
*
* Returns a pointer to the hypervisor connection or NULL in case of error
*
* URIs are documented at http://libvirt.org/uri.html
*/
virConnectPtr
virConnectOpenAuth(const char *name,
virConnectAuthPtr auth,
int flags)
{
if (!initialized)
if (virInitialize() < 0)
return NULL;
DEBUG("name=%s, auth=%p, flags=%d", NULLSTR(name), auth, flags);
return do_open (name, auth, flags);
}
/**
* virConnectClose:
* @conn: pointer to the hypervisor connection
*
* This function closes the connection to the Hypervisor. This should
* not be called if further interaction with the Hypervisor are needed
* especially if there is running domain which need further monitoring by
* the application.
*
* Returns 0 in case of success or -1 in case of error.
*/
int
virConnectClose(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
return virUnrefConnect(conn);
}
/**
* virConnectRef:
* @conn: the connection to hold a reference on
*
* Increment the reference count on the connection. For each
* additional call to this method, there shall be a corresponding
* call to virConnectClose to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a connection would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure
*/
int
virConnectRef(virConnectPtr conn)
{
if ((!VIR_IS_CONNECT(conn))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&conn->lock);
DEBUG("conn=%p refs=%d", conn, conn->refs);
conn->refs++;
virMutexUnlock(&conn->lock);
return 0;
}
/*
* Not for public use. This function is part of the internal
* implementation of driver features in the remote case.
*/
int
virDrvSupportsFeature (virConnectPtr conn, int feature)
{
int ret;
DEBUG("conn=%p, feature=%d", conn, feature);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
ret = VIR_DRV_SUPPORTS_FEATURE (conn->driver, conn, feature);
if (ret < 0)
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return ret;
}
/**
* virConnectGetType:
* @conn: pointer to the hypervisor connection
*
* Get the name of the Hypervisor software used.
*
* Returns NULL in case of error, a static zero terminated string otherwise.
*
* See also:
* http://www.redhat.com/archives/libvir-list/2007-February/msg00096.html
*/
const char *
virConnectGetType(virConnectPtr conn)
{
const char *ret;
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (conn->driver->type) {
ret = conn->driver->type (conn);
if (ret) return ret;
}
return conn->driver->name;
}
/**
* virConnectGetVersion:
* @conn: pointer to the hypervisor connection
* @hvVer: return value for the version of the running hypervisor (OUT)
*
* Get the version level of the Hypervisor running. This may work only with
* hypervisor call, i.e. with privileged access to the hypervisor, not
* with a Read-Only connection.
*
* Returns -1 in case of error, 0 otherwise. if the version can't be
* extracted by lack of capacities returns 0 and @hvVer is 0, otherwise
* @hvVer value is major * 1,000,000 + minor * 1,000 + release
*/
int
virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
{
DEBUG("conn=%p, hvVer=%p", conn, hvVer);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (hvVer == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->version) {
int ret = conn->driver->version (conn, hvVer);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectGetHostname:
* @conn: pointer to a hypervisor connection
*
* This returns the system hostname on which the hypervisor is
* running (the result of the gethostname(2) system call). If
* we are connected to a remote system, then this returns the
* hostname of the remote system.
*
* Returns the hostname which must be freed by the caller, or
* NULL if there was an error.
*/
char *
virConnectGetHostname (virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (conn->driver->getHostname) {
char *ret = conn->driver->getHostname (conn);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virConnectGetURI:
* @conn: pointer to a hypervisor connection
*
* This returns the URI (name) of the hypervisor connection.
* Normally this is the same as or similar to the string passed
* to the virConnectOpen/virConnectOpenReadOnly call, but
* the driver may make the URI canonical. If name == NULL
* was passed to virConnectOpen, then the driver will return
* a non-NULL URI which can be used to connect to the same
* hypervisor later.
*
* Returns the URI string which must be freed by the caller, or
* NULL if there was an error.
*/
char *
virConnectGetURI (virConnectPtr conn)
{
char *name;
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
name = (char *)xmlSaveUri(conn->uri);
if (!name) {
virReportOOMError (conn);
goto error;
}
return name;
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virConnectGetMaxVcpus:
* @conn: pointer to the hypervisor connection
* @type: value of the 'type' attribute in the <domain> element
*
* Provides the maximum number of virtual CPUs supported for a guest VM of a
* specific type. The 'type' parameter here corresponds to the 'type'
* attribute in the <domain> element of the XML.
*
* Returns the maximum of virtual CPU or -1 in case of error.
*/
int
virConnectGetMaxVcpus(virConnectPtr conn,
const char *type)
{
DEBUG("conn=%p, type=%s", conn, type);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (conn->driver->getMaxVcpus) {
int ret = conn->driver->getMaxVcpus (conn, type);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListDomains:
* @conn: pointer to the hypervisor connection
* @ids: array to collect the list of IDs of active domains
* @maxids: size of @ids
*
* Collect the list of active domains, and store their ID in @maxids
*
* Returns the number of domain found or -1 in case of error
*/
int
virConnectListDomains(virConnectPtr conn, int *ids, int maxids)
{
DEBUG("conn=%p, ids=%p, maxids=%d", conn, ids, maxids);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if ((ids == NULL) || (maxids < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->listDomains) {
int ret = conn->driver->listDomains (conn, ids, maxids);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectNumOfDomains:
* @conn: pointer to the hypervisor connection
*
* Provides the number of active domains.
*
* Returns the number of domain found or -1 in case of error
*/
int
virConnectNumOfDomains(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (conn->driver->numOfDomains) {
int ret = conn->driver->numOfDomains (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virDomainGetConnect:
* @dom: pointer to a domain
*
* Provides the connection pointer associated with a domain. The
* reference counter on the connection is not increased by this
* call.
*
* WARNING: When writing libvirt bindings in other languages, do
* not use this function. Instead, store the connection and
* the domain object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virDomainGetConnect (virDomainPtr dom)
{
DEBUG("dom=%p", dom);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return NULL;
}
return dom->conn;
}
/**
* virDomainCreateXML:
* @conn: pointer to the hypervisor connection
* @xmlDesc: string containing an XML description of the domain
* @flags: callers should always pass 0
*
* Launch a new guest domain, based on an XML description similar
* to the one returned by virDomainGetXMLDesc()
* This function may requires privileged access to the hypervisor.
* The domain is not persistent, so its definition will disappear when it
* is destroyed, or if the host is restarted (see virDomainDefineXML() to
* define persistent domains).
*
* Returns a new domain object or NULL in case of failure
*/
virDomainPtr
virDomainCreateXML(virConnectPtr conn, const char *xmlDesc,
unsigned int flags)
{
DEBUG("conn=%p, xmlDesc=%s, flags=%d", conn, xmlDesc, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (xmlDesc == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainCreateXML) {
virDomainPtr ret;
ret = conn->driver->domainCreateXML (conn, xmlDesc, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainCreateLinux:
* @conn: pointer to the hypervisor connection
* @xmlDesc: string containing an XML description of the domain
* @flags: callers should always pass 0
*
* Deprecated after 0.4.6.
* Renamed to virDomainCreateXML() providing identical functionality.
* This existing name will left indefinitely for API compatability.
*
* Returns a new domain object or NULL in case of failure
*/
virDomainPtr
virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
unsigned int flags)
{
return(virDomainCreateXML(conn, xmlDesc, flags));
}
/**
* virDomainLookupByID:
* @conn: pointer to the hypervisor connection
* @id: the domain ID number
*
* Try to find a domain based on the hypervisor ID number
* Note that this won't work for inactive domains which have an ID of -1,
* in that case a lookup based on the Name or UUId need to be done instead.
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
virDomainPtr
virDomainLookupByID(virConnectPtr conn, int id)
{
DEBUG("conn=%p, id=%d", conn, id);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (id < 0) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->domainLookupByID) {
virDomainPtr ret;
ret = conn->driver->domainLookupByID (conn, id);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainLookupByUUID:
* @conn: pointer to the hypervisor connection
* @uuid: the raw UUID for the domain
*
* Try to lookup a domain on the given hypervisor based on its UUID.
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
virDomainPtr
virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
{
DEBUG("conn=%p, uuid=%s", conn, uuid);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuid == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->domainLookupByUUID) {
virDomainPtr ret;
ret = conn->driver->domainLookupByUUID (conn, uuid);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainLookupByUUIDString:
* @conn: pointer to the hypervisor connection
* @uuidstr: the string UUID for the domain
*
* Try to lookup a domain on the given hypervisor based on its UUID.
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
virDomainPtr
virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
{
int raw[VIR_UUID_BUFLEN], i;
unsigned char uuid[VIR_UUID_BUFLEN];
int ret;
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuidstr == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/* XXX: sexpr_uuid() also supports 'xxxx-xxxx-xxxx-xxxx' format.
* We needn't it here. Right?
*/
ret = sscanf(uuidstr,
"%02x%02x%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x%02x%02x%02x%02x",
raw + 0, raw + 1, raw + 2, raw + 3,
raw + 4, raw + 5, raw + 6, raw + 7,
raw + 8, raw + 9, raw + 10, raw + 11,
raw + 12, raw + 13, raw + 14, raw + 15);
if (ret!=VIR_UUID_BUFLEN) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
for (i = 0; i < VIR_UUID_BUFLEN; i++)
uuid[i] = raw[i] & 0xFF;
return virDomainLookupByUUID(conn, &uuid[0]);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainLookupByName:
* @conn: pointer to the hypervisor connection
* @name: name for the domain
*
* Try to lookup a domain on the given hypervisor based on its name.
*
* Returns a new domain object or NULL in case of failure. If the
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
*/
virDomainPtr
virDomainLookupByName(virConnectPtr conn, const char *name)
{
DEBUG("conn=%p, name=%s", conn, name);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (name == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->domainLookupByName) {
virDomainPtr dom;
dom = conn->driver->domainLookupByName (conn, name);
if (!dom)
goto error;
return dom;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainDestroy:
* @domain: a domain object
*
* Destroy the domain object. The running instance is shutdown if not down
* already and all resources used by it are given back to the hypervisor. This
* does not free the associated virDomainPtr object.
* This function may require privileged access
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainDestroy(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
conn = domain->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainDestroy) {
int ret;
ret = conn->driver->domainDestroy (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virDomainFree:
* @domain: a domain object
*
* Free the domain object. The running instance is kept alive.
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainFree(virDomainPtr domain)
{
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (virUnrefDomain(domain) < 0)
return -1;
return(0);
}
/**
* virDomainRef:
* @domain: the domain to hold a reference on
*
* Increment the reference count on the domain. For each
* additional call to this method, there shall be a corresponding
* call to virDomainFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a domain would increment
* the reference count.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainRef(virDomainPtr domain)
{
if ((!VIR_IS_CONNECTED_DOMAIN(domain))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&domain->conn->lock);
DEBUG("domain=%p refs=%d", domain, domain->refs);
domain->refs++;
virMutexUnlock(&domain->conn->lock);
return 0;
}
/**
* virDomainSuspend:
* @domain: a domain object
*
* Suspends an active domain, the process is frozen without further access
* to CPU resources and I/O but the memory used by the domain at the
* hypervisor level will stay allocated. Use virDomainResume() to reactivate
* the domain.
* This function may requires privileged access.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainSuspend(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainSuspend) {
int ret;
ret = conn->driver->domainSuspend (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainResume:
* @domain: a domain object
*
* Resume an suspended domain, the process is restarted from the state where
* it was frozen by calling virSuspendDomain().
* This function may requires privileged access
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainResume(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainResume) {
int ret;
ret = conn->driver->domainResume (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainSave:
* @domain: a domain object
* @to: path for the output file
*
* This method will suspend a domain and save its memory contents to
* a file on disk. After the call, if successful, the domain is not
* listed as running anymore (this may be a problem).
* Use virDomainRestore() to restore a domain after saving.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainSave(virDomainPtr domain, const char *to)
{
char filepath[4096];
virConnectPtr conn;
DEBUG("domain=%p, to=%s", domain, to);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (to == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/*
* We must absolutize the file path as the save is done out of process
* TODO: check for URI when libxml2 is linked in.
*/
if (to[0] != '/') {
unsigned int len, t;
t = strlen(to);
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL)
return (-1);
len = strlen(filepath);
/* that should be covered by getcwd() semantic, but be 100% sure */
if (len > sizeof(filepath) - (t + 3))
return (-1);
filepath[len] = '/';
strcpy(&filepath[len + 1], to);
to = &filepath[0];
}
if (conn->driver->domainSave) {
int ret;
ret = conn->driver->domainSave (domain, to);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainRestore:
* @conn: pointer to the hypervisor connection
* @from: path to the
*
* This method will restore a domain saved to disk by virDomainSave().
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainRestore(virConnectPtr conn, const char *from)
{
char filepath[4096];
DEBUG("conn=%p, from=%s", conn, from);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (from == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/*
* We must absolutize the file path as the restore is done out of process
* TODO: check for URI when libxml2 is linked in.
*/
if (from[0] != '/') {
unsigned int len, t;
t = strlen(from);
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL) {
virLibConnError(conn, VIR_ERR_SYSTEM_ERROR,
_("cannot get working directory"));
goto error;
}
len = strlen(filepath);
/* that should be covered by getcwd() semantic, but be 100% sure */
if (len > sizeof(filepath) - (t + 3)) {
virLibConnError(conn, VIR_ERR_INTERNAL_ERROR,
_("path too long"));
goto error;
}
filepath[len] = '/';
strcpy(&filepath[len + 1], from);
from = &filepath[0];
}
if (conn->driver->domainRestore) {
int ret;
ret = conn->driver->domainRestore (conn, from);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virDomainCoreDump:
* @domain: a domain object
* @to: path for the core file
* @flags: extra flags, currently unused
*
* This method will dump the core of a domain on a given file for analysis.
* Note that for remote Xen Daemon the file path will be interpreted in
* the remote host.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainCoreDump(virDomainPtr domain, const char *to, int flags)
{
char filepath[4096];
virConnectPtr conn;
DEBUG("domain=%p, to=%s, flags=%d", domain, to, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (to == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/*
* We must absolutize the file path as the save is done out of process
* TODO: check for URI when libxml2 is linked in.
*/
if (to[0] != '/') {
unsigned int len, t;
t = strlen(to);
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL) {
virLibDomainError(domain, VIR_ERR_SYSTEM_ERROR,
_("cannot get current directory"));
goto error;
}
len = strlen(filepath);
/* that should be covered by getcwd() semantic, but be 100% sure */
if (len > sizeof(filepath) - (t + 3)) {
virLibDomainError(domain, VIR_ERR_INTERNAL_ERROR,
_("path too long"));
goto error;
}
filepath[len] = '/';
strcpy(&filepath[len + 1], to);
to = &filepath[0];
}
if (conn->driver->domainCoreDump) {
int ret;
ret = conn->driver->domainCoreDump (domain, to, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainShutdown:
* @domain: a domain object
*
* Shutdown a domain, the domain object is still usable there after but
* the domain OS is being stopped. Note that the guest OS may ignore the
* request.
*
* TODO: should we add an option for reboot, knowing it may not be doable
* in the general case ?
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainShutdown(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainShutdown) {
int ret;
ret = conn->driver->domainShutdown (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainReboot:
* @domain: a domain object
* @flags: extra flags for the reboot operation, not used yet
*
* Reboot a domain, the domain object is still usable there after but
* the domain OS is being stopped for a restart.
* Note that the guest OS may ignore the request.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainReboot(virDomainPtr domain, unsigned int flags)
{
virConnectPtr conn;
DEBUG("domain=%p, flags=%u", domain, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainReboot) {
int ret;
ret = conn->driver->domainReboot (domain, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetName:
* @domain: a domain object
*
* Get the public name for that domain
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the domain object.
*/
const char *
virDomainGetName(virDomainPtr domain)
{
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (NULL);
}
return (domain->name);
}
/**
* virDomainGetUUID:
* @domain: a domain object
* @uuid: pointer to a VIR_UUID_BUFLEN bytes array
*
* Get the UUID for a domain
*
* Returns -1 in case of error, 0 in case of success
*/
int
virDomainGetUUID(virDomainPtr domain, unsigned char *uuid)
{
DEBUG("domain=%p, uuid=%p", domain, uuid);
virResetLastError();
if (!VIR_IS_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (uuid == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return (-1);
}
memcpy(uuid, &domain->uuid[0], VIR_UUID_BUFLEN);
return (0);
}
/**
* virDomainGetUUIDString:
* @domain: a domain object
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
*
* Get the UUID for a domain as string. For more information about
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virDomainGetUUIDString(virDomainPtr domain, char *buf)
{
unsigned char uuid[VIR_UUID_BUFLEN];
DEBUG("domain=%p, buf=%p", domain, buf);
virResetLastError();
if (!VIR_IS_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (buf == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (virDomainGetUUID(domain, &uuid[0]))
goto error;
virUUIDFormat(uuid, buf);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetID:
* @domain: a domain object
*
* Get the hypervisor ID number for the domain
*
* Returns the domain ID number or (unsigned int) -1 in case of error
*/
unsigned int
virDomainGetID(virDomainPtr domain)
{
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return ((unsigned int) -1);
}
return (domain->id);
}
/**
* virDomainGetOSType:
* @domain: a domain object
*
* Get the type of domain operation system.
*
* Returns the new string or NULL in case of error, the string must be
* freed by the caller.
*/
char *
virDomainGetOSType(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (NULL);
}
conn = domain->conn;
if (conn->driver->domainGetOSType) {
char *ret;
ret = conn->driver->domainGetOSType (domain);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return NULL;
}
/**
* virDomainGetMaxMemory:
* @domain: a domain object or NULL
*
* Retrieve the maximum amount of physical memory allocated to a
* domain. If domain is NULL, then this get the amount of memory reserved
* to Domain0 i.e. the domain where the application runs.
*
* Returns the memory size in kilobytes or 0 in case of error.
*/
unsigned long
virDomainGetMaxMemory(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (0);
}
conn = domain->conn;
if (conn->driver->domainGetMaxMemory) {
unsigned long ret;
ret = conn->driver->domainGetMaxMemory (domain);
if (ret == 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return 0;
}
/**
* virDomainSetMaxMemory:
* @domain: a domain object or NULL
* @memory: the memory size in kilobytes
*
* Dynamically change the maximum amount of physical memory allocated to a
* domain. If domain is NULL, then this change the amount of memory reserved
* to Domain0 i.e. the domain where the application runs.
* This function requires privileged access to the hypervisor.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory)
{
virConnectPtr conn;
DEBUG("domain=%p, memory=%lu", domain, memory);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (memory < 4096) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainSetMaxMemory) {
int ret;
ret = conn->driver->domainSetMaxMemory (domain, memory);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainSetMemory:
* @domain: a domain object or NULL
* @memory: the memory size in kilobytes
*
* Dynamically change the target amount of physical memory allocated to a
* domain. If domain is NULL, then this change the amount of memory reserved
* to Domain0 i.e. the domain where the application runs.
* This function may requires privileged access to the hypervisor.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainSetMemory(virDomainPtr domain, unsigned long memory)
{
virConnectPtr conn;
DEBUG("domain=%p, memory=%lu", domain, memory);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (memory < 4096) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainSetMemory) {
int ret;
ret = conn->driver->domainSetMemory (domain, memory);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetInfo:
* @domain: a domain object
* @info: pointer to a virDomainInfo structure allocated by the user
*
* Extract information about a domain. Note that if the connection
* used to get the domain is limited only a partial set of the information
* can be extracted.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info)
{
virConnectPtr conn;
DEBUG("domain=%p, info=%p", domain, info);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (info == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
memset(info, 0, sizeof(virDomainInfo));
conn = domain->conn;
if (conn->driver->domainGetInfo) {
int ret;
ret = conn->driver->domainGetInfo (domain, info);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetXMLDesc:
* @domain: a domain object
* @flags: an OR'ed set of virDomainXMLFlags
*
* Provide an XML description of the domain. The description may be reused
* later to relaunch the domain with virDomainCreateXML().
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
char *
virDomainGetXMLDesc(virDomainPtr domain, int flags)
{
virConnectPtr conn;
DEBUG("domain=%p, flags=%d", domain, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (NULL);
}
conn = domain->conn;
if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED,
_("virDomainGetXMLDesc with secure flag"));
goto error;
}
flags &= VIR_DOMAIN_XML_FLAGS_MASK;
if (conn->driver->domainDumpXML) {
char *ret;
ret = conn->driver->domainDumpXML (domain, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return NULL;
}
/**
* virConnectDomainXMLFromNative:
* @conn: a connection object
* @nativeFormat: configuration format importing from
* @nativeConfig: the configuration data to import
* @flags: currently unused, pass 0
*
* Reads native configuration data describing a domain, and
* generates libvirt domain XML. The format of the native
* data is hypervisor dependant.
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
char *virConnectDomainXMLFromNative(virConnectPtr conn,
const char *nativeFormat,
const char *nativeConfig,
unsigned int flags)
{
DEBUG("conn=%p, format=%s config=%s flags=%u", conn, nativeFormat, nativeConfig, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (nativeFormat == NULL || nativeConfig == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
return (NULL);
}
if (conn->driver->domainXMLFromNative) {
char *ret;
ret = conn->driver->domainXMLFromNative (conn,
nativeFormat,
nativeConfig,
flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virConnectDomainXMLToNative:
* @conn: a connection object
* @nativeFormat: configuration format exporting to
* @domainXml: the domain configuration to export
* @flags: currently unused, pass 0
*
* Reads a domain XML configuration document, and generates
* generates a native configuration file describing the domain.
* The format of the native data is hypervisor dependant.
*
* Returns a 0 terminated UTF-8 encoded native config datafile, or NULL in case of error.
* the caller must free() the returned value.
*/
char *virConnectDomainXMLToNative(virConnectPtr conn,
const char *nativeFormat,
const char *domainXml,
unsigned int flags)
{
DEBUG("conn=%p, format=%s xml=%s flags=%u", conn, nativeFormat, domainXml, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (nativeFormat == NULL || domainXml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
return (NULL);
}
if (conn->driver->domainXMLToNative) {
char *ret;
ret = conn->driver->domainXMLToNative(conn,
nativeFormat,
domainXml,
flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
static virDomainPtr
virDomainMigrateVersion1 (virDomainPtr domain,
virConnectPtr dconn,
unsigned long flags,
const char *dname,
const char *uri,
unsigned long bandwidth)
{
virDomainPtr ddomain = NULL;
char *uri_out = NULL;
char *cookie = NULL;
int cookielen = 0;
/* Prepare the migration.
*
* The destination host may return a cookie, or leave cookie as
* NULL.
*
* The destination host MUST set uri_out if uri_in is NULL.
*
* If uri_in is non-NULL, then the destination host may modify
* the URI by setting uri_out. If it does not wish to modify
* the URI, it should leave uri_out as NULL.
*/
if (dconn->driver->domainMigratePrepare
(dconn, &cookie, &cookielen, uri, &uri_out, flags, dname,
bandwidth) == -1)
goto done;
if (uri == NULL && uri_out == NULL) {
virLibConnError (domain->conn, VIR_ERR_INTERNAL_ERROR,
_("domainMigratePrepare did not set uri"));
goto done;
}
if (uri_out)
uri = uri_out; /* Did domainMigratePrepare change URI? */
assert (uri != NULL);
/* Perform the migration. The driver isn't supposed to return
* until the migration is complete.
*/
if (domain->conn->driver->domainMigratePerform
(domain, cookie, cookielen, uri, flags, dname, bandwidth) == -1)
goto done;
/* Get the destination domain and return it or error.
* 'domain' no longer actually exists at this point
* (or so we hope), but we still use the object in memory
* in order to get the name.
*/
dname = dname ? dname : domain->name;
if (dconn->driver->domainMigrateFinish)
ddomain = dconn->driver->domainMigrateFinish
(dconn, dname, cookie, cookielen, uri, flags);
else
ddomain = virDomainLookupByName (dconn, dname);
done:
VIR_FREE (uri_out);
VIR_FREE (cookie);
return ddomain;
}
static virDomainPtr
virDomainMigrateVersion2 (virDomainPtr domain,
virConnectPtr dconn,
unsigned long flags,
const char *dname,
const char *uri,
unsigned long bandwidth)
{
virDomainPtr ddomain = NULL;
char *uri_out = NULL;
char *cookie = NULL;
char *dom_xml = NULL;
int cookielen = 0, ret;
/* Prepare the migration.
*
* The destination host may return a cookie, or leave cookie as
* NULL.
*
* The destination host MUST set uri_out if uri_in is NULL.
*
* If uri_in is non-NULL, then the destination host may modify
* the URI by setting uri_out. If it does not wish to modify
* the URI, it should leave uri_out as NULL.
*/
/* In version 2 of the protocol, the prepare step is slightly
* different. We fetch the domain XML of the source domain
* and pass it to Prepare2.
*/
if (!domain->conn->driver->domainDumpXML) {
virLibConnError (domain->conn, VIR_ERR_INTERNAL_ERROR, __FUNCTION__);
return NULL;
}
dom_xml = domain->conn->driver->domainDumpXML (domain,
VIR_DOMAIN_XML_SECURE);
if (!dom_xml)
return NULL;
ret = dconn->driver->domainMigratePrepare2
(dconn, &cookie, &cookielen, uri, &uri_out, flags, dname,
bandwidth, dom_xml);
VIR_FREE (dom_xml);
if (ret == -1)
goto done;
if (uri == NULL && uri_out == NULL) {
virLibConnError (domain->conn, VIR_ERR_INTERNAL_ERROR,
_("domainMigratePrepare2 did not set uri"));
goto done;
}
if (uri_out)
uri = uri_out; /* Did domainMigratePrepare2 change URI? */
assert (uri != NULL);
/* Perform the migration. The driver isn't supposed to return
* until the migration is complete.
*/
ret = domain->conn->driver->domainMigratePerform
(domain, cookie, cookielen, uri, flags, dname, bandwidth);
/* In version 2 of the migration protocol, we pass the
* status code from the sender to the destination host,
* so it can do any cleanup if the migration failed.
*/
dname = dname ? dname : domain->name;
ddomain = dconn->driver->domainMigrateFinish2
(dconn, dname, cookie, cookielen, uri, flags, ret);
done:
VIR_FREE (uri_out);
VIR_FREE (cookie);
return ddomain;
}
/**
* virDomainMigrate:
* @domain: a domain object
* @dconn: destination host (a connection object)
* @flags: flags
* @dname: (optional) rename domain to this at destination
* @uri: (optional) dest hostname/URI as seen from the source host
* @bandwidth: (optional) specify migration bandwidth limit in Mbps
*
* Migrate the domain object from its current host to the destination
* host given by dconn (a connection to the destination host).
*
* Flags may be one of more of the following:
* VIR_MIGRATE_LIVE Attempt a live migration.
*
* If a hypervisor supports renaming domains during migration,
* then you may set the dname parameter to the new name (otherwise
* it keeps the same name). If this is not supported by the
* hypervisor, dname must be NULL or else you will get an error.
*
* Since typically the two hypervisors connect directly to each
* other in order to perform the migration, you may need to specify
* a path from the source to the destination. This is the purpose
* of the uri parameter. If uri is NULL, then libvirt will try to
* find the best method. Uri may specify the hostname or IP address
* of the destination host as seen from the source. Or uri may be
* a URI giving transport, hostname, user, port, etc. in the usual
* form. Refer to driver documentation for the particular URIs
* supported.
*
* The maximum bandwidth (in Mbps) that will be used to do migration
* can be specified with the bandwidth parameter. If set to 0,
* libvirt will choose a suitable default. Some hypervisors do
* not support this feature and will return an error if bandwidth
* is not 0.
*
* To see which features are supported by the current hypervisor,
* see virConnectGetCapabilities, /capabilities/host/migration_features.
*
* There are many limitations on migration imposed by the underlying
* technology - for example it may not be possible to migrate between
* different processors even with the same architecture, or between
* different types of hypervisor.
*
* Returns the new domain object if the migration was successful,
* or NULL in case of error. Note that the new domain object
* exists in the scope of the destination connection (dconn).
*/
virDomainPtr
virDomainMigrate (virDomainPtr domain,
virConnectPtr dconn,
unsigned long flags,
const char *dname,
const char *uri,
unsigned long bandwidth)
{
virDomainPtr ddomain = NULL;
DEBUG("domain=%p, dconn=%p, flags=%lu, dname=%s, uri=%s, bandwidth=%lu",
domain, dconn, flags, NULLSTR(dname), NULLSTR(uri), bandwidth);
virResetLastError();
/* First checkout the source */
if (!VIR_IS_CONNECTED_DOMAIN (domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return NULL;
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
/* Now checkout the destination */
if (!VIR_IS_CONNECT (dconn)) {
virLibConnError (domain->conn, VIR_ERR_INVALID_CONN, __FUNCTION__);
goto error;
}
if (dconn->flags & VIR_CONNECT_RO) {
/* NB, deliberately report error against source object, not dest */
virLibDomainError (domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
/* Check that migration is supported by both drivers. */
if (VIR_DRV_SUPPORTS_FEATURE (domain->conn->driver, domain->conn,
VIR_DRV_FEATURE_MIGRATION_V1) &&
VIR_DRV_SUPPORTS_FEATURE (dconn->driver, dconn,
VIR_DRV_FEATURE_MIGRATION_V1))
ddomain = virDomainMigrateVersion1 (domain, dconn, flags, dname, uri, bandwidth);
else if (VIR_DRV_SUPPORTS_FEATURE (domain->conn->driver, domain->conn,
VIR_DRV_FEATURE_MIGRATION_V2) &&
VIR_DRV_SUPPORTS_FEATURE (dconn->driver, dconn,
VIR_DRV_FEATURE_MIGRATION_V2))
ddomain = virDomainMigrateVersion2 (domain, dconn, flags, dname, uri, bandwidth);
else {
virLibConnError (domain->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
goto error;
}
if (ddomain == NULL)
goto error;
return ddomain;
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return NULL;
}
/*
* Not for public use. This function is part of the internal
* implementation of migration in the remote case.
*/
int
virDomainMigratePrepare (virConnectPtr dconn,
char **cookie,
int *cookielen,
const char *uri_in,
char **uri_out,
unsigned long flags,
const char *dname,
unsigned long bandwidth)
{
VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p, "
"flags=%lu, dname=%s, bandwidth=%lu", dconn, cookie, cookielen,
NULLSTR(uri_in), uri_out, flags, NULLSTR(dname), bandwidth);
virResetLastError();
if (!VIR_IS_CONNECT (dconn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (dconn->flags & VIR_CONNECT_RO) {
virLibConnError(dconn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (dconn->driver->domainMigratePrepare) {
int ret;
ret = dconn->driver->domainMigratePrepare (dconn, cookie, cookielen,
uri_in, uri_out,
flags, dname, bandwidth);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (dconn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dconn);
return -1;
}
/*
* Not for public use. This function is part of the internal
* implementation of migration in the remote case.
*/
int
virDomainMigratePerform (virDomainPtr domain,
const char *cookie,
int cookielen,
const char *uri,
unsigned long flags,
const char *dname,
unsigned long bandwidth)
{
virConnectPtr conn;
VIR_DEBUG("domain=%p, cookie=%p, cookielen=%d, uri=%s, flags=%lu, "
"dname=%s, bandwidth=%lu", domain, cookie, cookielen, uri, flags,
NULLSTR(dname), bandwidth);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (domain)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
conn = domain->conn;
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainMigratePerform) {
int ret;
ret = conn->driver->domainMigratePerform (domain, cookie, cookielen,
uri,
flags, dname, bandwidth);
if (ret < 0)
goto error;
return ret;
}
virLibDomainError (domain, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/*
* Not for public use. This function is part of the internal
* implementation of migration in the remote case.
*/
virDomainPtr
virDomainMigrateFinish (virConnectPtr dconn,
const char *dname,
const char *cookie,
int cookielen,
const char *uri,
unsigned long flags)
{
VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
"flags=%lu", dconn, NULLSTR(dname), cookie, cookielen,
uri, flags);
virResetLastError();
if (!VIR_IS_CONNECT (dconn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (dconn->flags & VIR_CONNECT_RO) {
virLibConnError(dconn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (dconn->driver->domainMigrateFinish) {
virDomainPtr ret;
ret = dconn->driver->domainMigrateFinish (dconn, dname,
cookie, cookielen,
uri, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (dconn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dconn);
return NULL;
}
/*
* Not for public use. This function is part of the internal
* implementation of migration in the remote case.
*/
int
virDomainMigratePrepare2 (virConnectPtr dconn,
char **cookie,
int *cookielen,
const char *uri_in,
char **uri_out,
unsigned long flags,
const char *dname,
unsigned long bandwidth,
const char *dom_xml)
{
VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p,"
"flags=%lu, dname=%s, bandwidth=%lu, dom_xml=%s", dconn,
cookie, cookielen, uri_in, uri_out, flags, NULLSTR(dname),
bandwidth, dom_xml);
virResetLastError();
if (!VIR_IS_CONNECT (dconn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (dconn->flags & VIR_CONNECT_RO) {
virLibConnError(dconn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (dconn->driver->domainMigratePrepare2) {
int ret;
ret = dconn->driver->domainMigratePrepare2 (dconn, cookie, cookielen,
uri_in, uri_out,
flags, dname, bandwidth,
dom_xml);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (dconn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dconn);
return -1;
}
/*
* Not for public use. This function is part of the internal
* implementation of migration in the remote case.
*/
virDomainPtr
virDomainMigrateFinish2 (virConnectPtr dconn,
const char *dname,
const char *cookie,
int cookielen,
const char *uri,
unsigned long flags,
int retcode)
{
VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
"flags=%lu, retcode=%d", dconn, NULLSTR(dname), cookie,
cookielen, uri, flags, retcode);
virResetLastError();
if (!VIR_IS_CONNECT (dconn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (dconn->flags & VIR_CONNECT_RO) {
virLibConnError(dconn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (dconn->driver->domainMigrateFinish2) {
virDomainPtr ret;
ret = dconn->driver->domainMigrateFinish2 (dconn, dname,
cookie, cookielen,
uri, flags,
retcode);
if (!ret)
goto error;
return ret;
}
virLibConnError (dconn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dconn);
return NULL;
}
/**
* virNodeGetInfo:
* @conn: pointer to the hypervisor connection
* @info: pointer to a virNodeInfo structure allocated by the user
*
* Extract hardware information about the node.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
{
DEBUG("conn=%p, info=%p", conn, info);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (info == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->nodeGetInfo) {
int ret;
ret = conn->driver->nodeGetInfo (conn, info);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectGetCapabilities:
* @conn: pointer to the hypervisor connection
*
* Provides capabilities of the hypervisor / driver.
*
* Returns NULL in case of error, or an XML string
* defining the capabilities.
* The client must free the returned string after use.
*/
char *
virConnectGetCapabilities (virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT (conn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (conn->driver->getCapabilities) {
char *ret;
ret = conn->driver->getCapabilities (conn);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNodeGetFreeMemory:
* @conn: pointer to the hypervisor connection
*
* provides the free memory available on the Node
* Note: most libvirt APIs provide memory sizes in kilobytes, but in this
* function the returned value is in bytes. Divide by 1024 as necessary.
*
* Returns the available free memory in bytes or 0 in case of error
*/
unsigned long long
virNodeGetFreeMemory(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT (conn)) {
virLibConnError (NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return 0;
}
if (conn->driver->getFreeMemory) {
unsigned long long ret;
ret = conn->driver->getFreeMemory (conn);
if (ret == 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return 0;
}
/**
* virDomainGetSchedulerType:
* @domain: pointer to domain object
* @nparams: number of scheduler parameters(return value)
*
* Get the scheduler type.
*
* Returns NULL in case of error. The caller must free the returned string.
*/
char *
virDomainGetSchedulerType(virDomainPtr domain, int *nparams)
{
virConnectPtr conn;
char *schedtype;
DEBUG("domain=%p, nparams=%p", domain, nparams);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return NULL;
}
conn = domain->conn;
if (conn->driver->domainGetSchedulerType){
schedtype = conn->driver->domainGetSchedulerType (domain, nparams);
if (!schedtype)
goto error;
return schedtype;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return NULL;
}
/**
* virDomainGetSchedulerParameters:
* @domain: pointer to domain object
* @params: pointer to scheduler parameter object
* (return value)
* @nparams: pointer to number of scheduler parameter
* (this value should be same than the returned value
* nparams of virDomainGetSchedulerType)
*
* Get the scheduler parameters, the @params array will be filled with the
* values.
*
* Returns -1 in case of error, 0 in case of success.
*/
int
virDomainGetSchedulerParameters(virDomainPtr domain,
virSchedParameterPtr params, int *nparams)
{
virConnectPtr conn;
DEBUG("domain=%p, params=%p, nparams=%p", domain, params, nparams);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
conn = domain->conn;
if (conn->driver->domainGetSchedulerParameters) {
int ret;
ret = conn->driver->domainGetSchedulerParameters (domain, params, nparams);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainSetSchedulerParameters:
* @domain: pointer to domain object
* @params: pointer to scheduler parameter objects
* @nparams: number of scheduler parameter
* (this value should be same or less than the returned value
* nparams of virDomainGetSchedulerType)
*
* Change the scheduler parameters
*
* Returns -1 in case of error, 0 in case of success.
*/
int
virDomainSetSchedulerParameters(virDomainPtr domain,
virSchedParameterPtr params, int nparams)
{
virConnectPtr conn;
DEBUG("domain=%p, params=%p, nparams=%d", domain, params, nparams);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainSetSchedulerParameters) {
int ret;
ret = conn->driver->domainSetSchedulerParameters (domain, params, nparams);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainBlockStats:
* @dom: pointer to the domain object
* @path: path to the block device
* @stats: block device stats (returned)
* @size: size of stats structure
*
* This function returns block device (disk) stats for block
* devices attached to the domain.
*
* The path parameter is the name of the block device. Get this
* by calling virDomainGetXMLDesc and finding the <target dev='...'>
* attribute within //domain/devices/disk. (For example, "xvda").
*
* Domains may have more than one block device. To get stats for
* each you should make multiple calls to this function.
*
* Individual fields within the stats structure may be returned
* as -1, which indicates that the hypervisor does not support
* that particular statistic.
*
* Returns: 0 in case of success or -1 in case of failure.
*/
int
virDomainBlockStats (virDomainPtr dom, const char *path,
virDomainBlockStatsPtr stats, size_t size)
{
virConnectPtr conn;
struct _virDomainBlockStats stats2 = { -1, -1, -1, -1, -1 };
DEBUG("domain=%p, path=%s, stats=%p, size=%zi", dom, path, stats, size);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
if (!path || !stats || size > sizeof stats2) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = dom->conn;
if (conn->driver->domainBlockStats) {
if (conn->driver->domainBlockStats (dom, path, &stats2) == -1)
goto error;
memcpy (stats, &stats2, size);
return 0;
}
virLibDomainError (dom, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dom->conn);
return -1;
}
/**
* virDomainInterfaceStats:
* @dom: pointer to the domain object
* @path: path to the interface
* @stats: network interface stats (returned)
* @size: size of stats structure
*
* This function returns network interface stats for interfaces
* attached to the domain.
*
* The path parameter is the name of the network interface.
*
* Domains may have more than network interface. To get stats for
* each you should make multiple calls to this function.
*
* Individual fields within the stats structure may be returned
* as -1, which indicates that the hypervisor does not support
* that particular statistic.
*
* Returns: 0 in case of success or -1 in case of failure.
*/
int
virDomainInterfaceStats (virDomainPtr dom, const char *path,
virDomainInterfaceStatsPtr stats, size_t size)
{
virConnectPtr conn;
struct _virDomainInterfaceStats stats2 = { -1, -1, -1, -1,
-1, -1, -1, -1 };
DEBUG("domain=%p, path=%s, stats=%p, size=%zi", dom, path, stats, size);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
if (!path || !stats || size > sizeof stats2) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = dom->conn;
if (conn->driver->domainInterfaceStats) {
if (conn->driver->domainInterfaceStats (dom, path, &stats2) == -1)
goto error;
memcpy (stats, &stats2, size);
return 0;
}
virLibDomainError (dom, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dom->conn);
return -1;
}
/**
* virDomainBlockPeek:
* @dom: pointer to the domain object
* @path: path to the block device
* @offset: offset within block device
* @size: size to read
* @buffer: return buffer (must be at least size bytes)
* @flags: unused, always pass 0
*
* This function allows you to read the contents of a domain's
* disk device.
*
* Typical uses for this are to determine if the domain has
* written a Master Boot Record (indicating that the domain
* has completed installation), or to try to work out the state
* of the domain's filesystems.
*
* (Note that in the local case you might try to open the
* block device or file directly, but that won't work in the
* remote case, nor if you don't have sufficient permission.
* Hence the need for this call).
*
* 'path' must be a device or file corresponding to the domain.
* In other words it must be the precise string returned in
* a <disk><source dev='...'/></disk> from
* virDomainGetXMLDesc.
*
* 'offset' and 'size' represent an area which must lie entirely
* within the device or file. 'size' may be 0 to test if the
* call would succeed.
*
* 'buffer' is the return buffer and must be at least 'size' bytes.
*
* NB. The remote driver imposes a 64K byte limit on 'size'.
* For your program to be able to work reliably over a remote
* connection you should split large requests to <= 65536 bytes.
*
* Returns: 0 in case of success or -1 in case of failure.
*/
int
virDomainBlockPeek (virDomainPtr dom,
const char *path,
unsigned long long offset /* really 64 bits */,
size_t size,
void *buffer,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("domain=%p, path=%s, offset=%lld, size=%zi, buffer=%p",
dom, path, offset, size, buffer);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
conn = dom->conn;
if (dom->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(dom, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (!path) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG,
_("path is NULL"));
goto error;
}
if (flags != 0) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG,
_("flags must be zero"));
goto error;
}
/* Allow size == 0 as an access test. */
if (size > 0 && !buffer) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG,
_("buffer is NULL"));
goto error;
}
if (conn->driver->domainBlockPeek) {
int ret;
ret =conn->driver->domainBlockPeek (dom, path, offset, size,
buffer, flags);
if (ret < 0)
goto error;
return ret;
}
virLibDomainError (dom, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dom->conn);
return -1;
}
/**
* virDomainMemoryPeek:
* @dom: pointer to the domain object
* @start: start of memory to peek
* @size: size of memory to peek
* @buffer: return buffer (must be at least size bytes)
* @flags: flags, see below
*
* This function allows you to read the contents of a domain's
* memory.
*
* The memory which is read is controlled by the 'start', 'size'
* and 'flags' parameters.
*
* If 'flags' is VIR_MEMORY_VIRTUAL then the 'start' and 'size'
* parameters are interpreted as virtual memory addresses for
* whichever task happens to be running on the domain at the
* moment. Although this sounds haphazard it is in fact what
* you want in order to read Linux kernel state, because it
* ensures that pointers in the kernel image can be interpreted
* coherently.
*
* 'buffer' is the return buffer and must be at least 'size' bytes.
* 'size' may be 0 to test if the call would succeed.
*
* NB. The remote driver imposes a 64K byte limit on 'size'.
* For your program to be able to work reliably over a remote
* connection you should split large requests to <= 65536 bytes.
*
* Returns: 0 in case of success or -1 in case of failure.
*/
int
virDomainMemoryPeek (virDomainPtr dom,
unsigned long long start /* really 64 bits */,
size_t size,
void *buffer,
unsigned int flags)
{
virConnectPtr conn;
DEBUG ("domain=%p, start=%lld, size=%zi, buffer=%p, flags=%d",
dom, start, size, buffer, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
virLibDomainError (NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
conn = dom->conn;
if (dom->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(dom, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
/* Note on access to physical memory: A VIR_MEMORY_PHYSICAL flag is
* a possibility. However it isn't really useful unless the caller
* can also access registers, particularly CR3 on x86 in order to
* get the Page Table Directory. Since registers are different on
* every architecture, that would imply another call to get the
* machine registers.
*
* The QEMU driver handles VIR_MEMORY_VIRTUAL, mapping it
* to the qemu 'memsave' command which does the virtual to physical
* mapping inside qemu.
*
* The QEMU driver also handles VIR_MEMORY_PHYSICAL, mapping it
* to the qemu 'pmemsave' command.
*
* At time of writing there is no Xen driver. However the Xen
* hypervisor only lets you map physical pages from other domains,
* and so the Xen driver would have to do the virtual to physical
* mapping by chasing 2, 3 or 4-level page tables from the PTD.
* There is example code in libxc (xc_translate_foreign_address)
* which does this, although we cannot copy this code directly
* because of incompatible licensing.
*/
if (flags != VIR_MEMORY_VIRTUAL && flags != VIR_MEMORY_PHYSICAL) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG,
_("flags parameter must be VIR_MEMORY_VIRTUAL or VIR_MEMORY_PHYSICAL"));
goto error;
}
/* Allow size == 0 as an access test. */
if (size > 0 && !buffer) {
virLibDomainError (dom, VIR_ERR_INVALID_ARG,
_("buffer is NULL but size is non-zero"));
goto error;
}
if (conn->driver->domainMemoryPeek) {
int ret;
ret = conn->driver->domainMemoryPeek (dom, start, size,
buffer, flags);
if (ret < 0)
goto error;
return ret;
}
virLibDomainError (dom, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dom->conn);
return -1;
}
/************************************************************************
* *
* Handling of defined but not running domains *
* *
************************************************************************/
/**
* virDomainDefineXML:
* @conn: pointer to the hypervisor connection
* @xml: the XML description for the domain, preferably in UTF-8
*
* Define a domain, but does not start it.
* This definition is persistent, until explicitly undefined with
* virDomainUndefine(). A previous definition for this domain would be
* overriden if it already exists.
*
* Returns NULL in case of error, a pointer to the domain otherwise
*/
virDomainPtr
virDomainDefineXML(virConnectPtr conn, const char *xml) {
DEBUG("conn=%p, xml=%s", conn, xml);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->domainDefineXML) {
virDomainPtr ret;
ret = conn->driver->domainDefineXML (conn, xml);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virDomainUndefine:
* @domain: pointer to a defined domain
*
* Undefine a domain but does not stop it if it is running
*
* Returns 0 in case of success, -1 in case of error
*/
int
virDomainUndefine(virDomainPtr domain) {
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
conn = domain->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainUndefine) {
int ret;
ret = conn->driver->domainUndefine (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virConnectNumOfDefinedDomains:
* @conn: pointer to the hypervisor connection
*
* Provides the number of defined but inactive domains.
*
* Returns the number of domain found or -1 in case of error
*/
int
virConnectNumOfDefinedDomains(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->driver->numOfDefinedDomains) {
int ret;
ret = conn->driver->numOfDefinedDomains (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListDefinedDomains:
* @conn: pointer to the hypervisor connection
* @names: pointer to an array to store the names
* @maxnames: size of the array
*
* list the defined but inactive domains, stores the pointers to the names
* in @names
*
* Returns the number of names provided in the array or -1 in case of error
*/
int
virConnectListDefinedDomains(virConnectPtr conn, char **const names,
int maxnames) {
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->listDefinedDomains) {
int ret;
ret = conn->driver->listDefinedDomains (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virDomainCreate:
* @domain: pointer to a defined domain
*
* launch a defined domain. If the call succeed the domain moves from the
* defined to the running domains pools.
*
* Returns 0 in case of success, -1 in case of error
*/
int
virDomainCreate(virDomainPtr domain) {
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
conn = domain->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainCreate) {
int ret;
ret = conn->driver->domainCreate (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetAutostart:
* @domain: a domain object
* @autostart: the value returned
*
* Provides a boolean value indicating whether the domain
* configured to be automatically started when the host
* machine boots.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virDomainGetAutostart(virDomainPtr domain,
int *autostart)
{
virConnectPtr conn;
DEBUG("domain=%p, autostart=%p", domain, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (!autostart) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainGetAutostart) {
int ret;
ret = conn->driver->domainGetAutostart (domain, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainSetAutostart:
* @domain: a domain object
* @autostart: whether the domain should be automatically started 0 or 1
*
* Configure the domain to be automatically started
* when the host machine boots.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virDomainSetAutostart(virDomainPtr domain,
int autostart)
{
virConnectPtr conn;
DEBUG("domain=%p, autostart=%d", domain, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
conn = domain->conn;
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->driver->domainSetAutostart) {
int ret;
ret = conn->driver->domainSetAutostart (domain, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainSetVcpus:
* @domain: pointer to domain object, or NULL for Domain0
* @nvcpus: the new number of virtual CPUs for this domain
*
* Dynamically change the number of virtual CPUs used by the domain.
* Note that this call may fail if the underlying virtualization hypervisor
* does not support it or if growing the number is arbitrary limited.
* This function requires privileged access to the hypervisor.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus)
{
virConnectPtr conn;
DEBUG("domain=%p, nvcpus=%u", domain, nvcpus);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (nvcpus < 1) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainSetVcpus) {
int ret;
ret = conn->driver->domainSetVcpus (domain, nvcpus);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainPinVcpu:
* @domain: pointer to domain object, or NULL for Domain0
* @vcpu: virtual CPU number
* @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
* Each bit set to 1 means that corresponding CPU is usable.
* Bytes are stored in little-endian order: CPU0-7, 8-15...
* In each byte, lowest CPU number is least significant bit.
* @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
* underlying virtualization system (Xen...).
* If maplen < size, missing bytes are set to zero.
* If maplen > size, failure code is returned.
*
* Dynamically change the real CPUs which can be allocated to a virtual CPU.
* This function requires privileged access to the hypervisor.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu,
unsigned char *cpumap, int maplen)
{
virConnectPtr conn;
DEBUG("domain=%p, vcpu=%u, cpumap=%p, maplen=%d", domain, vcpu, cpumap, maplen);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if ((vcpu > 32000) || (cpumap == NULL) || (maplen < 1)) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainPinVcpu) {
int ret;
ret = conn->driver->domainPinVcpu (domain, vcpu, cpumap, maplen);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetVcpus:
* @domain: pointer to domain object, or NULL for Domain0
* @info: pointer to an array of virVcpuInfo structures (OUT)
* @maxinfo: number of structures in info array
* @cpumaps: pointer to an bit map of real CPUs for all vcpus of this
* domain (in 8-bit bytes) (OUT)
* If cpumaps is NULL, then no cpumap information is returned by the API.
* It's assumed there is <maxinfo> cpumap in cpumaps array.
* The memory allocated to cpumaps must be (maxinfo * maplen) bytes
* (ie: calloc(maxinfo, maplen)).
* One cpumap inside cpumaps has the format described in
* virDomainPinVcpu() API.
* @maplen: number of bytes in one cpumap, from 1 up to size of CPU map in
* underlying virtualization system (Xen...).
*
* Extract information about virtual CPUs of domain, store it in info array
* and also in cpumaps if this pointer isn't NULL.
*
* Returns the number of info filled in case of success, -1 in case of failure.
*/
int
virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo,
unsigned char *cpumaps, int maplen)
{
virConnectPtr conn;
DEBUG("domain=%p, info=%p, maxinfo=%d, cpumaps=%p, maplen=%d", domain, info, maxinfo, cpumaps, maplen);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if ((info == NULL) || (maxinfo < 1)) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (cpumaps != NULL && maplen < 1) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainGetVcpus) {
int ret;
ret = conn->driver->domainGetVcpus (domain, info, maxinfo,
cpumaps, maplen);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetMaxVcpus:
* @domain: pointer to domain object
*
* Provides the maximum number of virtual CPUs supported for
* the guest VM. If the guest is inactive, this is basically
* the same as virConnectGetMaxVcpus. If the guest is running
* this will reflect the maximum number of virtual CPUs the
* guest was booted with.
*
* Returns the maximum of virtual CPU or -1 in case of error.
*/
int
virDomainGetMaxVcpus(virDomainPtr domain)
{
virConnectPtr conn;
DEBUG("domain=%p", domain);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
conn = domain->conn;
if (conn->driver->domainGetMaxVcpus) {
int ret;
ret = conn->driver->domainGetMaxVcpus (domain);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainGetSecurityLabel:
* @domain: a domain object
* @seclabel: pointer to a virSecurityLabel structure
*
* Extract security label of an active domain. The 'label' field
* in the @seclabel argument will be initialized to the empty
* string if the domain is not running under a security model.
*
* Returns 0 in case of success, -1 in case of failure
*/
int
virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel)
{
virConnectPtr conn;
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return -1;
}
if (seclabel == NULL) {
virLibDomainError(domain, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainGetSecurityLabel) {
int ret;
ret = conn->driver->domainGetSecurityLabel(domain, seclabel);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virNodeGetSecurityModel:
* @conn: a connection object
* @secmodel: pointer to a virSecurityModel structure
*
* Extract the security model of a hypervisor. The 'model' field
* in the @secmodel argument may be initialized to the empty
* string if the driver has not activated a security model.
*
* Returns 0 in case of success, -1 in case of failure
*/
int
virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
{
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(conn, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (secmodel == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->nodeGetSecurityModel) {
int ret;
ret = conn->driver->nodeGetSecurityModel(conn, secmodel);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virDomainAttachDevice:
* @domain: pointer to domain object
* @xml: pointer to XML description of one device
*
* Create a virtual device attachment to backend.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virDomainAttachDevice(virDomainPtr domain, const char *xml)
{
virConnectPtr conn;
DEBUG("domain=%p, xml=%s", domain, xml);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainAttachDevice) {
int ret;
ret = conn->driver->domainAttachDevice (domain, xml);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virDomainDetachDevice:
* @domain: pointer to domain object
* @xml: pointer to XML description of one device
*
* Destroy a virtual device attachment to backend.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virDomainDetachDevice(virDomainPtr domain, const char *xml)
{
virConnectPtr conn;
DEBUG("domain=%p, xml=%s", domain, xml);
virResetLastError();
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
virLibDomainError(NULL, VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
return (-1);
}
if (domain->conn->flags & VIR_CONNECT_RO) {
virLibDomainError(domain, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = domain->conn;
if (conn->driver->domainDetachDevice) {
int ret;
ret = conn->driver->domainDetachDevice (domain, xml);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(domain->conn);
return -1;
}
/**
* virNodeGetCellsFreeMemory:
* @conn: pointer to the hypervisor connection
* @freeMems: pointer to the array of unsigned long long
* @startCell: index of first cell to return freeMems info on.
* @maxCells: Maximum number of cells for which freeMems information can
* be returned.
*
* This call returns the amount of free memory in one or more NUMA cells.
* The @freeMems array must be allocated by the caller and will be filled
* with the amount of free memory in bytes for each cell requested,
* starting with startCell (in freeMems[0]), up to either
* (startCell + maxCells), or the number of additional cells in the node,
* whichever is smaller.
*
* Returns the number of entries filled in freeMems, or -1 in case of error.
*/
int
virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
int startCell, int maxCells)
{
DEBUG("conn=%p, freeMems=%p, startCell=%d, maxCells=%d",
conn, freeMems, startCell, maxCells);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(conn, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((freeMems == NULL) || (maxCells <= 0) || (startCell < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->driver->nodeGetCellsFreeMemory) {
int ret;
ret = conn->driver->nodeGetCellsFreeMemory (conn, freeMems, startCell, maxCells);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virNetworkGetConnect:
* @net: pointer to a network
*
* Provides the connection pointer associated with a network. The
* reference counter on the connection is not increased by this
* call.
*
* WARNING: When writing libvirt bindings in other languages, do
* not use this function. Instead, store the connection and
* the network object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virNetworkGetConnect (virNetworkPtr net)
{
DEBUG("net=%p", net);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK (net)) {
virLibNetworkError (NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return NULL;
}
return net->conn;
}
/**
* virConnectNumOfNetworks:
* @conn: pointer to the hypervisor connection
*
* Provides the number of active networks.
*
* Returns the number of network found or -1 in case of error
*/
int
virConnectNumOfNetworks(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->networkDriver && conn->networkDriver->numOfNetworks) {
int ret;
ret = conn->networkDriver->numOfNetworks (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListNetworks:
* @conn: pointer to the hypervisor connection
* @names: array to collect the list of names of active networks
* @maxnames: size of @names
*
* Collect the list of active networks, and store their names in @names
*
* Returns the number of networks found or -1 in case of error
*/
int
virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->listNetworks) {
int ret;
ret = conn->networkDriver->listNetworks (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectNumOfDefinedNetworks:
* @conn: pointer to the hypervisor connection
*
* Provides the number of inactive networks.
*
* Returns the number of networks found or -1 in case of error
*/
int
virConnectNumOfDefinedNetworks(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->networkDriver && conn->networkDriver->numOfDefinedNetworks) {
int ret;
ret = conn->networkDriver->numOfDefinedNetworks (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(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
*
* Returns the number of names provided in the array or -1 in case of error
*/
int
virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->listDefinedNetworks) {
int ret;
ret = conn->networkDriver->listDefinedNetworks (conn,
names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virNetworkLookupByName:
* @conn: pointer to the hypervisor connection
* @name: name for the network
*
* Try to lookup a network on the given hypervisor based on its name.
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*/
virNetworkPtr
virNetworkLookupByName(virConnectPtr conn, const char *name)
{
DEBUG("conn=%p, name=%s", conn, name);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (name == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkLookupByName) {
virNetworkPtr ret;
ret = conn->networkDriver->networkLookupByName (conn, name);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNetworkLookupByUUID:
* @conn: pointer to the hypervisor connection
* @uuid: the raw UUID for the network
*
* Try to lookup a network on the given hypervisor based on its UUID.
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*/
virNetworkPtr
virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
{
DEBUG("conn=%p, uuid=%s", conn, uuid);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuid == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkLookupByUUID){
virNetworkPtr ret;
ret = conn->networkDriver->networkLookupByUUID (conn, uuid);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNetworkLookupByUUIDString:
* @conn: pointer to the hypervisor connection
* @uuidstr: the string UUID for the network
*
* Try to lookup a network on the given hypervisor based on its UUID.
*
* Returns a new network object or NULL in case of failure. If the
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
*/
virNetworkPtr
virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
{
int raw[VIR_UUID_BUFLEN], i;
unsigned char uuid[VIR_UUID_BUFLEN];
int ret;
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuidstr == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/* XXX: sexpr_uuid() also supports 'xxxx-xxxx-xxxx-xxxx' format.
* We needn't it here. Right?
*/
ret = sscanf(uuidstr,
"%02x%02x%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x%02x%02x%02x%02x",
raw + 0, raw + 1, raw + 2, raw + 3,
raw + 4, raw + 5, raw + 6, raw + 7,
raw + 8, raw + 9, raw + 10, raw + 11,
raw + 12, raw + 13, raw + 14, raw + 15);
if (ret!=VIR_UUID_BUFLEN) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
for (i = 0; i < VIR_UUID_BUFLEN; i++)
uuid[i] = raw[i] & 0xFF;
return virNetworkLookupByUUID(conn, &uuid[0]);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNetworkCreateXML:
* @conn: pointer to the hypervisor connection
* @xmlDesc: an XML description of the network
*
* Create and start a new virtual network, based on an XML description
* similar to the one returned by virNetworkGetXMLDesc()
*
* Returns a new network object or NULL in case of failure
*/
virNetworkPtr
virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
{
DEBUG("conn=%p, xmlDesc=%s", conn, xmlDesc);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (xmlDesc == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkCreateXML) {
virNetworkPtr ret;
ret = conn->networkDriver->networkCreateXML (conn, xmlDesc);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNetworkDefineXML:
* @conn: pointer to the hypervisor connection
* @xml: the XML description for the network, preferably in UTF-8
*
* Define a network, but does not create it
*
* Returns NULL in case of error, a pointer to the network otherwise
*/
virNetworkPtr
virNetworkDefineXML(virConnectPtr conn, const char *xml)
{
DEBUG("conn=%p, xml=%s", conn, xml);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkDefineXML) {
virNetworkPtr ret;
ret = conn->networkDriver->networkDefineXML (conn, xml);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNetworkUndefine:
* @network: pointer to a defined network
*
* Undefine a network but does not stop it if it is running
*
* Returns 0 in case of success, -1 in case of error
*/
int
virNetworkUndefine(virNetworkPtr network) {
virConnectPtr conn;
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
conn = network->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibNetworkError(network, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkUndefine) {
int ret;
ret = conn->networkDriver->networkUndefine (network);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virNetworkCreate:
* @network: pointer to a defined network
*
* Create and start a defined network. If the call succeed the network
* moves from the defined to the running networks pools.
*
* Returns 0 in case of success, -1 in case of error
*/
int
virNetworkCreate(virNetworkPtr network)
{
virConnectPtr conn;
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
conn = network->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibNetworkError(network, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkCreate) {
int ret;
ret = conn->networkDriver->networkCreate (network);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virNetworkDestroy:
* @network: a network object
*
* Destroy the network object. The running instance is shutdown if not down
* already and all resources used by it are given back to the hypervisor. This
* does not free the associated virNetworkPtr object.
* This function may require privileged access
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virNetworkDestroy(virNetworkPtr network)
{
virConnectPtr conn;
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
conn = network->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibNetworkError(network, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->networkDriver && conn->networkDriver->networkDestroy) {
int ret;
ret = conn->networkDriver->networkDestroy (network);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virNetworkFree:
* @network: a network object
*
* Free the network object. The running instance is kept alive.
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virNetworkFree(virNetworkPtr network)
{
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
if (virUnrefNetwork(network) < 0)
return (-1);
return(0);
}
/**
* virNetworkRef:
* @network: the network to hold a reference on
*
* Increment the reference count on the network. For each
* additional call to this method, there shall be a corresponding
* call to virNetworkFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a network would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virNetworkRef(virNetworkPtr network)
{
if ((!VIR_IS_CONNECTED_NETWORK(network))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&network->conn->lock);
DEBUG("network=%p refs=%d", network, network->refs);
network->refs++;
virMutexUnlock(&network->conn->lock);
return 0;
}
/**
* virNetworkGetName:
* @network: a network object
*
* Get the public name for that network
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the network object.
*/
const char *
virNetworkGetName(virNetworkPtr network)
{
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (NULL);
}
return (network->name);
}
/**
* virNetworkGetUUID:
* @network: a network object
* @uuid: pointer to a VIR_UUID_BUFLEN bytes array
*
* Get the UUID for a network
*
* Returns -1 in case of error, 0 in case of success
*/
int
virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
{
DEBUG("network=%p, uuid=%p", network, uuid);
virResetLastError();
if (!VIR_IS_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
if (uuid == NULL) {
virLibNetworkError(network, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
memcpy(uuid, &network->uuid[0], VIR_UUID_BUFLEN);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virNetworkGetUUIDString:
* @network: a network object
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
*
* Get the UUID for a network as string. For more information about
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virNetworkGetUUIDString(virNetworkPtr network, char *buf)
{
unsigned char uuid[VIR_UUID_BUFLEN];
DEBUG("network=%p, buf=%p", network, buf);
virResetLastError();
if (!VIR_IS_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
if (buf == NULL) {
virLibNetworkError(network, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (virNetworkGetUUID(network, &uuid[0]))
return (-1);
virUUIDFormat(uuid, buf);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virNetworkGetXMLDesc:
* @network: a network object
* @flags: an OR'ed set of extraction flags, not used yet
*
* Provide an XML description of the network. The description may be reused
* later to relaunch the network with virNetworkCreateXML().
*
* 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, int flags)
{
virConnectPtr conn;
DEBUG("network=%p, flags=%d", network, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (NULL);
}
if (flags != 0) {
virLibNetworkError(network, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkDumpXML) {
char *ret;
ret = conn->networkDriver->networkDumpXML (network, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return NULL;
}
/**
* 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;
DEBUG("network=%p", network);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (NULL);
}
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkGetBridgeName) {
char *ret;
ret = conn->networkDriver->networkGetBridgeName (network);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return NULL;
}
/**
* virNetworkGetAutostart:
* @network: a network object
* @autostart: the value returned
*
* Provides a boolean value indicating whether the network
* configured to be automatically started when the host
* machine boots.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virNetworkGetAutostart(virNetworkPtr network,
int *autostart)
{
virConnectPtr conn;
DEBUG("network=%p, autostart=%p", network, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
if (!autostart) {
virLibNetworkError(network, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkGetAutostart) {
int ret;
ret = conn->networkDriver->networkGetAutostart (network, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
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;
DEBUG("network=%p, autostart=%d", network, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_NETWORK(network)) {
virLibNetworkError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
if (network->conn->flags & VIR_CONNECT_RO) {
virLibNetworkError(network, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = network->conn;
if (conn->networkDriver && conn->networkDriver->networkSetAutostart) {
int ret;
ret = conn->networkDriver->networkSetAutostart (network, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(network->conn);
return -1;
}
/**
* virInterfaceGetConnect:
* @iface: pointer to an interface
*
* Provides the connection pointer associated with an interface. The
* reference counter on the connection is not increased by this
* call.
*
* WARNING: When writing libvirt bindings in other languages, do
* not use this function. Instead, store the connection and
* the interface object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virInterfaceGetConnect (virInterfacePtr iface)
{
DEBUG("iface=%p", iface);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE (iface)) {
virLibInterfaceError (NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return NULL;
}
return iface->conn;
}
/**
* virConnectNumOfInterfaces:
* @conn: pointer to the hypervisor connection
*
* Provides the number of active interfaces on the physical host.
*
* Returns the number of active interfaces found or -1 in case of error
*/
int
virConnectNumOfInterfaces(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->interfaceDriver && conn->interfaceDriver->numOfInterfaces) {
int ret;
ret = conn->interfaceDriver->numOfInterfaces (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListInterfaces:
* @conn: pointer to the hypervisor connection
* @names: array to collect the list of names of interfaces
* @maxnames: size of @names
*
* Collect the list of active physical host interfaces,
* and store their names in @names
*
* Returns the number of interfaces found or -1 in case of error
*/
int
virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->listInterfaces) {
int ret;
ret = conn->interfaceDriver->listInterfaces (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectNumOfDefinedInterfaces:
* @conn: pointer to the hypervisor connection
*
* Provides the number of defined (inactive) interfaces on the physical host.
*
* Returns the number of defined interface found or -1 in case of error
*/
int
virConnectNumOfDefinedInterfaces(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->interfaceDriver && conn->interfaceDriver->numOfDefinedInterfaces) {
int ret;
ret = conn->interfaceDriver->numOfDefinedInterfaces (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListDefinedInterfaces:
* @conn: pointer to the hypervisor connection
* @names: array to collect the list of names of interfaces
* @maxnames: size of @names
*
* Collect the list of defined (inactive) physical host interfaces,
* and store their names in @names.
*
* Returns the number of interfaces found or -1 in case of error
*/
int
virConnectListDefinedInterfaces(virConnectPtr conn,
char **const names,
int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->listDefinedInterfaces) {
int ret;
ret = conn->interfaceDriver->listDefinedInterfaces (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virInterfaceLookupByName:
* @conn: pointer to the hypervisor connection
* @name: name for the interface
*
* Try to lookup an interface on the given hypervisor based on its name.
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
*/
virInterfacePtr
virInterfaceLookupByName(virConnectPtr conn, const char *name)
{
DEBUG("conn=%p, name=%s", conn, name);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (name == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceLookupByName) {
virInterfacePtr ret;
ret = conn->interfaceDriver->interfaceLookupByName (conn, name);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virInterfaceLookupByMACString:
* @conn: pointer to the hypervisor connection
* @macstr: the MAC for the interface (null-terminated ASCII format)
*
* Try to lookup an interface on the given hypervisor based on its MAC.
*
* Returns a new interface object or NULL in case of failure. If the
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
*/
virInterfacePtr
virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
{
DEBUG("conn=%p, macstr=%s", conn, macstr);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (macstr == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceLookupByMACString) {
virInterfacePtr ret;
ret = conn->interfaceDriver->interfaceLookupByMACString (conn, macstr);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virInterfaceGetName:
* @iface: an interface object
*
* Get the public name for that interface
*
* Returns a pointer to the name or NULL, the string need not be deallocated
* its lifetime will be the same as the interface object.
*/
const char *
virInterfaceGetName(virInterfacePtr iface)
{
DEBUG("iface=%p", iface);
virResetLastError();
if (!VIR_IS_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (NULL);
}
return (iface->name);
}
/**
* virInterfaceGetMACString:
* @iface: an interface object
*
* Get the MAC for an interface as string. For more information about
* MAC see RFC4122.
*
* Returns a pointer to the MAC address (in null-terminated ASCII
* format) or NULL, the string need not be deallocated its lifetime
* will be the same as the interface object.
*/
const char *
virInterfaceGetMACString(virInterfacePtr iface)
{
DEBUG("iface=%p", iface);
virResetLastError();
if (!VIR_IS_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (NULL);
}
return (iface->mac);
}
/**
* virInterfaceGetXMLDesc:
* @iface: an interface object
* @flags: an OR'ed set of extraction flags, not used yet
*
* Provide an XML description of the interface. The description may be reused
* later to redefine the interface with virInterfaceDefineXML().
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
char *
virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
{
virConnectPtr conn;
DEBUG("iface=%p, flags=%d", iface, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (NULL);
}
if (flags != 0) {
virLibInterfaceError(iface, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = iface->conn;
if (conn->interfaceDriver && conn->interfaceDriver->interfaceGetXMLDesc) {
char *ret;
ret = conn->interfaceDriver->interfaceGetXMLDesc (iface, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(iface->conn);
return NULL;
}
/**
* virInterfaceDefineXML:
* @conn: pointer to the hypervisor connection
* @xml: the XML description for the interface, preferably in UTF-8
* @flags: and OR'ed set of extraction flags, not used yet
*
* Define an interface (or modify existing interface configuration)
*
* Returns NULL in case of error, a pointer to the interface otherwise
*/
virInterfacePtr
virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
{
DEBUG("conn=%p, xml=%s, flags=%d", conn, xml, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceDefineXML) {
virInterfacePtr ret;
ret = conn->interfaceDriver->interfaceDefineXML (conn, xml, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virInterfaceUndefine:
* @iface: pointer to a defined interface
*
* Undefine an interface, ie remove it from the config.
* This does not free the associated virInterfacePtr object.
*
* Returns 0 in case of success, -1 in case of error
*/
int
virInterfaceUndefine(virInterfacePtr iface) {
virConnectPtr conn;
DEBUG("iface=%p", iface);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (-1);
}
conn = iface->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibInterfaceError(iface, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceUndefine) {
int ret;
ret = conn->interfaceDriver->interfaceUndefine (iface);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(iface->conn);
return -1;
}
/**
* virInterfaceCreate:
* @iface: pointer to a defined interface
* @flags: and OR'ed set of extraction flags, not used yet
*
* Activate an interface (ie call "ifup")
*
* Returns 0 in case of success, -1 in case of error
*/
int
virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
{
virConnectPtr conn;
DEBUG("iface=%p, flags=%d", iface, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (-1);
}
conn = iface->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibInterfaceError(iface, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceCreate) {
int ret;
ret = conn->interfaceDriver->interfaceCreate (iface, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(iface->conn);
return -1;
}
/**
* virInterfaceDestroy:
* @iface: an interface object
* @flags: and OR'ed set of extraction flags, not used yet
*
* deactivate an interface (ie call "ifdown")
* This does not remove the interface from the config, and
* does not free the associated virInterfacePtr object.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
{
virConnectPtr conn;
DEBUG("iface=%p, flags=%d", iface, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (-1);
}
conn = iface->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibInterfaceError(iface, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->interfaceDriver && conn->interfaceDriver->interfaceDestroy) {
int ret;
ret = conn->interfaceDriver->interfaceDestroy (iface, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(iface->conn);
return -1;
}
/**
* virInterfaceRef:
* @iface: the interface to hold a reference on
*
* Increment the reference count on the interface. For each
* additional call to this method, there shall be a corresponding
* call to virInterfaceFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using an interface would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virInterfaceRef(virInterfacePtr iface)
{
if ((!VIR_IS_CONNECTED_INTERFACE(iface))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&iface->conn->lock);
DEBUG("iface=%p refs=%d", iface, iface->refs);
iface->refs++;
virMutexUnlock(&iface->conn->lock);
return 0;
}
/**
* virInterfaceFree:
* @iface: an interface object
*
* Free the interface object. The interface itself is unaltered.
* The data structure is freed and should not be used thereafter.
*
* Returns 0 in case of success and -1 in case of failure.
*/
int
virInterfaceFree(virInterfacePtr iface)
{
DEBUG("iface=%p", iface);
virResetLastError();
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
virLibInterfaceError(NULL, VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
return (-1);
}
if (virUnrefInterface(iface) < 0)
return (-1);
return(0);
}
/**
* virStoragePoolGetConnect:
* @pool: pointer to a pool
*
* Provides the connection pointer associated with a storage pool. The
* reference counter on the connection is not increased by this
* call.
*
* WARNING: When writing libvirt bindings in other languages, do
* not use this function. Instead, store the connection and
* the pool object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virStoragePoolGetConnect (virStoragePoolPtr pool)
{
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL (pool)) {
virLibStoragePoolError (NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return NULL;
}
return pool->conn;
}
/**
* virConnectNumOfStoragePools:
* @conn: pointer to hypervisor connection
*
* Provides the number of active storage pools
*
* Returns the number of pools found, or -1 on error
*/
int
virConnectNumOfStoragePools (virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->storageDriver && conn->storageDriver->numOfPools) {
int ret;
ret = conn->storageDriver->numOfPools (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListStoragePools:
* @conn: pointer to hypervisor connection
* @names: array of char * to fill with pool names (allocated by caller)
* @maxnames: size of the names array
*
* Provides the list of names of active storage pools
* upto maxnames. If there are more than maxnames, the
* remaining names will be silently ignored.
*
* Returns 0 on success, -1 on error
*/
int
virConnectListStoragePools (virConnectPtr conn,
char **const names,
int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->listPools) {
int ret;
ret = conn->storageDriver->listPools (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectNumOfDefinedStoragePools:
* @conn: pointer to hypervisor connection
*
* Provides the number of inactive storage pools
*
* Returns the number of pools found, or -1 on error
*/
int
virConnectNumOfDefinedStoragePools(virConnectPtr conn)
{
DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (conn->storageDriver && conn->storageDriver->numOfDefinedPools) {
int ret;
ret = conn->storageDriver->numOfDefinedPools (conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListDefinedStoragePools:
* @conn: pointer to hypervisor connection
* @names: array of char * to fill with pool names (allocated by caller)
* @maxnames: size of the names array
*
* Provides the list of names of inactive storage pools
* upto maxnames. If there are more than maxnames, the
* remaining names will be silently ignored.
*
* Returns 0 on success, -1 on error
*/
int
virConnectListDefinedStoragePools(virConnectPtr conn,
char **const names,
int maxnames)
{
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->listDefinedPools) {
int ret;
ret = conn->storageDriver->listDefinedPools (conn, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectFindStoragePoolSources:
* @conn: pointer to hypervisor connection
* @type: type of storage pool sources to discover
* @srcSpec: XML document specifying discovery source
* @flags: flags for discovery (unused, pass 0)
*
* Talks to a storage backend and attempts to auto-discover the set of
* available storage pool sources. e.g. For iSCSI this would be a set of
* iSCSI targets. For NFS this would be a list of exported paths. The
* srcSpec (optional for some storage pool types, e.g. local ones) is
* an instance of the storage pool's source element specifying where
* to look for the pools.
*
* srcSpec is not required for some types (e.g., those querying
* local storage resources only)
*
* Returns an xml document consisting of a SourceList element
* containing a source document appropriate to the given pool
* type for each discovered source.
*/
char *
virConnectFindStoragePoolSources(virConnectPtr conn,
const char *type,
const char *srcSpec,
unsigned int flags)
{
DEBUG("conn=%p, type=%s, src=%s, flags=%u", conn, type ? type : "", srcSpec ? srcSpec : "", flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (type == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->findPoolSources) {
char *ret;
ret = conn->storageDriver->findPoolSources(conn, type, srcSpec, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolLookupByName:
* @conn: pointer to hypervisor connection
* @name: name of pool to fetch
*
* Fetch a storage pool based on its unique name
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
virStoragePoolLookupByName(virConnectPtr conn,
const char *name)
{
DEBUG("conn=%p, name=%s", conn, name);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (name == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolLookupByName) {
virStoragePoolPtr ret;
ret = conn->storageDriver->poolLookupByName (conn, name);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolLookupByUUID:
* @conn: pointer to hypervisor connection
* @uuid: globally unique id of pool to fetch
*
* Fetch a storage pool based on its globally unique id
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
virStoragePoolLookupByUUID(virConnectPtr conn,
const unsigned char *uuid)
{
DEBUG("conn=%p, uuid=%s", conn, uuid);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuid == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolLookupByUUID) {
virStoragePoolPtr ret;
ret = conn->storageDriver->poolLookupByUUID (conn, uuid);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolLookupByUUIDString:
* @conn: pointer to hypervisor connection
* @uuidstr: globally unique id of pool to fetch
*
* Fetch a storage pool based on its globally unique id
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
virStoragePoolLookupByUUIDString(virConnectPtr conn,
const char *uuidstr)
{
unsigned char uuid[VIR_UUID_BUFLEN];
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuidstr == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (virUUIDParse(uuidstr, uuid) < 0) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
return virStoragePoolLookupByUUID(conn, uuid);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolLookupByVolume:
* @vol: pointer to storage volume
*
* Fetch a storage pool which contains a particular volume
*
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
*/
virStoragePoolPtr
virStoragePoolLookupByVolume(virStorageVolPtr vol)
{
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (vol->conn->storageDriver && vol->conn->storageDriver->poolLookupByVolume) {
virStoragePoolPtr ret;
ret = vol->conn->storageDriver->poolLookupByVolume (vol);
if (!ret)
goto error;
return ret;
}
virLibConnError (vol->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(vol->conn);
return NULL;
}
/**
* virStoragePoolCreateXML:
* @conn: pointer to hypervisor connection
* @xmlDesc: XML description for new pool
* @flags: future flags, use 0 for now
*
* Create a new storage based on its XML description. The
* pool is not persistent, so its definition will disappear
* when it is destroyed, or if the host is restarted
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
*/
virStoragePoolPtr
virStoragePoolCreateXML(virConnectPtr conn,
const char *xmlDesc,
unsigned int flags)
{
DEBUG("conn=%p, xmlDesc=%s", conn, xmlDesc);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (xmlDesc == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolCreateXML) {
virStoragePoolPtr ret;
ret = conn->storageDriver->poolCreateXML (conn, xmlDesc, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolDefineXML:
* @conn: pointer to hypervisor connection
* @xml: XML description for new pool
* @flags: future flags, use 0 for now
*
* Define a new inactive storage pool based on its XML description. The
* pool is persistent, until explicitly undefined.
*
* Returns a virStoragePoolPtr object, or NULL if creation failed
*/
virStoragePoolPtr
virStoragePoolDefineXML(virConnectPtr conn,
const char *xml,
unsigned int flags)
{
DEBUG("conn=%p, xml=%s", conn, xml);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolDefineXML) {
virStoragePoolPtr ret;
ret = conn->storageDriver->poolDefineXML (conn, xml, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStoragePoolBuild:
* @pool: pointer to storage pool
* @flags: future flags, use 0 for now
*
* Build the underlying storage pool
*
* Returns 0 on success, or -1 upon failure
*/
int
virStoragePoolBuild(virStoragePoolPtr pool,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("pool=%p, flags=%u", pool, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolBuild) {
int ret;
ret = conn->storageDriver->poolBuild (pool, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolUndefine:
* @pool: pointer to storage pool
*
* Undefine an inactive storage pool
*
* Returns 0 on success, -1 on failure
*/
int
virStoragePoolUndefine(virStoragePoolPtr pool)
{
virConnectPtr conn;
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_NETWORK, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolUndefine) {
int ret;
ret = conn->storageDriver->poolUndefine (pool);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolCreate:
* @pool: pointer to storage pool
* @flags: future flags, use 0 for now
*
* Starts an inactive storage pool
*
* Returns 0 on success, or -1 if it could not be started
*/
int
virStoragePoolCreate(virStoragePoolPtr pool,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolCreate) {
int ret;
ret = conn->storageDriver->poolCreate (pool, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolDestroy:
* @pool: pointer to storage pool
*
* Destroy an active storage pool. This will deactivate the
* pool on the host, but keep any persistent config associated
* with it. If it has a persistent config it can later be
* restarted with virStoragePoolCreate(). This does not free
* the associated virStoragePoolPtr object.
*
* Returns 0 on success, or -1 if it could not be destroyed
*/
int
virStoragePoolDestroy(virStoragePoolPtr pool)
{
virConnectPtr conn;
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolDestroy) {
int ret;
ret = conn->storageDriver->poolDestroy (pool);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolDelete:
* @pool: pointer to storage pool
* @flags: flags for obliteration process
*
* Delete the underlying pool resources. This is
* a non-recoverable operation. The virStoragePoolPtr object
* itself is not free'd.
*
* Returns 0 on success, or -1 if it could not be obliterate
*/
int
virStoragePoolDelete(virStoragePoolPtr pool,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("pool=%p, flags=%u", pool, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolDelete) {
int ret;
ret = conn->storageDriver->poolDelete (pool, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolFree:
* @pool: pointer to storage pool
*
* Free a storage pool object, releasing all memory associated with
* it. Does not change the state of the pool on the host.
*
* Returns 0 on success, or -1 if it could not be free'd.
*/
int
virStoragePoolFree(virStoragePoolPtr pool)
{
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (virUnrefStoragePool(pool) < 0)
return (-1);
return(0);
}
/**
* virStoragePoolRef:
* @pool: the pool to hold a reference on
*
* Increment the reference count on the pool. For each
* additional call to this method, there shall be a corresponding
* call to virStoragePoolFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a pool would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virStoragePoolRef(virStoragePoolPtr pool)
{
if ((!VIR_IS_CONNECTED_STORAGE_POOL(pool))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&pool->conn->lock);
DEBUG("pool=%p refs=%d", pool, pool->refs);
pool->refs++;
virMutexUnlock(&pool->conn->lock);
return 0;
}
/**
* virStoragePoolRefresh:
* @pool: pointer to storage pool
* @flags: flags to control refresh behaviour (currently unused, use 0)
*
* Request that the pool refresh its list of volumes. This may
* involve communicating with a remote server, and/or initializing
* new devices at the OS layer
*
* Returns 0 if the volume list was refreshed, -1 on failure
*/
int
virStoragePoolRefresh(virStoragePoolPtr pool,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("pool=%p flags=%u", pool, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
conn = pool->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->poolRefresh) {
int ret;
ret = conn->storageDriver->poolRefresh (pool, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolGetName:
* @pool: pointer to storage pool
*
* Fetch the locally unique name of the storage pool
*
* Returns the name of the pool, or NULL on error
*/
const char*
virStoragePoolGetName(virStoragePoolPtr pool)
{
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (NULL);
}
return (pool->name);
}
/**
* virStoragePoolGetUUID:
* @pool: pointer to storage pool
* @uuid: buffer of VIR_UUID_BUFLEN bytes in size
*
* Fetch the globally unique ID of the storage pool
*
* Returns 0 on success, or -1 on error;
*/
int
virStoragePoolGetUUID(virStoragePoolPtr pool,
unsigned char *uuid)
{
DEBUG("pool=%p, uuid=%p", pool, uuid);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (uuid == NULL) {
virLibStoragePoolError(pool, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
memcpy(uuid, &pool->uuid[0], VIR_UUID_BUFLEN);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolGetUUIDString:
* @pool: pointer to storage pool
* @buf: buffer of VIR_UUID_STRING_BUFLEN bytes in size
*
* Fetch the globally unique ID of the storage pool as a string
*
* Returns 0 on success, or -1 on error;
*/
int
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
char *buf)
{
unsigned char uuid[VIR_UUID_BUFLEN];
DEBUG("pool=%p, buf=%p", pool, buf);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (buf == NULL) {
virLibStoragePoolError(pool, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (virStoragePoolGetUUID(pool, &uuid[0]))
goto error;
virUUIDFormat(uuid, buf);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolGetInfo:
* @pool: pointer to storage pool
* @info: pointer at which to store info
*
* Get volatile information about the storage pool
* such as free space / usage summary
*
* Returns 0 on success, or -1 on failure.
*/
int
virStoragePoolGetInfo(virStoragePoolPtr pool,
virStoragePoolInfoPtr info)
{
virConnectPtr conn;
DEBUG("pool=%p, info=%p", pool, info);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (info == NULL) {
virLibStoragePoolError(pool, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
memset(info, 0, sizeof(virStoragePoolInfo));
conn = pool->conn;
if (conn->storageDriver->poolGetInfo) {
int ret;
ret = conn->storageDriver->poolGetInfo (pool, info);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolGetXMLDesc:
* @pool: pointer to storage pool
* @flags: flags for XML format options (set of virDomainXMLFlags)
*
* Fetch an XML document describing all aspects of the
* storage pool. This is suitable for later feeding back
* into the virStoragePoolCreateXML method.
*
* Returns a XML document, or NULL on error
*/
char *
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("pool=%p, flags=%u", pool, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (NULL);
}
if (flags != 0) {
virLibStoragePoolError(pool, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = pool->conn;
if (conn->storageDriver && conn->storageDriver->poolGetXMLDesc) {
char *ret;
ret = conn->storageDriver->poolGetXMLDesc (pool, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return NULL;
}
/**
* virStoragePoolGetAutostart:
* @pool: pointer to storage pool
* @autostart: location in which to store autostart flag
*
* Fetches the value of the autostart flag, which determines
* whether the pool is automatically started at boot time
*
* Returns 0 on success, -1 on failure
*/
int
virStoragePoolGetAutostart(virStoragePoolPtr pool,
int *autostart)
{
virConnectPtr conn;
DEBUG("pool=%p, autostart=%p", pool, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (!autostart) {
virLibStoragePoolError(pool, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = pool->conn;
if (conn->storageDriver && conn->storageDriver->poolGetAutostart) {
int ret;
ret = conn->storageDriver->poolGetAutostart (pool, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolSetAutostart:
* @pool: pointer to storage pool
* @autostart: new flag setting
*
* Sets the autostart flag
*
* Returns 0 on success, -1 on failure
*/
int
virStoragePoolSetAutostart(virStoragePoolPtr pool,
int autostart)
{
virConnectPtr conn;
DEBUG("pool=%p, autostart=%d", pool, autostart);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
virLibStoragePoolError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return -1;
}
if (pool->conn->flags & VIR_CONNECT_RO) {
virLibStoragePoolError(pool, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
conn = pool->conn;
if (conn->storageDriver && conn->storageDriver->poolSetAutostart) {
int ret;
ret = conn->storageDriver->poolSetAutostart (pool, autostart);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolNumOfVolumes:
* @pool: pointer to storage pool
*
* Fetch the number of storage volumes within a pool
*
* Returns the number of storage pools, or -1 on failure
*/
int
virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
{
DEBUG("pool=%p", pool);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibConnError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if (pool->conn->storageDriver && pool->conn->storageDriver->poolNumOfVolumes) {
int ret;
ret = pool->conn->storageDriver->poolNumOfVolumes (pool);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (pool->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStoragePoolListVolumes:
* @pool: pointer to storage pool
* @names: array in which to storage volume names
* @maxnames: size of names array
*
* Fetch list of storage volume names, limiting to
* at most maxnames.
*
* Returns the number of names fetched, or -1 on error
*/
int
virStoragePoolListVolumes(virStoragePoolPtr pool,
char **const names,
int maxnames)
{
DEBUG("pool=%p, names=%p, maxnames=%d", pool, names, maxnames);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibConnError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (-1);
}
if ((names == NULL) || (maxnames < 0)) {
virLibConnError(pool->conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (pool->conn->storageDriver && pool->conn->storageDriver->poolListVolumes) {
int ret;
ret = pool->conn->storageDriver->poolListVolumes (pool, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (pool->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return -1;
}
/**
* virStorageVolGetConnect:
* @vol: pointer to a pool
*
* Provides the connection pointer associated with a storage volume. The
* reference counter on the connection is not increased by this
* call.
*
* WARNING: When writing libvirt bindings in other languages, do
* not use this function. Instead, store the connection and
* the volume object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virStorageVolGetConnect (virStorageVolPtr vol)
{
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_STORAGE_VOL (vol)) {
virLibStoragePoolError (NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return NULL;
}
return vol->conn;
}
/**
* virStorageVolLookupByName:
* @pool: pointer to storage pool
* @name: name of storage volume
*
* Fetch a pointer to a storage volume based on its name
* within a pool
*
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
virStorageVolLookupByName(virStoragePoolPtr pool,
const char *name)
{
DEBUG("pool=%p, name=%s", pool, name);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (name == NULL) {
virLibConnError(pool->conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (pool->conn->storageDriver && pool->conn->storageDriver->volLookupByName) {
virStorageVolPtr ret;
ret = pool->conn->storageDriver->volLookupByName (pool, name);
if (!ret)
goto error;
return ret;
}
virLibConnError (pool->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return NULL;
}
/**
* virStorageVolLookupByKey:
* @conn: pointer to hypervisor connection
* @key: globally unique key
*
* Fetch a pointer to a storage volume based on its
* globally unique key
*
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
virStorageVolLookupByKey(virConnectPtr conn,
const char *key)
{
DEBUG("conn=%p, key=%s", conn, key);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (key == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->volLookupByKey) {
virStorageVolPtr ret;
ret = conn->storageDriver->volLookupByKey (conn, key);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStorageVolLookupByPath:
* @conn: pointer to hypervisor connection
* @path: locally unique path
*
* Fetch a pointer to a storage volume based on its
* locally (host) unique path
*
* Returns a storage volume, or NULL if not found / error
*/
virStorageVolPtr
virStorageVolLookupByPath(virConnectPtr conn,
const char *path)
{
DEBUG("conn=%p, path=%s", conn, path);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (path == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->volLookupByPath) {
virStorageVolPtr ret;
ret = conn->storageDriver->volLookupByPath (conn, path);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virStorageVolGetName:
* @vol: pointer to storage volume
*
* Fetch the storage volume name. This is unique
* within the scope of a pool
*
* Returns the volume name, or NULL on error
*/
const char*
virStorageVolGetName(virStorageVolPtr vol)
{
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (NULL);
}
return (vol->name);
}
/**
* virStorageVolGetKey:
* @vol: pointer to storage volume
*
* Fetch the storage volume key. This is globally
* unique, so the same volume will have the same
* key no matter what host it is accessed from
*
* Returns the volume key, or NULL on error
*/
const char*
virStorageVolGetKey(virStorageVolPtr vol)
{
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (NULL);
}
return (vol->key);
}
/**
* virStorageVolCreateXML:
* @pool: pointer to storage pool
* @xmldesc: description of volume to create
* @flags: flags for creation (unused, pass 0)
*
* Create a storage volume within a pool based
* on an XML description. Not all pools support
* creation of volumes
*
* Returns the storage volume, or NULL on error
*/
virStorageVolPtr
virStorageVolCreateXML(virStoragePoolPtr pool,
const char *xmldesc,
unsigned int flags)
{
DEBUG("pool=%p, flags=%u", pool, flags);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibConnError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (NULL);
}
if (pool->conn->flags & VIR_CONNECT_RO) {
virLibConnError(pool->conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (pool->conn->storageDriver && pool->conn->storageDriver->volCreateXML) {
virStorageVolPtr ret;
ret = pool->conn->storageDriver->volCreateXML (pool, xmldesc, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (pool->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return NULL;
}
/**
* virStorageVolCreateXMLFrom:
* @pool: pointer to parent pool for the new volume
* @xmldesc: description of volume to create
* @clonevol: storage volume to use as input
* @flags: flags for creation (unused, pass 0)
*
* Create a storage volume in the parent pool, using the
* 'clonevol' volume as input. Information for the new
* volume (name, perms) are passed via a typical volume
* XML description.
*
* Returns the storage volume, or NULL on error
*/
virStorageVolPtr
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
const char *xmldesc,
virStorageVolPtr clonevol,
unsigned int flags)
{
DEBUG("pool=%p, flags=%u, clonevol=%p", pool, flags, clonevol);
virResetLastError();
if (!VIR_IS_STORAGE_POOL(pool)) {
virLibConnError(NULL, VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
return (NULL);
}
if (!VIR_IS_STORAGE_VOL(clonevol)) {
virLibConnError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (NULL);
}
if (pool->conn->flags & VIR_CONNECT_RO ||
clonevol->conn->flags & VIR_CONNECT_RO) {
virLibConnError(pool->conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (pool->conn->storageDriver &&
pool->conn->storageDriver->volCreateXMLFrom) {
virStorageVolPtr ret;
ret = pool->conn->storageDriver->volCreateXMLFrom (pool, xmldesc,
clonevol, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (pool->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(pool->conn);
return NULL;
}
/**
* virStorageVolDelete:
* @vol: pointer to storage volume
* @flags: future flags, use 0 for now
*
* Delete the storage volume from the pool
*
* Returns 0 on success, or -1 on error
*/
int
virStorageVolDelete(virStorageVolPtr vol,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("vol=%p, flags=%u", vol, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (-1);
}
conn = vol->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibStorageVolError(vol, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->storageDriver && conn->storageDriver->volDelete) {
int ret;
ret = conn->storageDriver->volDelete (vol, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(vol->conn);
return -1;
}
/**
* virStorageVolFree:
* @vol: pointer to storage volume
*
* Release the storage volume handle. The underlying
* storage volume continues to exist.
*
* Returns 0 on success, or -1 on error
*/
int
virStorageVolFree(virStorageVolPtr vol)
{
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (-1);
}
if (virUnrefStorageVol(vol) < 0)
return (-1);
return(0);
}
/**
* virStorageVolRef:
* @vol: the vol to hold a reference on
*
* Increment the reference count on the vol. For each
* additional call to this method, there shall be a corresponding
* call to virStorageVolFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a vol would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virStorageVolRef(virStorageVolPtr vol)
{
if ((!VIR_IS_CONNECTED_STORAGE_VOL(vol))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&vol->conn->lock);
DEBUG("vol=%p refs=%d", vol, vol->refs);
vol->refs++;
virMutexUnlock(&vol->conn->lock);
return 0;
}
/**
* virStorageVolGetInfo:
* @vol: pointer to storage volume
* @info: pointer at which to store info
*
* Fetches volatile information about the storage
* volume such as its current allocation
*
* Returns 0 on success, or -1 on failure
*/
int
virStorageVolGetInfo(virStorageVolPtr vol,
virStorageVolInfoPtr info)
{
virConnectPtr conn;
DEBUG("vol=%p, info=%p", vol, info);
virResetLastError();
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (-1);
}
if (info == NULL) {
virLibStorageVolError(vol, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
memset(info, 0, sizeof(virStorageVolInfo));
conn = vol->conn;
if (conn->storageDriver->volGetInfo){
int ret;
ret = conn->storageDriver->volGetInfo (vol, info);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(vol->conn);
return -1;
}
/**
* virStorageVolGetXMLDesc:
* @vol: pointer to storage volume
* @flags: flags for XML generation (unused, pass 0)
*
* Fetch an XML document describing all aspects of
* the storage volume
*
* Returns the XML document, or NULL on error
*/
char *
virStorageVolGetXMLDesc(virStorageVolPtr vol,
unsigned int flags)
{
virConnectPtr conn;
DEBUG("vol=%p, flags=%u", vol, flags);
virResetLastError();
if (!VIR_IS_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (NULL);
}
if (flags != 0) {
virLibStorageVolError(vol, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
conn = vol->conn;
if (conn->storageDriver && conn->storageDriver->volGetXMLDesc) {
char *ret;
ret = conn->storageDriver->volGetXMLDesc (vol, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(vol->conn);
return NULL;
}
/**
* virStorageVolGetPath:
* @vol: pointer to storage volume
*
* Fetch the storage volume path. Depending on the pool
* configuration this is either persistent across hosts,
* or dynamically assigned at pool startup. Consult
* pool documentation for information on getting the
* persistent naming
*
* Returns the storage volume path, or NULL on error
*/
char *
virStorageVolGetPath(virStorageVolPtr vol)
{
virConnectPtr conn;
DEBUG("vol=%p", vol);
virResetLastError();
if (!VIR_IS_STORAGE_VOL(vol)) {
virLibStorageVolError(NULL, VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
return (NULL);
}
conn = vol->conn;
if (conn->storageDriver && conn->storageDriver->volGetPath) {
char *ret;
ret = conn->storageDriver->volGetPath (vol);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(vol->conn);
return NULL;
}
/**
* virNodeNumOfDevices:
* @conn: pointer to the hypervisor connection
* @cap: capability name
* @flags: flags (unused, pass 0)
*
* Provides the number of node devices.
*
* 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 or -1 in case of error
*/
int
virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
{
DEBUG("conn=%p, cap=%s, flags=%d", conn, NULLSTR(cap), flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (flags != 0) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->deviceMonitor && conn->deviceMonitor->numOfDevices) {
int ret;
ret = conn->deviceMonitor->numOfDevices (conn, cap, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(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: flags (unused, pass 0)
*
* Collect the list of node devices, and store their names in @names
*
* 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)
{
DEBUG("conn=%p, cap=%s, names=%p, maxnames=%d, flags=%d",
conn, cap, names, maxnames, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if ((flags != 0) || (names == NULL) || (maxnames < 0)) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->deviceMonitor && conn->deviceMonitor->listDevices) {
int ret;
ret = conn->deviceMonitor->listDevices (conn, cap, names, maxnames, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virNodeDeviceLookupByName:
* @conn: pointer to the hypervisor connection
* @name: unique device name
*
* Lookup a node device by its name.
*
* Returns a virNodeDevicePtr if found, NULL otherwise.
*/
virNodeDevicePtr virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
{
DEBUG("conn=%p, name=%p", conn, name);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (name == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->deviceMonitor && conn->deviceMonitor->deviceLookupByName) {
virNodeDevicePtr ret;
ret = conn->deviceMonitor->deviceLookupByName (conn, name);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNodeDeviceGetXMLDesc:
* @dev: pointer to the node device
* @flags: flags for XML generation (unused, pass 0)
*
* Fetch an XML document describing all aspects of
* the device.
*
* Returns the XML document, or NULL on error
*/
char *virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return NULL;
}
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceDumpXML) {
char *ret;
ret = dev->conn->deviceMonitor->deviceDumpXML (dev, flags);
if (!ret)
goto error;
return ret;
}
virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return NULL;
}
/**
* virNodeDeviceGetName:
* @dev: the device
*
* Just return the device name
*
* Returns the device name or NULL in case of error
*/
const char *virNodeDeviceGetName(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return NULL;
}
return dev->name;
}
/**
* virNodeDeviceGetParent:
* @dev: the device
*
* Accessor for the parent of the device
*
* Returns the name of the device's parent, or NULL if the
* device has no parent.
*/
const char *virNodeDeviceGetParent(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return NULL;
}
if (!dev->parent) {
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceGetParent) {
dev->parent = dev->conn->deviceMonitor->deviceGetParent (dev);
} else {
virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
virSetConnError(dev->conn);
return NULL;
}
}
return dev->parent;
}
/**
* virNodeDeviceNumOfCaps:
* @dev: the device
*
* Accessor for the number of capabilities supported by the device.
*
* Returns the number of capabilities supported by the device.
*/
int virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return -1;
}
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceNumOfCaps) {
int ret;
ret = dev->conn->deviceMonitor->deviceNumOfCaps (dev);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return -1;
}
/**
* 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.
*/
int virNodeDeviceListCaps(virNodeDevicePtr dev,
char **const names,
int maxnames)
{
DEBUG("dev=%p, conn=%p, names=%p, maxnames=%d",
dev, dev ? dev->conn : NULL, names, maxnames);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return -1;
}
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceListCaps) {
int ret;
ret = dev->conn->deviceMonitor->deviceListCaps (dev, names, maxnames);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return -1;
}
/**
* virNodeDeviceFree:
* @dev: pointer to the node device
*
* Drops a reference to the node device, freeing it if
* this was the last reference.
*
* Returns the 0 for success, -1 for error.
*/
int virNodeDeviceFree(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return (-1);
}
if (virUnrefNodeDevice(dev) < 0)
return (-1);
return(0);
}
/**
* virNodeDeviceRef:
* @dev: the dev to hold a reference on
*
* Increment the reference count on the dev. For each
* additional call to this method, there shall be a corresponding
* call to virNodeDeviceFree to release the reference count, once
* the caller no longer needs the reference to this object.
*
* This method is typically useful for applications where multiple
* threads are using a connection, and it is required that the
* connection remain open until all threads have finished using
* it. ie, each new thread using a dev would increment
* the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virNodeDeviceRef(virNodeDevicePtr dev)
{
if ((!VIR_IS_CONNECTED_NODE_DEVICE(dev))) {
virLibConnError(NULL, VIR_ERR_INVALID_ARG, __FUNCTION__);
return(-1);
}
virMutexLock(&dev->conn->lock);
DEBUG("dev=%p refs=%d", dev, dev->refs);
dev->refs++;
virMutexUnlock(&dev->conn->lock);
return 0;
}
/**
* virNodeDeviceDettach:
* @dev: pointer to the node device
*
* Dettach 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.
*
* 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
virNodeDeviceDettach(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return (-1);
}
if (dev->conn->driver->nodeDeviceDettach) {
int ret;
ret = dev->conn->driver->nodeDeviceDettach (dev);
if (ret < 0)
goto error;
return ret;
}
virLibConnError(dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return (-1);
}
/**
* virNodeDeviceReAttach:
* @dev: pointer to the node device
*
* Re-attach a previously dettached node device to the node so that it
* may be used by the node again.
*
* Depending on the hypervisor, this may involve operations such
* as resetting the device, unbinding it from a dummy device driver
* and binding it to its appropriate driver.
*
* If the device is currently in use by a guest, this method may fail.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virNodeDeviceReAttach(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return (-1);
}
if (dev->conn->driver->nodeDeviceReAttach) {
int ret;
ret = dev->conn->driver->nodeDeviceReAttach (dev);
if (ret < 0)
goto error;
return ret;
}
virLibConnError(dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return (-1);
}
/**
* virNodeDeviceReset:
* @dev: pointer to the node device
*
* Reset a previously dettached node device to the node before or
* after assigning it to a guest.
*
* The exact reset semantics depends on the hypervisor and device
* type but, for example, KVM will attempt to reset PCI devices with
* a Function Level Reset, Secondary Bus Reset or a Power Management
* D-State reset.
*
* If the reset will affect other devices which are currently in use,
* this function may fail.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virNodeDeviceReset(virNodeDevicePtr dev)
{
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return (-1);
}
if (dev->conn->driver->nodeDeviceReset) {
int ret;
ret = dev->conn->driver->nodeDeviceReset (dev);
if (ret < 0)
goto error;
return ret;
}
virLibConnError(dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return (-1);
}
/**
* virNodeDeviceCreateXML:
* @conn: pointer to the hypervisor connection
* @xmlDesc: string containing an XML description of the device to be created
* @flags: callers should always pass 0
*
* Create a new device on the VM host machine, for example, virtual
* HBAs created using vport_create.
*
* 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=%d", conn, xmlDesc, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xmlDesc == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->deviceMonitor &&
conn->deviceMonitor->deviceCreateXML) {
virNodeDevicePtr dev = conn->deviceMonitor->deviceCreateXML(conn, xmlDesc, flags);
if (dev == NULL)
goto error;
return dev;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virNodeDeviceDestroy:
* @dev: a device object
*
* Destroy the device object. The virtual device 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)
{
DEBUG("dev=%p", dev);
virResetLastError();
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
return (-1);
}
if (dev->conn->flags & VIR_CONNECT_RO) {
virLibConnError(dev->conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (dev->conn->deviceMonitor &&
dev->conn->deviceMonitor->deviceDestroy) {
int retval = dev->conn->deviceMonitor->deviceDestroy(dev);
if (retval < 0) {
goto error;
}
return 0;
}
virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(dev->conn);
return -1;
}
/*
* Domain Event Notification
*/
/**
* virConnectDomainEventRegister:
* @conn: pointer to the connection
* @cb: callback to the function handling domain events
* @opaque: opaque data to pass on to the callback
* @freecb: optional function to deallocate opaque when not used anymore
*
* Adds a Domain Event Callback.
* Registering for a domain callback will enable delivery of the events
*
* The virDomainPtr object handle passed into the callback upon delivery
* of an event is only valid for the duration of execution of the callback.
* If the callback wishes to keep the domain object after the callback
* returns, it shall take a reference to it, by calling virDomainRef.
* The reference can be released once the object is no longer required
* by calling virDomainFree.
*
* Returns 0 on success, -1 on failure
*/
int
virConnectDomainEventRegister(virConnectPtr conn,
virConnectDomainEventCallback cb,
void *opaque,
virFreeCallback freecb)
{
DEBUG("conn=%p, cb=%p, opaque=%p, freecb=%p", conn, cb, opaque, freecb);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (cb == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if ((conn->driver) && (conn->driver->domainEventRegister)) {
int ret;
ret = conn->driver->domainEventRegister (conn, cb, opaque, freecb);
if (ret < 0)
goto error;
return ret;
}
virLibConnError(conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectDomainEventDeregister:
* @conn: pointer to the connection
* @cb: callback to the function handling domain events
*
* Removes a Domain Event Callback.
* De-registering for a domain callback will disable
* delivery of this event type
*
* Returns 0 on success, -1 on failure
*/
int
virConnectDomainEventDeregister(virConnectPtr conn,
virConnectDomainEventCallback cb)
{
DEBUG("conn=%p, cb=%p", conn, cb);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (-1);
}
if (cb == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if ((conn->driver) && (conn->driver->domainEventDeregister)) {
int ret;
ret = conn->driver->domainEventDeregister (conn, cb);
if (ret < 0)
goto error;
return ret;
}
virLibConnError(conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virSecretGetConnect:
* @secret: A virSecret secret
*
* Provides the connection pointer associated with a secret. The reference
* counter on the connection is not increased by this call.
*
* WARNING: When writing libvirt bindings in other languages, do not use this
* function. Instead, store the connection and the secret object together.
*
* Returns the virConnectPtr or NULL in case of failure.
*/
virConnectPtr
virSecretGetConnect (virSecretPtr secret)
{
DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET (secret)) {
virLibSecretError (NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return NULL;
}
return secret->conn;
}
/**
* virConnectNumOfSecrets:
* @conn: virConnect connection
*
* Fetch number of currently defined secrets.
*
* Returns the number currently defined secrets.
*/
int
virConnectNumOfSecrets(virConnectPtr conn)
{
VIR_DEBUG("conn=%p", conn);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (conn->secretDriver != NULL &&
conn->secretDriver->numOfSecrets != NULL) {
int ret;
ret = conn->secretDriver->numOfSecrets(conn);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virConnectListSecrets:
* @conn: virConnect connection
* @uuids: Pointer to an array to store the UUIDs
* @maxuuids: size of the array.
*
* List UUIDs of defined secrets, store pointers to names in uuids.
*
* Returns the number of UUIDs provided in the array, or -1 on failure.
*/
int
virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
{
VIR_DEBUG("conn=%p, uuids=%p, maxuuids=%d", conn, uuids, maxuuids);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return -1;
}
if (uuids == NULL || maxuuids < 0) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->secretDriver != NULL && conn->secretDriver->listSecrets != NULL) {
int ret;
ret = conn->secretDriver->listSecrets(conn, uuids, maxuuids);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virSecretLookupByUUID:
* @conn: pointer to the hypervisor connection
* @uuid: the raw UUID for the secret
*
* Try to lookup a secret on the given hypervisor based on its UUID.
* Uses the 16 bytes of raw data to describe the UUID
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*/
virSecretPtr
virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
{
DEBUG("conn=%p, uuid=%s", conn, uuid);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuid == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->secretDriver &&
conn->secretDriver->lookupByUUID) {
virSecretPtr ret;
ret = conn->secretDriver->lookupByUUID (conn, uuid);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretLookupByUUIDString:
* @conn: pointer to the hypervisor connection
* @uuidstr: the string UUID for the secret
*
* Try to lookup a secret on the given hypervisor based on its UUID.
* Uses the printable string value to describe the UUID
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*/
virSecretPtr
virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
{
int raw[VIR_UUID_BUFLEN], i;
unsigned char uuid[VIR_UUID_BUFLEN];
int ret;
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (uuidstr == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
/* XXX: sexpr_uuid() also supports 'xxxx-xxxx-xxxx-xxxx' format.
* We needn't it here. Right?
*/
ret = sscanf(uuidstr,
"%02x%02x%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x-"
"%02x%02x%02x%02x%02x%02x",
raw + 0, raw + 1, raw + 2, raw + 3,
raw + 4, raw + 5, raw + 6, raw + 7,
raw + 8, raw + 9, raw + 10, raw + 11,
raw + 12, raw + 13, raw + 14, raw + 15);
if (ret!=VIR_UUID_BUFLEN) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
for (i = 0; i < VIR_UUID_BUFLEN; i++)
uuid[i] = raw[i] & 0xFF;
return virSecretLookupByUUID(conn, &uuid[0]);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretLookupByUsage:
* @conn: pointer to the hypervisor connection
* @usageType: the type of secret usage
* @usageID: identifier of the object using the secret
*
* Try to lookup a secret on the given hypervisor based on its usage
* The usageID is unique within the set of secrets sharing the
* same usageType value.
*
* Returns a new secret object or NULL in case of failure. If the
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
*/
virSecretPtr
virSecretLookupByUsage(virConnectPtr conn,
int usageType,
const char *usageID)
{
DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return (NULL);
}
if (usageID == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->secretDriver &&
conn->secretDriver->lookupByUsage) {
virSecretPtr ret;
ret = conn->secretDriver->lookupByUsage (conn, usageType, usageID);
if (!ret)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretDefineXML:
* @conn: virConnect connection
* @xml: XML describing the secret.
* @flags: flags, use 0 for now
*
* If XML specifies an UUID, locates the specified secret and replaces all
* attributes of the secret specified by UUID by attributes specified in xml
* (any attributes not specified in xml are discarded).
*
* Otherwise, creates a new secret with an automatically chosen UUID, and
* initializes its attributes from xml.
*
* Returns a the secret on success, NULL on failure.
*/
virSecretPtr
virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
{
VIR_DEBUG("conn=%p, xml=%s, flags=%u", conn, xml, flags);
virResetLastError();
if (!VIR_IS_CONNECT(conn)) {
virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
return NULL;
}
if (conn->flags & VIR_CONNECT_RO) {
virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (xml == NULL) {
virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->secretDriver != NULL && conn->secretDriver->defineXML != NULL) {
virSecretPtr ret;
ret = conn->secretDriver->defineXML(conn, xml, flags);
if (ret == NULL)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretGetUUID:
* @secret: A virSecret secret
* @uuid: buffer of VIR_UUID_BUFLEN bytes in size
*
* Fetches the UUID of the secret.
*
* Returns 0 on success with the uuid buffer being filled, or
* -1 upon failure.
*/
int
virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
{
VIR_DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return -1;
}
if (uuid == NULL) {
virLibSecretError(secret, VIR_ERR_INVALID_ARG, __FUNCTION__);
/* Copy to connection error object for back compatability */
virSetConnError(secret->conn);
return -1;
}
memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
return 0;
}
/**
* virSecretGetUUIDString:
* @secret: a secret object
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
*
* Get the UUID for a secret as string. For more information about
* UUID see RFC4122.
*
* Returns -1 in case of error, 0 in case of success
*/
int
virSecretGetUUIDString(virSecretPtr secret, char *buf)
{
unsigned char uuid[VIR_UUID_BUFLEN];
DEBUG("secret=%p, buf=%p", secret, buf);
virResetLastError();
if (!VIR_IS_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return (-1);
}
if (buf == NULL) {
virLibSecretError(secret, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (virSecretGetUUID(secret, &uuid[0]))
goto error;
virUUIDFormat(uuid, buf);
return (0);
error:
/* Copy to connection error object for back compatability */
virSetConnError(secret->conn);
return -1;
}
/**
* virSecretGetUsageType:
* @secret: a secret object
*
* Get the type of object which uses this secret. The returned
* value is one of the constants defined in the virSecretUsageType
* enumeration. More values may be added to this enumeration in
* the future, so callers should expect to see usage types they
* do not explicitly know about.
*
* Returns a positive integer identifying the type of object,
* or -1 upon error.
*/
int
virSecretGetUsageType(virSecretPtr secret)
{
DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return (-1);
}
return (secret->usageType);
}
/**
* virSecretGetUsageID:
* @secret: a secret object
*
* Get the unique identifier of the object with which this
* secret is to be used. The format of the identifier is
* dependant on the usage type of the secret. For a secret
* with a usage type of VIR_SECRET_USAGE_TYPE_VOLUME the
* identifier will be a fully qualfied path name. The
* identifiers are intended to be unique within the set of
* all secrets sharing the same usage type. ie, there shall
* only ever be one secret for each volume path.
*
* Returns a string identifying the object using the secret,
* or NULL upon error
*/
const char *
virSecretGetUsageID(virSecretPtr secret)
{
DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return (NULL);
}
return (secret->usageID);
}
/**
* virSecretGetXMLDesc:
* @secret: A virSecret secret
* @flags: flags, use 0 for now
*
* Fetches an XML document describing attributes of the secret.
*
* Returns the XML document on success, NULL on failure. The caller must
* free() the XML.
*/
char *
virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("secret=%p, flags=%u", secret, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return NULL;
}
conn = secret->conn;
if (conn->secretDriver != NULL && conn->secretDriver->getXMLDesc != NULL) {
char *ret;
ret = conn->secretDriver->getXMLDesc(secret, flags);
if (ret == NULL)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretSetValue:
* @secret: A virSecret secret
* @value: Value of the secret
* @value_size: Size of the value
* @flags: flags, use 0 for now
*
* Sets the value of a secret.
*
* Returns 0 on success, -1 on failure.
*/
int
virSecretSetValue(virSecretPtr secret, const unsigned char *value,
size_t value_size, unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("secret=%p, value=%p, value_size=%zu, flags=%u", secret, value,
value_size, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return -1;
}
conn = secret->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibSecretError(secret, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (value == NULL) {
virLibSecretError(secret, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
if (conn->secretDriver != NULL && conn->secretDriver->setValue != NULL) {
int ret;
ret = conn->secretDriver->setValue(secret, value, value_size, flags);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virSecretGetValue:
* @secret: A virSecret connection
* @value_size: Place for storing size of the secret value
* @flags: flags, use 0 for now
*
* Fetches the value of a secret.
*
* Returns the secret value on success, NULL on failure. The caller must
* free() the secret value.
*/
unsigned char *
virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
{
virConnectPtr conn;
VIR_DEBUG("secret=%p, value_size=%p, flags=%u", secret, value_size, flags);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return NULL;
}
conn = secret->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibSecretError(secret, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (value_size == NULL) {
virLibSecretError(secret, VIR_ERR_INVALID_ARG, __FUNCTION__);
goto error;
}
flags &= VIR_SECRET_GET_VALUE_FLAGS_MASK;
if (conn->secretDriver != NULL && conn->secretDriver->getValue != NULL) {
unsigned char *ret;
ret = conn->secretDriver->getValue(secret, value_size, flags);
if (ret == NULL)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return NULL;
}
/**
* virSecretUndefine:
* @secret: A virSecret secret
*
* Deletes the specified secret. This does not free the associated
* virSecretPtr object.
*
* Returns 0 on success, -1 on failure.
*/
int
virSecretUndefine(virSecretPtr secret)
{
virConnectPtr conn;
VIR_DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return -1;
}
conn = secret->conn;
if (conn->flags & VIR_CONNECT_RO) {
virLibSecretError(secret, VIR_ERR_OPERATION_DENIED, __FUNCTION__);
goto error;
}
if (conn->secretDriver != NULL && conn->secretDriver->undefine != NULL) {
int ret;
ret = conn->secretDriver->undefine(secret);
if (ret < 0)
goto error;
return ret;
}
virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
error:
/* Copy to connection error object for back compatability */
virSetConnError(conn);
return -1;
}
/**
* virSecretRef:
* @secret: the secret to hold a reference on
*
* Increment the reference count on the secret. For each additional call to
* this method, there shall be a corresponding call to virSecretFree to release
* the reference count, once the caller no longer needs the reference to this
* object.
*
* This method is typically useful for applications where multiple threads are
* using a connection, and it is required that the connection remain open until
* all threads have finished using it. ie, each new thread using a secret would
* increment the reference count.
*
* Returns 0 in case of success, -1 in case of failure.
*/
int
virSecretRef(virSecretPtr secret)
{
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return -1;
}
virMutexLock(&secret->conn->lock);
DEBUG("secret=%p refs=%d", secret, secret->refs);
secret->refs++;
virMutexUnlock(&secret->conn->lock);
return 0;
}
/**
* virSecretFree:
* @secret: pointer to a secret
*
* Release the secret handle. The underlying secret continues to exist.
*
* Returns 0 on success, or -1 on error
*/
int
virSecretFree(virSecretPtr secret)
{
DEBUG("secret=%p", secret);
virResetLastError();
if (!VIR_IS_CONNECTED_SECRET(secret)) {
virLibSecretError(NULL, VIR_ERR_INVALID_SECRET, __FUNCTION__);
return -1;
}
if (virUnrefSecret(secret) < 0)
return -1;
return 0;
}
Reference in New Issue View Git Blame Copy Permalink