Introduce a src/libvirt-secret.c file to hold all the
methods related to the virSecret type.
---
docs/apibuild.py | 1 +
po/POTFILES.in | 1 +
src/Makefile.am | 2 +
src/libvirt-secret.c | 695 +++++++++++++++++++++++++++++++++++++++++++++++++++
src/libvirt.c | 668 -------------------------------------------------
5 files changed, 699 insertions(+), 668 deletions(-)
create mode 100644 src/libvirt-secret.c
diff --git a/docs/apibuild.py b/docs/apibuild.py
index cf329e2..90a816d 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -29,6 +29,7 @@ included_files = {
"libvirt-network.c": "Network interfaces for the libvirt library",
"libvirt-nodedev.c": "Node device interfaces for the libvirt library",
"libvirt-nwfilter.c": "NWFilter interfaces for the libvirt library",
+ "libvirt-secret.c": "Secret interfaces for the libvirt library",
"virerror.c": "implements error handling and reporting code for libvirt",
"virevent.c": "event loop for monitoring file handles",
"virtypedparam.c": "virTypedParameters APIs",
diff --git a/po/POTFILES.in b/po/POTFILES.in
index a628bb3..7d14790 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -61,6 +61,7 @@ src/libvirt-domain-snapshot.c
src/libvirt-lxc.c
src/libvirt-network.c
src/libvirt-nwfilter.c
+src/libvirt-secret.c
src/libvirt-qemu.c
src/locking/lock_daemon.c
src/locking/lock_daemon_config.c
diff --git a/src/Makefile.am b/src/Makefile.am
index dfc5920..62aca8a 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -194,6 +194,7 @@ DRIVER_SOURCES = \
libvirt-network.c \
libvirt-nodedev.c \
libvirt-nwfilter.c \
+ libvirt-secret.c \
locking/lock_manager.c locking/lock_manager.h \
locking/lock_driver.h \
locking/lock_driver_nop.h locking/lock_driver_nop.c \
@@ -2196,6 +2197,7 @@ libvirt_setuid_rpc_client_la_SOURCES = \
libvirt-network.c \
libvirt-nodedev.c \
libvirt-nwfilter.c \
+ libvirt-secret.c \
libvirt-lxc.c \
$(NULL)
diff --git a/src/libvirt-secret.c b/src/libvirt-secret.c
new file mode 100644
index 0000000..bf6678c
--- /dev/null
+++ b/src/libvirt-secret.c
@@ -0,0 +1,695 @@
+/*
+ * libvirt-secret.c: entry points for virSecretPtr APIs
+ *
+ * Copyright (C) 2006-2014 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/>.
+ */
+
+#include <config.h>
+
+#include "datatypes.h"
+#include "virlog.h"
+
+VIR_LOG_INIT("libvirt.secret");
+
+#define VIR_FROM_THIS VIR_FROM_NONE
+
+/**
+ * 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)
+{
+ VIR_DEBUG("secret=%p", secret);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, 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();
+
+ virCheckConnectReturn(conn, -1);
+
+ if (conn->secretDriver != NULL &&
+ conn->secretDriver->connectNumOfSecrets != NULL) {
+ int ret;
+
+ ret = conn->secretDriver->connectNumOfSecrets(conn);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
+/**
+ * virConnectListAllSecrets:
+ * @conn: Pointer to the hypervisor connection.
+ * @secrets: Pointer to a variable to store the array containing the secret
+ * objects or NULL if the list is not required (just returns the
+ * number of secrets).
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Collect the list of secrets, and allocate an array to store those
+ * objects.
+ *
+ * Normally, all secrets are returned; however, @flags can be used to
+ * filter the results for a smaller list of targeted secrets. The valid
+ * flags are divided into groups, where each group contains bits that
+ * describe mutually exclusive attributes of a secret, and where all bits
+ * within a group describe all possible secrets.
+ *
+ * The first group of @flags is used to filter secrets by its storage
+ * location. Flag VIR_CONNECT_LIST_SECRETS_EPHEMERAL selects secrets that
+ * are kept only in memory. Flag VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL
+ * selects secrets that are kept in persistent storage.
+ *
+ * The second group of @flags is used to filter secrets by privacy. Flag
+ * VIR_CONNECT_LIST_SECRETS_PRIVATE seclets secrets that are never revealed
+ * to any caller of libvirt nor to any other node. Flag
+ * VIR_CONNECT_LIST_SECRETS_NO_PRIVATE selects non-private secrets.
+ *
+ * Returns the number of secrets found or -1 and sets @secrets to NULL in case
+ * of error. On success, the array stored into @secrets is guaranteed to
+ * have an extra allocated element set to NULL but not included in the return count,
+ * to make iteration easier. The caller is responsible for calling
+ * virSecretFree() on each array element, then calling free() on @secrets.
+ */
+int
+virConnectListAllSecrets(virConnectPtr conn,
+ virSecretPtr **secrets,
+ unsigned int flags)
+{
+ VIR_DEBUG("conn=%p, secrets=%p, flags=%x", conn, secrets, flags);
+
+ virResetLastError();
+
+ if (secrets)
+ *secrets = NULL;
+
+ virCheckConnectReturn(conn, -1);
+
+ if (conn->secretDriver &&
+ conn->secretDriver->connectListAllSecrets) {
+ int ret;
+ ret = conn->secretDriver->connectListAllSecrets(conn, secrets, flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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();
+
+ virCheckConnectReturn(conn, -1);
+ virCheckNonNullArgGoto(uuids, error);
+ virCheckNonNegativeArgGoto(maxuuids, error);
+
+ if (conn->secretDriver != NULL && conn->secretDriver->connectListSecrets != NULL) {
+ int ret;
+
+ ret = conn->secretDriver->connectListSecrets(conn, uuids, maxuuids);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * 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)
+{
+ VIR_UUID_DEBUG(conn, uuid);
+
+ virResetLastError();
+
+ virCheckConnectReturn(conn, NULL);
+ virCheckNonNullArgGoto(uuid, error);
+
+ if (conn->secretDriver &&
+ conn->secretDriver->secretLookupByUUID) {
+ virSecretPtr ret;
+ ret = conn->secretDriver->secretLookupByUUID(conn, uuid);
+ if (!ret)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * 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)
+{
+ unsigned char uuid[VIR_UUID_BUFLEN];
+ VIR_DEBUG("conn=%p, uuidstr=%s", conn, NULLSTR(uuidstr));
+
+ virResetLastError();
+
+ virCheckConnectReturn(conn, NULL);
+ virCheckNonNullArgGoto(uuidstr, error);
+
+ if (virUUIDParse(uuidstr, uuid) < 0) {
+ virReportInvalidArg(uuidstr,
+ _("uuidstr in %s must be a valid UUID"),
+ __FUNCTION__);
+ goto error;
+ }
+
+ return virSecretLookupByUUID(conn, &uuid[0]);
+
+ error:
+ virDispatchError(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.
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * 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)
+{
+ VIR_DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
+
+ virResetLastError();
+
+ virCheckConnectReturn(conn, NULL);
+ virCheckNonNullArgGoto(usageID, error);
+
+ if (conn->secretDriver &&
+ conn->secretDriver->secretLookupByUsage) {
+ virSecretPtr ret;
+ ret = conn->secretDriver->secretLookupByUsage(conn, usageType, usageID);
+ if (!ret)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virSecretDefineXML:
+ * @conn: virConnect connection
+ * @xml: XML describing the secret.
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * If XML specifies a 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.
+ *
+ * virSecretFree should be used to free the resources after the
+ * secret object is no longer needed.
+ *
+ * Returns a secret on success, NULL on failure.
+ */
+virSecretPtr
+virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
+{
+ VIR_DEBUG("conn=%p, xml=%s, flags=%x", conn, xml, flags);
+
+ virResetLastError();
+
+ virCheckConnectReturn(conn, NULL);
+ virCheckReadOnlyGoto(conn->flags, error);
+ virCheckNonNullArgGoto(xml, error);
+
+ if (conn->secretDriver != NULL && conn->secretDriver->secretDefineXML != NULL) {
+ virSecretPtr ret;
+
+ ret = conn->secretDriver->secretDefineXML(conn, xml, flags);
+ if (ret == NULL)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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();
+
+ virCheckSecretReturn(secret, -1);
+ virCheckNonNullArgGoto(uuid, error);
+
+ memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
+
+ return 0;
+
+ error:
+ virDispatchError(secret->conn);
+ return -1;
+}
+
+
+/**
+ * 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)
+{
+ VIR_DEBUG("secret=%p, buf=%p", secret, buf);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, -1);
+ virCheckNonNullArgGoto(buf, error);
+
+ virUUIDFormat(secret->uuid, buf);
+ return 0;
+
+ error:
+ virDispatchError(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)
+{
+ VIR_DEBUG("secret=%p", secret);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, -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)
+{
+ VIR_DEBUG("secret=%p", secret);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, NULL);
+
+ return secret->usageID;
+}
+
+
+/**
+ * virSecretGetXMLDesc:
+ * @secret: A virSecret secret
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * 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=%x", secret, flags);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, NULL);
+ conn = secret->conn;
+
+ if (conn->secretDriver != NULL && conn->secretDriver->secretGetXMLDesc != NULL) {
+ char *ret;
+
+ ret = conn->secretDriver->secretGetXMLDesc(secret, flags);
+ if (ret == NULL)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(conn);
+ return NULL;
+}
+
+
+/**
+ * virSecretSetValue:
+ * @secret: A virSecret secret
+ * @value: Value of the secret
+ * @value_size: Size of the value
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * 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=%x", secret, value,
+ value_size, flags);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, -1);
+ conn = secret->conn;
+
+ virCheckReadOnlyGoto(conn->flags, error);
+ virCheckNonNullArgGoto(value, error);
+
+ if (conn->secretDriver != NULL && conn->secretDriver->secretSetValue != NULL) {
+ int ret;
+
+ ret = conn->secretDriver->secretSetValue(secret, value, value_size, flags);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(conn);
+ return -1;
+}
+
+
+/**
+ * virSecretGetValue:
+ * @secret: A virSecret connection
+ * @value_size: Place for storing size of the secret value
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * 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=%x", secret, value_size, flags);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, NULL);
+ conn = secret->conn;
+
+ virCheckReadOnlyGoto(conn->flags, error);
+ virCheckNonNullArgGoto(value_size, error);
+
+ if (conn->secretDriver != NULL && conn->secretDriver->secretGetValue != NULL) {
+ unsigned char *ret;
+
+ ret = conn->secretDriver->secretGetValue(secret, value_size, flags, 0);
+ if (ret == NULL)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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();
+
+ virCheckSecretReturn(secret, -1);
+ conn = secret->conn;
+
+ virCheckReadOnlyGoto(conn->flags, error);
+
+ if (conn->secretDriver != NULL && conn->secretDriver->secretUndefine != NULL) {
+ int ret;
+
+ ret = conn->secretDriver->secretUndefine(secret);
+ if (ret < 0)
+ goto error;
+ return ret;
+ }
+
+ virReportUnsupportedError();
+
+ error:
+ virDispatchError(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)
+{
+ VIR_DEBUG("secret=%p refs=%d", secret,
+ secret ? secret->object.u.s.refs : 0);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, -1);
+
+ virObjectRef(secret);
+ 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)
+{
+ VIR_DEBUG("secret=%p", secret);
+
+ virResetLastError();
+
+ virCheckSecretReturn(secret, -1);
+
+ virObjectUnref(secret);
+ return 0;
+}
diff --git a/src/libvirt.c b/src/libvirt.c
index 79f9696..c40a132 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -12809,674 +12809,6 @@ virConnectDomainEventDeregister(virConnectPtr conn,
/**
- * 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)
-{
- VIR_DEBUG("secret=%p", secret);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, 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();
-
- virCheckConnectReturn(conn, -1);
-
- if (conn->secretDriver != NULL &&
- conn->secretDriver->connectNumOfSecrets != NULL) {
- int ret;
-
- ret = conn->secretDriver->connectNumOfSecrets(conn);
- if (ret < 0)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(conn);
- return -1;
-}
-
-
-/**
- * virConnectListAllSecrets:
- * @conn: Pointer to the hypervisor connection.
- * @secrets: Pointer to a variable to store the array containing the secret
- * objects or NULL if the list is not required (just returns the
- * number of secrets).
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * Collect the list of secrets, and allocate an array to store those
- * objects.
- *
- * Normally, all secrets are returned; however, @flags can be used to
- * filter the results for a smaller list of targeted secrets. The valid
- * flags are divided into groups, where each group contains bits that
- * describe mutually exclusive attributes of a secret, and where all bits
- * within a group describe all possible secrets.
- *
- * The first group of @flags is used to filter secrets by its storage
- * location. Flag VIR_CONNECT_LIST_SECRETS_EPHEMERAL selects secrets that
- * are kept only in memory. Flag VIR_CONNECT_LIST_SECRETS_NO_EPHEMERAL
- * selects secrets that are kept in persistent storage.
- *
- * The second group of @flags is used to filter secrets by privacy. Flag
- * VIR_CONNECT_LIST_SECRETS_PRIVATE seclets secrets that are never revealed
- * to any caller of libvirt nor to any other node. Flag
- * VIR_CONNECT_LIST_SECRETS_NO_PRIVATE selects non-private secrets.
- *
- * Returns the number of secrets found or -1 and sets @secrets to NULL in case
- * of error. On success, the array stored into @secrets is guaranteed to
- * have an extra allocated element set to NULL but not included in the return count,
- * to make iteration easier. The caller is responsible for calling
- * virSecretFree() on each array element, then calling free() on @secrets.
- */
-int
-virConnectListAllSecrets(virConnectPtr conn,
- virSecretPtr **secrets,
- unsigned int flags)
-{
- VIR_DEBUG("conn=%p, secrets=%p, flags=%x", conn, secrets, flags);
-
- virResetLastError();
-
- if (secrets)
- *secrets = NULL;
-
- virCheckConnectReturn(conn, -1);
-
- if (conn->secretDriver &&
- conn->secretDriver->connectListAllSecrets) {
- int ret;
- ret = conn->secretDriver->connectListAllSecrets(conn, secrets, flags);
- if (ret < 0)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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();
-
- virCheckConnectReturn(conn, -1);
- virCheckNonNullArgGoto(uuids, error);
- virCheckNonNegativeArgGoto(maxuuids, error);
-
- if (conn->secretDriver != NULL && conn->secretDriver->connectListSecrets != NULL) {
- int ret;
-
- ret = conn->secretDriver->connectListSecrets(conn, uuids, maxuuids);
- if (ret < 0)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * 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)
-{
- VIR_UUID_DEBUG(conn, uuid);
-
- virResetLastError();
-
- virCheckConnectReturn(conn, NULL);
- virCheckNonNullArgGoto(uuid, error);
-
- if (conn->secretDriver &&
- conn->secretDriver->secretLookupByUUID) {
- virSecretPtr ret;
- ret = conn->secretDriver->secretLookupByUUID(conn, uuid);
- if (!ret)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * 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)
-{
- unsigned char uuid[VIR_UUID_BUFLEN];
- VIR_DEBUG("conn=%p, uuidstr=%s", conn, NULLSTR(uuidstr));
-
- virResetLastError();
-
- virCheckConnectReturn(conn, NULL);
- virCheckNonNullArgGoto(uuidstr, error);
-
- if (virUUIDParse(uuidstr, uuid) < 0) {
- virReportInvalidArg(uuidstr,
- _("uuidstr in %s must be a valid UUID"),
- __FUNCTION__);
- goto error;
- }
-
- return virSecretLookupByUUID(conn, &uuid[0]);
-
- error:
- virDispatchError(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.
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * 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)
-{
- VIR_DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
-
- virResetLastError();
-
- virCheckConnectReturn(conn, NULL);
- virCheckNonNullArgGoto(usageID, error);
-
- if (conn->secretDriver &&
- conn->secretDriver->secretLookupByUsage) {
- virSecretPtr ret;
- ret = conn->secretDriver->secretLookupByUsage(conn, usageType, usageID);
- if (!ret)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(conn);
- return NULL;
-}
-
-
-/**
- * virSecretDefineXML:
- * @conn: virConnect connection
- * @xml: XML describing the secret.
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * If XML specifies a 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.
- *
- * virSecretFree should be used to free the resources after the
- * secret object is no longer needed.
- *
- * Returns a secret on success, NULL on failure.
- */
-virSecretPtr
-virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
-{
- VIR_DEBUG("conn=%p, xml=%s, flags=%x", conn, xml, flags);
-
- virResetLastError();
-
- virCheckConnectReturn(conn, NULL);
- virCheckReadOnlyGoto(conn->flags, error);
- virCheckNonNullArgGoto(xml, error);
-
- if (conn->secretDriver != NULL && conn->secretDriver->secretDefineXML != NULL) {
- virSecretPtr ret;
-
- ret = conn->secretDriver->secretDefineXML(conn, xml, flags);
- if (ret == NULL)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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();
-
- virCheckSecretReturn(secret, -1);
- virCheckNonNullArgGoto(uuid, error);
-
- memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
-
- return 0;
-
- error:
- virDispatchError(secret->conn);
- return -1;
-}
-
-
-/**
- * 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)
-{
- VIR_DEBUG("secret=%p, buf=%p", secret, buf);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, -1);
- virCheckNonNullArgGoto(buf, error);
-
- virUUIDFormat(secret->uuid, buf);
- return 0;
-
- error:
- virDispatchError(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)
-{
- VIR_DEBUG("secret=%p", secret);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, -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)
-{
- VIR_DEBUG("secret=%p", secret);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, NULL);
-
- return secret->usageID;
-}
-
-
-/**
- * virSecretGetXMLDesc:
- * @secret: A virSecret secret
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * 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=%x", secret, flags);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, NULL);
- conn = secret->conn;
-
- if (conn->secretDriver != NULL && conn->secretDriver->secretGetXMLDesc != NULL) {
- char *ret;
-
- ret = conn->secretDriver->secretGetXMLDesc(secret, flags);
- if (ret == NULL)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(conn);
- return NULL;
-}
-
-
-/**
- * virSecretSetValue:
- * @secret: A virSecret secret
- * @value: Value of the secret
- * @value_size: Size of the value
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * 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=%x", secret, value,
- value_size, flags);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, -1);
- conn = secret->conn;
-
- virCheckReadOnlyGoto(conn->flags, error);
- virCheckNonNullArgGoto(value, error);
-
- if (conn->secretDriver != NULL && conn->secretDriver->secretSetValue != NULL) {
- int ret;
-
- ret = conn->secretDriver->secretSetValue(secret, value, value_size, flags);
- if (ret < 0)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(conn);
- return -1;
-}
-
-
-/**
- * virSecretGetValue:
- * @secret: A virSecret connection
- * @value_size: Place for storing size of the secret value
- * @flags: extra flags; not used yet, so callers should always pass 0
- *
- * 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=%x", secret, value_size, flags);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, NULL);
- conn = secret->conn;
-
- virCheckReadOnlyGoto(conn->flags, error);
- virCheckNonNullArgGoto(value_size, error);
-
- if (conn->secretDriver != NULL && conn->secretDriver->secretGetValue != NULL) {
- unsigned char *ret;
-
- ret = conn->secretDriver->secretGetValue(secret, value_size, flags, 0);
- if (ret == NULL)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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();
-
- virCheckSecretReturn(secret, -1);
- conn = secret->conn;
-
- virCheckReadOnlyGoto(conn->flags, error);
-
- if (conn->secretDriver != NULL && conn->secretDriver->secretUndefine != NULL) {
- int ret;
-
- ret = conn->secretDriver->secretUndefine(secret);
- if (ret < 0)
- goto error;
- return ret;
- }
-
- virReportUnsupportedError();
-
- error:
- virDispatchError(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)
-{
- VIR_DEBUG("secret=%p refs=%d", secret,
- secret ? secret->object.u.s.refs : 0);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, -1);
-
- virObjectRef(secret);
- 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)
-{
- VIR_DEBUG("secret=%p", secret);
-
- virResetLastError();
-
- virCheckSecretReturn(secret, -1);
-
- virObjectUnref(secret);
- return 0;
-}
-
-
-/**
* virStreamNew:
* @conn: pointer to the connection
* @flags: bitwise-OR of virStreamFlags
--
2.1.0
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list