Module libvirt-admin from libvirt-admin

Provides the interfaces of the libvirt library to operate with the server itself, not any hypervisors. Copyright (C) 2014-2015 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see http://www.gnu.org/licenses/.

Table of Contents

Macros

#define VIR_CLIENT_INFO_READONLY
#define VIR_CLIENT_INFO_SASL_USER_NAME
#define VIR_CLIENT_INFO_SELINUX_CONTEXT
#define VIR_CLIENT_INFO_SOCKET_ADDR
#define VIR_CLIENT_INFO_UNIX_GROUP_ID
#define VIR_CLIENT_INFO_UNIX_GROUP_NAME
#define VIR_CLIENT_INFO_UNIX_PROCESS_ID
#define VIR_CLIENT_INFO_UNIX_USER_ID
#define VIR_CLIENT_INFO_UNIX_USER_NAME
#define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME
#define VIR_SERVER_CLIENTS_CURRENT
#define VIR_SERVER_CLIENTS_MAX
#define VIR_SERVER_CLIENTS_UNAUTH_CURRENT
#define VIR_SERVER_CLIENTS_UNAUTH_MAX
#define VIR_THREADPOOL_JOB_QUEUE_DEPTH
#define VIR_THREADPOOL_WORKERS_CURRENT
#define VIR_THREADPOOL_WORKERS_FREE
#define VIR_THREADPOOL_WORKERS_MAX
#define VIR_THREADPOOL_WORKERS_MIN
#define VIR_THREADPOOL_WORKERS_PRIORITY

Types

typedef struct _virAdmClient virAdmClient
typedef virAdmClient * virAdmClientPtr
typedef struct _virAdmConnect virAdmConnect
typedef virAdmConnect * virAdmConnectPtr
typedef struct _virAdmServer virAdmServer
typedef virAdmServer * virAdmServerPtr
typedef enum virClientTransport

Functions

int	virAdmClientClose		(virAdmClientPtr client, 
unsigned int flags) int virAdmClientFree (virAdmClientPtr client) unsigned long long virAdmClientGetID (virAdmClientPtr client) int virAdmClientGetInfo (virAdmClientPtr client,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) long long virAdmClientGetTimestamp (virAdmClientPtr client) int virAdmClientGetTransport (virAdmClientPtr client) int virAdmConnectClose (virAdmConnectPtr conn) typedef virAdmConnectCloseFunc void virAdmConnectCloseFunc (virAdmConnectPtr conn,
int reason,
void * opaque) int virAdmConnectGetLibVersion (virAdmConnectPtr conn,
unsigned long long * libVer) int virAdmConnectGetLoggingFilters (virAdmConnectPtr conn,
char ** filters,
unsigned int flags) int virAdmConnectGetLoggingOutputs (virAdmConnectPtr conn,
char ** outputs,
unsigned int flags) char * virAdmConnectGetURI (virAdmConnectPtr conn) int virAdmConnectIsAlive (virAdmConnectPtr conn) int virAdmConnectListServers (virAdmConnectPtr conn,
virAdmServerPtr ** servers,
unsigned int flags) virAdmServerPtr virAdmConnectLookupServer (virAdmConnectPtr conn,
const char * name,
unsigned int flags) virAdmConnectPtr virAdmConnectOpen (const char * name,
unsigned int flags) int virAdmConnectRef (virAdmConnectPtr conn) int virAdmConnectRegisterCloseCallback (virAdmConnectPtr conn,
virAdmConnectCloseFunc cb,
void * opaque,
virFreeCallback freecb) int virAdmConnectSetLoggingFilters (virAdmConnectPtr conn,
const char * filters,
unsigned int flags) int virAdmConnectSetLoggingOutputs (virAdmConnectPtr conn,
const char * outputs,
unsigned int flags) int virAdmConnectUnregisterCloseCallback (virAdmConnectPtr conn,
virAdmConnectCloseFunc cb) int virAdmGetVersion (unsigned long long * libVer) int virAdmInitialize (void) int virAdmServerFree (virAdmServerPtr srv) int virAdmServerGetClientLimits (virAdmServerPtr srv,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) const char * virAdmServerGetName (virAdmServerPtr srv) int virAdmServerGetThreadPoolParameters (virAdmServerPtr srv,
virTypedParameterPtr * params,
int * nparams,
unsigned int flags) int virAdmServerListClients (virAdmServerPtr srv,
virAdmClientPtr ** clients,
unsigned int flags) virAdmClientPtr virAdmServerLookupClient (virAdmServerPtr srv,
unsigned long long id,
unsigned int flags) int virAdmServerSetClientLimits (virAdmServerPtr srv,
virTypedParameterPtr params,
int nparams,
unsigned int flags) int virAdmServerSetThreadPoolParameters (virAdmServerPtr srv,
virTypedParameterPtr params,
int nparams,
unsigned int flags)

Description

Macros

VIR_CLIENT_INFO_READONLY

#define VIR_CLIENT_INFO_READONLY

Macro represents client's connection permission, whether the client is connected in read-only mode or just the opposite - read-write, as VIR_TYPED_PARAM_BOOLEAN. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_SASL_USER_NAME

#define VIR_CLIENT_INFO_SASL_USER_NAME

Macro represents client's SASL user name, if SASL authentication is enabled on the remote host, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_SELINUX_CONTEXT

#define VIR_CLIENT_INFO_SELINUX_CONTEXT

Macro represents the client's (peer's) SELinux context and this can either be at socket layer or at transport layer, depending on the connection type, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_SOCKET_ADDR

#define VIR_CLIENT_INFO_SOCKET_ADDR

Macro represents clients network socket address in a standard URI format: (IPv4|[IPv6]):port, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_UNIX_GROUP_ID

#define VIR_CLIENT_INFO_UNIX_GROUP_ID

Macro represents UNIX GID the client process is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_UNIX_GROUP_NAME

#define VIR_CLIENT_INFO_UNIX_GROUP_NAME

Macro represents the group name that is bound to the client process's GID it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_UNIX_PROCESS_ID

#define VIR_CLIENT_INFO_UNIX_PROCESS_ID

Macro represents the client process's pid it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_UNIX_USER_ID

#define VIR_CLIENT_INFO_UNIX_USER_ID

Macro represents UNIX UID the client process is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_INT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_UNIX_USER_NAME

#define VIR_CLIENT_INFO_UNIX_USER_NAME

Macro represents the user name that is bound to the client process's UID it is running with. Only relevant for clients connected locally, i.e. via a UNIX socket, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME

#define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME

Macro represents the 'distinguished name' field in X509 certificate the client used to establish a TLS session with remote host, as VIR_TYPED_PARAM_STRING. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_SERVER_CLIENTS_CURRENT

#define VIR_SERVER_CLIENTS_CURRENT

Macro for per-server nclients attribute: represents the current number of clients connected to the server, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_SERVER_CLIENTS_MAX

#define VIR_SERVER_CLIENTS_MAX

Macro for per-server nclients_max limit: represents the upper limit to number of clients connected to the server, as uint.

VIR_SERVER_CLIENTS_UNAUTH_CURRENT

#define VIR_SERVER_CLIENTS_UNAUTH_CURRENT

Macro for per-server nclients_unauth attribute: represents the current number of clients connected to the server, but not authenticated yet, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_SERVER_CLIENTS_UNAUTH_MAX

#define VIR_SERVER_CLIENTS_UNAUTH_MAX

Macro for per-server nclients_unauth_max limit: represents the upper limit to number of clients connected to the server, but not authenticated yet, as VIR_TYPED_PARAM_UINT.

VIR_THREADPOOL_JOB_QUEUE_DEPTH

#define VIR_THREADPOOL_JOB_QUEUE_DEPTH

Macro for the threadpool jobQueueDepth attribute: represents the current number of jobs waiting in a queue to be processed, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_THREADPOOL_WORKERS_CURRENT

#define VIR_THREADPOOL_WORKERS_CURRENT

Macro for the threadpool nWorkers attribute: represents the current number of active ordinary workers in threadpool, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_THREADPOOL_WORKERS_FREE

#define VIR_THREADPOOL_WORKERS_FREE

Macro for the threadpool freeWorkers attribute: represents the current number of free workers available to accomplish a job, as VIR_TYPED_PARAM_UINT. NOTE: This attribute is read-only and any attempt to set it will be denied by daemon

VIR_THREADPOOL_WORKERS_MAX

#define VIR_THREADPOOL_WORKERS_MAX

Macro for the threadpool maxWorkers limit: represents the upper limit to number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. The value of this limit has to be greater than VIR_THREADPOOL_WORKERS_MIN at all times.

VIR_THREADPOOL_WORKERS_MIN

#define VIR_THREADPOOL_WORKERS_MIN

Macro for the threadpool minWorkers limit: represents the bottom limit to number of active workers in threadpool, as VIR_TYPED_PARAM_UINT.

VIR_THREADPOOL_WORKERS_PRIORITY

#define VIR_THREADPOOL_WORKERS_PRIORITY

Macro for the threadpool nPrioWorkers attribute: represents the current number of active priority workers in threadpool, as VIR_TYPED_PARAM_UINT.

Types

virAdmClient

struct virAdmClient {
The content of this structure is not made public by the API
}

virAdmConnect

struct virAdmConnect {
The content of this structure is not made public by the API
}

virAdmServer

struct virAdmServer {
The content of this structure is not made public by the API
}

virClientTransport

enum virClientTransport {
VIR_CLIENT_TRANS_UNIX = 0 (0x0)
connection via UNIX socket
VIR_CLIENT_TRANS_TCP = 1 (0x1)
connection via unencrypted TCP socket
VIR_CLIENT_TRANS_TLS = 2 (0x2)
connection via encrypted TCP socket
VIR_CLIENT_TRANS_LAST = 3 (0x3)
}

Functions

virAdmClientClose

int	virAdmClientClose		(virAdmClientPtr client,
					 unsigned int flags)

Close @client's connection to daemon forcefully.

client
a valid client object reference
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 if the daemon's connection with @client was closed successfully or -1 in case of an error.

virAdmClientFree

int	virAdmClientFree		(virAdmClientPtr client)

Release the client object. The running instance is kept alive. The data structure is freed and should not be used thereafter.

client
a client object
Returns
0 in success, -1 on failure.

virAdmClientGetID

unsigned long long	virAdmClientGetID	(virAdmClientPtr client)

Get client's unique numeric ID.

client
a client object
Returns
numeric value used for client's ID or -1 in case of an error.

virAdmClientGetInfo

int	virAdmClientGetInfo		(virAdmClientPtr client,
					 virTypedParameterPtr * params,
					 int * nparams,
					 unsigned int flags)

Extract identity information about a client. Attributes returned in @params are mostly transport-dependent, i.e. some attributes including client process's pid, gid, uid, or remote side's socket address are only available for a specific connection type - local vs remote. Other identity attributes like authentication method used (if authentication is enabled on the remote host), SELinux context, or an indicator whether client is connected via a read-only connection are independent of the connection transport.

Note that the read-only connection indicator returns false for TCP/TLS clients because libvirt treats such connections as read-write by default, even though a TCP client is able to restrict access to certain APIs for itself.

client
a client object reference
params
pointer to a list of typed parameters which will be allocated to store all returned parameters
nparams
pointer which will hold the number of params returned in @params
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 if the information has been successfully retrieved or -1 in case of an error.

virAdmClientGetTimestamp

long long	virAdmClientGetTimestamp	(virAdmClientPtr client)

Get client's connection time. A situation may happen, that some clients had connected prior to the update to admin API, thus, libvirt assigns these clients epoch time to express that it doesn't know when the client connected.

client
a client object
Returns
client's connection timestamp (seconds from epoch in UTC) or 0 (epoch time) if libvirt doesn't have any information about client's connection time, or -1 in case of an error.

virAdmClientGetTransport

int	virAdmClientGetTransport	(virAdmClientPtr client)

Get client's connection transport type. This information can be helpful to differentiate between clients connected locally or remotely. An exception to this would be SSH which is one of libvirt's supported transports. Although SSH creates a channel between two (preferably) remote endpoints, the client process libvirt spawns automatically on the remote side will still connect to a UNIX socket, thus becoming indistinguishable from any other locally connected clients.

client
a client object
Returns
integer representation of the connection transport used by @client (this will be one of virClientTransport) or -1 in case of an error.

virAdmConnectClose

int	virAdmConnectClose		(virAdmConnectPtr conn)

This function closes the admin 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.

Connections are reference counted; the count is explicitly increased by the initial virAdmConnectOpen, as well as virAdmConnectRef; it is also temporarily increased by other API that depend on the connection remaining alive. The open and every virAdmConnectRef call should have a matching virAdmConnectClose, and all other references will be released after the corresponding operation completes.

conn
pointer to admin connection to close
Returns
a positive number if at least 1 reference remains on success. The returned value should not be assumed to be the total reference count. A return of 0 implies no references remain and the connection is closed and memory has been freed. A return of -1 implies a failure. It is possible for the last virAdmConnectClose to return a positive value if some other object still has a temporary reference to the connection, but the application should not try to further use a connection after the virAdmConnectClose that matches the initial open.

virAdmConnectCloseFunc

typedef void	(*virAdmConnectCloseFunc	)	(virAdmConnectPtr conn,
					 int reason,
					 void * opaque)

A callback to be registered, in case a connection was closed.

conn
virAdmConnect connection
reason
reason why the connection was closed (see virConnectCloseReason)
opaque
opaque client data

virAdmConnectGetLibVersion

int	virAdmConnectGetLibVersion	(virAdmConnectPtr conn,
					 unsigned long long * libVer)

Retrieves the remote side libvirt version used by the daemon. Format returned in @libVer is of a following pattern: major * 1,000,000 + minor * 1,000 + release.

conn
pointer to an active admin connection
libVer
stores the current remote libvirt version number
Returns
0 on success, -1 on failure and @libVer follows this format:

virAdmConnectGetLoggingFilters

int	virAdmConnectGetLoggingFilters	(virAdmConnectPtr conn,
					 char ** filters,
					 unsigned int flags)

Retrieves a list of currently installed logging filters. Filters returned are contained within an automatically allocated string and delimited by spaces. The format of each filter conforms to the format described in daemon's configuration file (e.g. libvirtd.conf).

To retrieve individual filters, additional parsing needs to be done by the caller. Caller is also responsible for freeing @filters correctly.

conn
pointer to an active admin connection
filters
pointer to a variable to store a string containing all currently defined logging filters on daemon (allocated automatically) or NULL if just the number of defined outputs is required
flags
extra flags; not used yet, so callers should always pass 0
Returns
the number of filters returned in @filters, or -1 in case of an error.

virAdmConnectGetLoggingOutputs

int	virAdmConnectGetLoggingOutputs	(virAdmConnectPtr conn,
					 char ** outputs,
					 unsigned int flags)

Retrieves a list of currently installed logging outputs. Outputs returned are contained within an automatically allocated string and delimited by spaces. The format of each output conforms to the format described in daemon's configuration file (e.g. libvirtd.conf).

To retrieve individual outputs, additional parsing needs to be done by the caller. Caller is also responsible for freeing @outputs correctly.

conn
pointer to an active admin connection
outputs
pointer to a variable to store a string containing all currently defined logging outputs on daemon (allocated automatically) or NULL if just the number of defined outputs is required
flags
extra flags; not used yet, so callers should always pass 0
Returns
the count of outputs in @outputs, or -1 in case of an error.

virAdmConnectGetURI

char *	virAdmConnectGetURI		(virAdmConnectPtr conn)

String returned by this method is normally the same as the string passed to the virAdmConnectOpen. Even if NULL was passed to virAdmConnectOpen, this method returns a non-null URI string.

conn
pointer to an admin connection
Returns
an URI string related to the connection or NULL in case of an error. Caller is responsible for freeing the string.

virAdmConnectIsAlive

int	virAdmConnectIsAlive		(virAdmConnectPtr conn)

Decide whether the connection to the admin server is alive or not. Connection is considered alive if the channel it is running over is not closed.

conn
connection to admin server
Returns
1, if the connection is alive, 0 if there isn't an existing connection at all or the channel has already been closed, or -1 on error.

virAdmConnectListServers

int	virAdmConnectListServers	(virAdmConnectPtr conn,
					 virAdmServerPtr ** servers,
					 unsigned int flags)

Collect list of all servers provided by daemon the client is connected to.

conn
daemon connection reference
servers
Pointer to a list to store an array containing objects or NULL if the list is not required (number of servers only)
flags
extra flags; not used yet, so callers should always pass 0
Returns
the number of servers available on daemon side or -1 in case of a failure, setting @servers to NULL. There is a guaranteed extra element set to NULL in the @servers list returned to make the iteration easier, excluding this extra element from the final count. Caller is responsible to call virAdmServerFree() on each list element, followed by freeing @servers.

virAdmConnectLookupServer

virAdmServerPtr	virAdmConnectLookupServer	(virAdmConnectPtr conn,
						 const char * name,
						 unsigned int flags)

Try to lookup a server on the given daemon based on @name.

virAdmServerFree() should be used to free the resources after the server object is no longer needed.

conn
daemon connection reference
name
name of the server too lookup
flags
extra flags; not used yet, so callers should always pass 0
Returns
the requested server or NULL in case of failure. If the server cannot be found, then VIR_ERR_NO_SERVER error is raised.

virAdmConnectOpen

virAdmConnectPtr	virAdmConnectOpen	(const char * name,
						 unsigned int flags)

Opens connection to admin interface of the daemon.

name
uri of the daemon to connect to, NULL for default
flags
bitwise-OR of virConnectFlags; so far the only supported flag is VIR_CONNECT_NO_ALIASES
Returns
@virAdmConnectPtr object or NULL on error

virAdmConnectRef

int	virAdmConnectRef		(virAdmConnectPtr conn)

Increment the reference count on the connection. For each additional call to this method, there shall be a corresponding call to virAdmConnectClose 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. I.e., each new thread using a connection would increment the reference count.

conn
the connection to hold a reference on
Returns
0 in case of success, -1 in case of failure

virAdmConnectRegisterCloseCallback

int	virAdmConnectRegisterCloseCallback	(virAdmConnectPtr conn,
						 virAdmConnectCloseFunc cb,
						 void * opaque,
						 virFreeCallback freecb)

Registers a callback to be invoked when the connection is closed. This callback is invoked when there is any condition that causes the socket connection to the hypervisor to be closed.

The @freecb must not invoke any other libvirt public APIs, since it is not called from a re-entrant safe context.

conn
connection to admin server
cb
callback to be invoked upon connection close
opaque
user data to pass to @cb
freecb
callback to free @opaque
Returns
0 on success, -1 on error

virAdmConnectSetLoggingFilters

int	virAdmConnectSetLoggingFilters	(virAdmConnectPtr conn,
					 const char * filters,
					 unsigned int flags)

Redefine the existing (set of) filter(s) with a new one specified in @filters. If multiple filters are specified, they need to be delimited by spaces. The format of each filter must conform to the format described in daemon's configuration file (e.g. libvirtd.conf).

To clear the currently defined (set of) filter(s), pass either an empty string ("") or NULL in @filters.

conn
pointer to an active admin connection
filters
pointer to a string containing a list of filters to be defined
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 if the new filter or the set of filters has been defined successfully, or -1 in case of an error.

virAdmConnectSetLoggingOutputs

int	virAdmConnectSetLoggingOutputs	(virAdmConnectPtr conn,
					 const char * outputs,
					 unsigned int flags)

Redefine the existing (set of) outputs(s) with a new one specified in @outputs. If multiple outputs are specified, they need to be delimited by spaces. The format of each output must conform to the format described in daemon's configuration file (e.g. libvirtd.conf).

To reset the existing (set of) output(s) to libvirt's defaults, an empty string ("") or NULL should be passed in @outputs.

conn
pointer to an active admin connection
outputs
pointer to a string containing a list of outputs to be defined
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 if the new output or the set of outputs has been defined successfully, or -1 in case of an error.

virAdmConnectUnregisterCloseCallback

int	virAdmConnectUnregisterCloseCallback	(virAdmConnectPtr conn,
						 virAdmConnectCloseFunc cb)

Unregisters the callback previously set with the virAdmConnectRegisterCloseCallback method. The callback will no longer receive notifications when the connection closes. If a virFreeCallback was provided at time of registration, it will be invoked.

conn
pointer to connection object
cb
pointer to the current registered callback
Returns
0 on success, -1 on error

virAdmGetVersion

int	virAdmGetVersion		(unsigned long long * libVer)

Provides version information. @libVer is the version of the library and will always be set unless an error occurs in which case an error code and a generic message will be returned. @libVer format is as follows: major * 1,000,000 + minor * 1,000 + release.

NOTE: To get the remote side library version use virAdmConnectGetLibVersion instead.

libVer
where to store the library version
Returns
0 on success, -1 in case of an error.

virAdmInitialize

int	virAdmInitialize		(void)

Initialize the library.

This method is automatically invoked by virAdmConnectOpen() API. Therefore, in most cases it is unnecessary to call this method manually, unless an event loop should be set up by calling virEventRegisterImpl() or the error reporting of the first connection attempt with virSetErrorFunc() should be altered prior to setting up connections. If the latter is the case, it is necessary for the application to call virAdmInitialize.

Returns
0 in case of success, -1 in case of error

virAdmServerFree

int	virAdmServerFree		(virAdmServerPtr srv)

Release the server object. The running instance is kept alive. The data structure is freed and should not be used thereafter.

srv
server object
Returns
0 on success, -1 on failure.

virAdmServerGetClientLimits

int	virAdmServerGetClientLimits	(virAdmServerPtr srv,
					 virTypedParameterPtr * params,
					 int * nparams,
					 unsigned int flags)

Retrieve client limits from server @srv. These include: - current number of clients connected to @srv, - maximum number of clients connected to @srv, - current number of clients connected to @srv waiting for authentication, - maximum number of clients connected to @srv that can be wainting for authentication.

srv
a valid server object reference
params
pointer to client limits object (return value, allocated automatically)
nparams
pointer to number of parameters returned in @params
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 on success, allocating @params to size returned in @nparams, or -1 in case of an error. Caller is responsible for deallocating @params.

virAdmServerGetName

const char *	virAdmServerGetName	(virAdmServerPtr srv)

Get the public name for specified server

srv
a server object
Returns
a pointer to the name or NULL. The string doesn't need to be deallocated since its lifetime will be the same as the server object.

virAdmServerGetThreadPoolParameters

int	virAdmServerGetThreadPoolParameters	(virAdmServerPtr srv,
						 virTypedParameterPtr * params,
						 int * nparams,
						 unsigned int flags)

Retrieves threadpool parameters from @srv. Upon successful completion, @params will be allocated automatically to hold all returned data, setting @nparams accordingly. When extracting parameters from @params, following search keys are supported: VIR_THREADPOOL_WORKERS_MIN VIR_THREADPOOL_WORKERS_MAX VIR_THREADPOOL_WORKERS_PRIORITY VIR_THREADPOOL_WORKERS_FREE VIR_THREADPOOL_WORKERS_CURRENT

srv
a valid server object reference
params
pointer to a list of typed parameters which will be allocated to store all returned parameters
nparams
pointer which will hold the number of params returned in @params
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 on success, -1 in case of an error.

virAdmServerListClients

int	virAdmServerListClients		(virAdmServerPtr srv,
					 virAdmClientPtr ** clients,
					 unsigned int flags)

Collect list of all clients connected to daemon on server @srv.

srv
a valid server object reference
clients
pointer to a list to store an array containing objects or NULL if the list is not required (number of clients only)
flags
extra flags; not used yet, so callers should always pass 0
Returns
the number of clients connected to daemon on server @srv -1 in case of a failure, setting @clients to NULL. There is a guaranteed extra element set to NULL in the @clients list returned to make the iteration easier, excluding this extra element from the final count. Caller is responsible to call virAdmClientFree() on each list element, followed by freeing @clients.

virAdmServerLookupClient

virAdmClientPtr	virAdmServerLookupClient	(virAdmServerPtr srv,
						 unsigned long long id,
						 unsigned int flags)

Try to lookup a client on the given server based on @id.

virAdmClientFree() should be used to free the resources after the client object is no longer needed.

srv
a valid server object reference
id
ID of the client to lookup on server @srv
flags
extra flags; not used yet, so callers should always pass 0
Returns
the requested client or NULL in case of failure. If the client could not be found, then VIR_ERR_NO_CLIENT error is raised.

virAdmServerSetClientLimits

int	virAdmServerSetClientLimits	(virAdmServerPtr srv,
					 virTypedParameterPtr params,
					 int nparams,
					 unsigned int flags)

Change client limits configuration on server @srv.

Caller is responsible for allocating @params prior to calling this function. See 'Manage per-server client limits' in libvirt-admin.h for supported parameters in @params.

srv
a valid server object reference
params
pointer to client limits object
nparams
number of parameters in @params
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 if the limits have been changed successfully or -1 in case of an error.

virAdmServerSetThreadPoolParameters

int	virAdmServerSetThreadPoolParameters	(virAdmServerPtr srv,
						 virTypedParameterPtr params,
						 int nparams,
						 unsigned int flags)

Change server threadpool parameters according to @params. Note that some tunables are read-only, thus any attempt to set them will result in a failure.

srv
a valid server object reference
params
pointer to threadpool typed parameter objects
nparams
number of parameters in @params
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 on success, -1 in case of an error.