shaba/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-20 06:50:22 +03:00
Code Releases Activity

src: expand docs for guest info array handling

Browse Source 
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>
This commit is contained in:
Daniel P. Berrangé 2025-03-05 15:24:31 +00:00
parent 325b5701ae
commit 5436eba3a8
1 changed files with 50 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
src/libvirt-domain.c
View File

@ -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