src: define virDomainGetMessages API

This API allows fetching a list of informational messages recorded
against the domain. This provides a way to give information about
tainting of the guest due to undesirable actions/configs, as well
as provide details of deprecated features.

The output of this API is explicitly targetted at humans, not
machines, so it is inappropriate to attempt to pattern match on
the strings and take action off them, not least because the messages
are marked for translation.

Should there be a demand for machine targetted information, this
would have to be addressed via a new API, and is not planned at
this point in time.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index de2456812c82dd9ab41cc26757ff0be2104d8b28..8011cf9fe1a683d9ee667d385f8a392e4b9e12ac 100644 (file)
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -5119,4 +5119,13 @@ int virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
                                   unsigned int nkeys,
                                   unsigned int flags);
 
+typedef enum {
+    VIR_DOMAIN_MESSAGE_DEPRECATION = (1 << 0),
+    VIR_DOMAIN_MESSAGE_TAINTING = (1 << 1),
+} virDomainMessageType;
+
+int virDomainGetMessages(virDomainPtr domain,
+                         char ***msgs,
+                         unsigned int flags);
+
 #endif /* LIBVIRT_DOMAIN_H */

diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h
index 9e8fe89921b57e240970f8648f52276c2504208a..05d7dfb5c793fbe652b7766316cb90e3951794e0 100644 (file)
--- a/src/driver-hypervisor.h
+++ b/src/driver-hypervisor.h
@@ -1400,6 +1400,11 @@ typedef int
                                     unsigned int nkeys,
                                     unsigned int flags);
 
+typedef int
+(*virDrvDomainGetMessages)(virDomainPtr domain,
+                           char ***msgs,
+                           unsigned int flags);
+
 typedef struct _virHypervisorDriver virHypervisorDriver;
 typedef virHypervisorDriver *virHypervisorDriverPtr;
 
@@ -1665,4 +1670,5 @@ struct _virHypervisorDriver {
     virDrvDomainBackupGetXMLDesc domainBackupGetXMLDesc;
     virDrvDomainAuthorizedSSHKeysGet domainAuthorizedSSHKeysGet;
     virDrvDomainAuthorizedSSHKeysSet domainAuthorizedSSHKeysSet;
+    virDrvDomainGetMessages domainGetMessages;
 };

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index dba89a7d3a300cdf6aed9d171b4021a910a1e52c..ae318f4a1ac1d5bb8f8b93c572c8d5e02f18f2bc 100644 (file)
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -13102,3 +13102,57 @@ virDomainAuthorizedSSHKeysSet(virDomainPtr domain,
     virDispatchError(conn);
     return -1;
 }
+
+
+/**
+ * virDomainGetMessages:
+ * @domain: a domain object
+ * @msgs: pointer to a variable to store messages
+ * @flags: zero or more virDomainMessageType flags
+ *
+ * Fetch a list of all messages recorded against the VM and
+ * store them into @msgs array which is allocated upon
+ * successful return and is NULL terminated. The caller is
+ * responsible for freeing @msgs when no longer needed.
+ *
+ * If @flags is zero then all messages are reported. The
+ * virDomainMessageType constants can be used to restrict
+ * results to certain types of message.
+ *
+ * Note it is hypervisor dependant whether messages are
+ * available for shutoff guests, or running guests, or
+ * both. Thus a client should be prepared to re-fetch
+ * messages when a guest transitions between running
+ * and shutoff states.
+ *
+ * Returns: number of messages stored in @msgs,
+ *          -1 otherwise.
+ */
+int
+virDomainGetMessages(virDomainPtr domain,
+                     char ***msgs,
+                     unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(domain, "msgs=%p, flags=0x%x", msgs, flags);
+
+    virResetLastError();
+
+    virCheckDomainReturn(domain, -1);
+    conn = domain->conn;
+    virCheckNonNullArgGoto(msgs, error);
+
+    if (conn->driver->domainGetMessages) {
+        int ret;
+        ret = conn->driver->domainGetMessages(domain, msgs, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+ error:
+    virDispatchError(conn);
+    return -1;
+}

diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index cf31f937d5deb61883aa5c93c8378b6d67306516..d851333eb015ba9bdb5f4e4b6cf0c37d7e612248 100644 (file)
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -879,4 +879,9 @@ LIBVIRT_6.10.0 {
         virDomainAuthorizedSSHKeysSet;
 } LIBVIRT_6.0.0;
 
+LIBVIRT_7.1.0 {
+    global:
+        virDomainGetMessages;
+} LIBVIRT_6.10.0;
+
 # .... define new API here using predicted next version number ....