# 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	virAdmConnectSetDaemonTimeout	(virAdmConnectPtr conn,
    					 unsigned int timeout,
    					 unsigned int flags)
    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)
    int	virAdmServerUpdateTlsFiles	(virAdmServerPtr srv,
    					 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

### `virAdmConnectSetDaemonTimeout`

    int	virAdmConnectSetDaemonTimeout	(virAdmConnectPtr conn,
    					 unsigned int timeout,
    					 unsigned int flags)

Reconfigure the existing timeout of the daemon to `timeout`. Setting timeout to 0 disables the daemon timeout.

conn
  pointer to an active admin connection
timeout
  timeout to set in seconds (0 disables timeout)
flags
  extra flags; not used yet, so callers should always pass 0
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.

### `virAdmServerUpdateTlsFiles`

    int	virAdmServerUpdateTlsFiles	(virAdmServerPtr srv,
    					 unsigned int flags)

Notify server to update tls file, such as cacert, cacrl, server cert / key.

srv
  a valid server object reference
flags
  extra flags; not used yet, so callers should always pass 0
Returns
  0 if the TLS files have been updated successfully or -1 in case of an error.