src: expand docs for guest info array handling

Give an overview of how arrays are handled and represented in
the typed parameters returned by the guest info API.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 557efcc0c09d930712021206b0b6aab70f581f9e..390f54d46e69d113f4f0ec631e12387b3ff8b82b 100644 (file)
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -13249,6 +13249,56 @@ virDomainSetVcpu(virDomainPtr domain,
  * This API requires the VM to run. The caller is responsible for calling
  * virTypedParamsFree to free memory returned in @params.
  *
+ * In a number of cases the parameters returned are representing
+ * arrays of data items. In these cases multiple VIR_DOMAIN_GUEST_INFO*
+ * constants will need to be concatenated to form a complete typed
+ * parameter key. The design pattern for handling array entries is
+ * as follows
+ *
+ * - VIR_DOMAIN_GUEST_INFO_nnnnn_COUNT
+ *
+ *   Defines the upper limit on the number of elements that will
+ *   be returned. In some cases the array information may be
+ *   sparsely populated, so it is not considered an error if a
+ *   given element does not exist. Applications should check for
+ *   each possible element upto the declared limit.
+ *
+ * - VIR_DOMAIN_GUEST_INFO_nnnnn_PREFIX
+ *
+ *   Defines the prefix to be used to construct the typed parameter
+ *   key for an array element, including the trailing '.'. The prefix
+ *   must have an array index appended, along with a suffix.
+ *
+ * - VIR_DOMAIN_GUEST_INFO_nnnnn_SUFFIX_mmmmm
+ *
+ *   Defines the suffix for accessing a particular data item within
+ *   the array element, including the leading '.'. The suffix must
+ *   have an array prefix and index prepended.
+ *
+ * As an example, assuming a printf-like formatting approach an
+ * application would construct a key as follows:
+ *
+ *     format(VIR_DOMAIN_GUEST_INFO_FS_PREFIX +
+ *            "%d" +
+ *            VIR_DOMAIN_GUEST_INFO_FS_SUFFIX_NAME,
+ *            index)
+ *
+ * Which, when index==3, would result in the key "fs.3.name"
+ *
+ * In some cases there may be nested arrays, in which case the key
+ * is formed by concatenating multiple prefixes and suffixes with
+ * mutliple array indexes. For example:
+ *
+ *     format(VIR_DOMAIN_GUEST_INFO_FS_PREFIX +
+ *            "%d" +
+ *            VIR_DOMAIN_GUEST_INFO_FS_SUFFIX_DISK_PREFIX +
+ *            "%d" +
+ *            VIR_DOMAIN_GUEST_INFO_FS_SUFFIX_DISK_SUFFIX_SERIAL
+ *            fsindex, diskindex)
+ *
+ * Which, when fsindex==3 and diskindex==7, would result in the
+ * key "fs.3.disk.7.serial".
+ *
  * Returns 0 on success, -1 on error.
  *
  * Since: 5.7.0