/**
* virAdmConnectRef:
* @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 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.
*
* Returns 0 in case of success, -1 in case of failure
*/
int
virAdmConnectRef(virAdmConnectPtr conn)
{
VIR_DEBUG("conn=%p refs=%d", conn,
conn ? conn->object.parent.u.s.refs : 0);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
virObjectRef(conn);
return 0;
}
/**
* virAdmConnectGetURI:
* @conn: pointer to an admin connection
*
* 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.
*
* Returns an URI string related to the connection or NULL in case of an error.
* Caller is responsible for freeing the string.
*/
char *
virAdmConnectGetURI(virAdmConnectPtr conn)
{
char *uri = NULL;
VIR_DEBUG("conn=%p", conn);
virResetLastError();
virCheckAdmConnectReturn(conn, NULL);
if (!(uri = virURIFormat(conn->uri)))
virDispatchError(NULL);
return uri;
}
/**
* virAdmConnectClose:
* @conn: pointer to admin connection to close
*
* 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.
*
* 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.
*/
int
virAdmConnectClose(virAdmConnectPtr conn)
{
VIR_DEBUG("conn=%p", conn);
virResetLastError();
if (!conn)
return 0;
virCheckAdmConnectReturn(conn, -1);
if (!virObjectUnref(conn))
return 0;
return 1;
}
/**
* virAdmConnectGetLibVersion:
* @conn: pointer to an active admin connection
* @libVer: stores the current remote libvirt version number
*
* 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.
*
* Returns 0 on success, -1 on failure and @libVer follows this format:
*/
int virAdmConnectGetLibVersion(virAdmConnectPtr conn,
unsigned long long *libVer)
{
VIR_DEBUG("conn=%p, libVir=%p", conn, libVer);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
virCheckNonNullArgReturn(libVer, -1);
if (remoteAdminConnectGetLibVersion(conn, libVer) < 0)
goto error;
return 0;
error:
virDispatchError(NULL);
return -1;
}
/**
* virAdmConnectUnregisterCloseCallback:
* @conn: pointer to connection object
* @cb: pointer to the current registered callback
*
* 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.
*
* Returns 0 on success, -1 on error
*/
int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn,
virAdmConnectCloseFunc cb)
{
VIR_DEBUG("conn=%p", conn);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
virCheckNonNullArgGoto(cb, error);
if (virAdmConnectCloseCallbackDataUnregister(conn->closeCallback, cb) < 0)
goto error;
return 0;
error:
virDispatchError(NULL);
return -1;
}
/**
* virAdmConnectRegisterCloseCallback:
* @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
*
* 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.
*
* Returns 0 on success, -1 on error
*/
int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn,
virAdmConnectCloseFunc cb,
void *opaque,
virFreeCallback freecb)
{
VIR_DEBUG("conn=%p", conn);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
virObjectRef(conn);
virObjectLock(conn);
virObjectLock(conn->closeCallback);
virCheckNonNullArgGoto(cb, error);
if (conn->closeCallback->callback) {
virReportError(VIR_ERR_OPERATION_INVALID, "%s",
_("A close callback is already registered"));
goto error;
}
conn->closeCallback->conn = conn;
conn->closeCallback->callback = cb;
conn->closeCallback->opaque = opaque;
conn->closeCallback->freeCallback = freecb;
virObjectUnlock(conn->closeCallback);
virObjectUnlock(conn);
return 0;
error:
virObjectUnlock(conn->closeCallback);
virObjectUnlock(conn);
virDispatchError(NULL);
virObjectUnref(conn);
return -1;
}
/**
* virAdmConnectSetLoggingFilters:
* @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
*
* 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.
*
* Returns 0 if the new filter or the set of filters has been defined
* successfully, or -1 in case of an error.
*/
int
virAdmConnectSetLoggingFilters(virAdmConnectPtr conn,
const char *filters,
unsigned int flags)
{
int ret = -1;
VIR_DEBUG("conn=%p, flags=0x%x", conn, flags);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
if ((ret = remoteAdminConnectSetLoggingFilters(conn, filters, flags)) < 0)
goto error;
return ret;
error:
virDispatchError(NULL);
return -1;
}
/**
* virAdmConnectIsAlive:
* @conn: connection to admin server
*
* 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.
*
* 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.
*/
int
virAdmConnectIsAlive(virAdmConnectPtr conn)
{
bool ret;
remoteAdminPrivPtr priv = NULL;
VIR_DEBUG("conn=%p", conn);
if (!conn)
return 0;
virCheckAdmConnectReturn(conn, -1);
virResetLastError();
priv = conn->privateData;
virObjectLock(priv);
ret = virNetClientIsOpen(priv->client);
virObjectUnlock(priv);
return ret;
}
/**
* virAdmConnectListServers:
* @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
*
* Collect list of all servers provided by daemon the client is connected to.
*
* 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.
*/
int
virAdmConnectListServers(virAdmConnectPtr conn,
virAdmServerPtr **servers,
unsigned int flags)
{
int ret = -1;
VIR_DEBUG("conn=%p, servers=%p, flags=%x", conn, servers, flags);
virResetLastError();
if (servers)
*servers = NULL;
virCheckAdmConnectReturn(conn, -1);
if ((ret = remoteAdminConnectListServers(conn, servers, flags)) < 0)
goto error;
return ret;
error:
virDispatchError(NULL);
return -1;
}
/**
* virAdmConnectUnregisterCloseCallback:
* @conn: pointer to connection object
* @cb: pointer to the current registered callback
*
* 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.
*
* Returns 0 on success, -1 on error
*/
int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn,
virAdmConnectCloseFunc cb)
{
VIR_DEBUG("conn=%p", conn);
virResetLastError();
virCheckAdmConnectReturn(conn, -1);
virObjectLock(conn);
virObjectLock(conn->closeCallback);
virCheckNonNullArgGoto(cb, error);
if (conn->closeCallback->callback != cb) {
virReportError(VIR_ERR_OPERATION_INVALID, "%s",
_("A different callback was requested"));
goto error;
}
conn->closeCallback->callback = NULL;
if (conn->closeCallback->freeCallback)
conn->closeCallback->freeCallback(conn->closeCallback->opaque);
conn->closeCallback->freeCallback = NULL;
virObjectUnlock(conn->closeCallback);
virObjectUnlock(conn);
virObjectUnref(conn);
return 0;
error:
virObjectUnlock(conn->closeCallback);
virObjectUnlock(conn);
virDispatchError(NULL);
return -1;
}