lib: Add few flags for the bulk stats APIs

Add domain list filtering functions and a flag to enforce checking
whether the remote daemon supports the requested stats groups.

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index e79c9ad9318c79d817765959d0761839bb23cb85..935831434edd59952e90dfe9f0515ed991748d7b 100644 (file)
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -2513,6 +2513,21 @@ typedef enum {
     VIR_DOMAIN_STATS_STATE = (1 << 0), /* return domain state */
 } virDomainStatsTypes;
 
+typedef enum {
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE,
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE = VIR_CONNECT_LIST_DOMAINS_INACTIVE,
+
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT = VIR_CONNECT_LIST_DOMAINS_PERSISTENT,
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT = VIR_CONNECT_LIST_DOMAINS_TRANSIENT,
+
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING = VIR_CONNECT_LIST_DOMAINS_RUNNING,
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED = VIR_CONNECT_LIST_DOMAINS_PAUSED,
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF = VIR_CONNECT_LIST_DOMAINS_SHUTOFF,
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER = VIR_CONNECT_LIST_DOMAINS_OTHER,
+
+    VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS = 1 << 31, /* enforce requested stats */
+} virConnectGetAllDomainStatsFlags;
+
 int virConnectGetAllDomainStats(virConnectPtr conn,
                                 unsigned int stats,
                                 virDomainStatsRecordPtr **retStats,

diff --git a/src/libvirt.c b/src/libvirt.c
index 17ec679d9b3219c3a3ba037cfc24d31187b003d2..5d8f01c26ef52918429c5870b61834fc7e4d6a82 100644 (file)
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -21524,8 +21524,8 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
  * virConnectGetAllDomainStats:
  * @conn: pointer to the hypervisor connection
  * @stats: stats to return, binary-OR of virDomainStatsTypes
- * @retStats: Pointer that will be filled with the array of returned stats.
- * @flags: extra flags; not used yet, so callers should always pass 0
+ * @retStats: Pointer that will be filled with the array of returned stats
+ * @flags: extra flags; binary-OR of virConnectGetAllDomainStatsFlags
  *
  * Query statistics for all domains on a given connection.
  *
@@ -21549,6 +21549,26 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
  * Using 0 for @stats returns all stats groups supported by the given
  * hypervisor.
  *
+ * Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
+ * the function return error in case some of the stat types in @stats were
+ * not recognized by the daemon.
+ *
+ * Similarly to virConnectListAllDomains, @flags can contain various flags to
+ * filter the list of domains to provide stats for.
+ *
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE selects online domains while
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE selects offline ones.
+ *
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_PERSISTENT and
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_TRANSIENT allow to filter the list
+ * according to their persistence.
+ *
+ * To filter the list of VMs by domain state @flags can contain
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_RUNNING,
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_PAUSED,
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_SHUTOFF and/or
+ * VIR_CONNECT_GET_ALL_DOMAINS_STATS_OTHER for all other states.
+ *
  * Returns the count of returned statistics structures on success, -1 on error.
  * The requested data are returned in the @retStats parameter. The returned
  * array should be freed by the caller. See virDomainStatsRecordListFree.
@@ -21589,8 +21609,8 @@ virConnectGetAllDomainStats(virConnectPtr conn,
  * virDomainListGetStats:
  * @doms: NULL terminated array of domains
  * @stats: stats to return, binary-OR of virDomainStatsTypes
- * @retStats: Pointer that will be filled with the array of returned stats.
- * @flags: extra flags; not used yet, so callers should always pass 0
+ * @retStats: Pointer that will be filled with the array of returned stats
+ * @flags: extra flags; binary-OR of virConnectGetAllDomainStatsFlags
  *
  * Query statistics for domains provided by @doms. Note that all domains in
  * @doms must share the same connection.
@@ -21615,6 +21635,13 @@ virConnectGetAllDomainStats(virConnectPtr conn,
  * Using 0 for @stats returns all stats groups supported by the given
  * hypervisor.
  *
+ * Specifying VIR_CONNECT_GET_ALL_DOMAINS_STATS_ENFORCE_STATS as @flags makes
+ * the function return error in case some of the stat types in @stats were
+ * not recognized by the daemon.
+ *
+ * Note that any of the domain list filtering flags in @flags will be rejected
+ * by this function.
+ *
  * Returns the count of returned statistics structures on success, -1 on error.
  * The requested data are returned in the @retStats parameter. The returned
  * array should be freed by the caller. See virDomainStatsRecordListFree.