From: Peter Krempa <pkrempa@redhat.com> Briefly describe what the introspection API returns. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/docs.rst | 1 + docs/formatintrospection.rst | 90 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 1 + 3 files changed, 92 insertions(+) create mode 100644 docs/formatintrospection.rst diff --git a/docs/docs.rst b/docs/docs.rst index 09939c1201..110afba1fc 100644 --- a/docs/docs.rst +++ b/docs/docs.rst @@ -100,6 +100,7 @@ Application development * `snapshots <formatsnapshot.html>`__ * `checkpoints <formatcheckpoint.html>`__ * `backup jobs <formatbackup.html>`__ + * `introspection XML <formatintrospection.html>`__ `Language bindings and API modules <bindings.html>`__ Bindings of the libvirt API for diff --git a/docs/formatintrospection.rst b/docs/formatintrospection.rst new file mode 100644 index 0000000000..80244a7917 --- /dev/null +++ b/docs/formatintrospection.rst @@ -0,0 +1,90 @@ +.. role:: since + +============================ +API introspection XML format +============================ + +.. contents:: + +Overview +-------- + +The API parameter introspection API +`virConnectGetIntrospection <html/libvirt-libvirt-host.html#virConnectGetIntrospection>`__ +allows callers probing which flags and parameters are supported by given API on +given hypervisor. + +The XML has following structure:: + + <libvirt-introspection> + <hypervisor> + <api name='virDomainMigrateToURI3'> + <flags dec='2097151' hex='0x1fffff'/> + <typed-parameters type='input' name='params'> + <param name='migrate_uri' type='string'/> + <param name='destination_name' type='string'/> + <param name='destination_xml' type='string'/> + <param name='bandwidth' type='ullong'/> + <param name='graphics_uri' type='string'/> + <param name='listen_address' type='string'/> + <param name='migrate_disks' type='string' multiple='yes'/> + </typed-parameters> + </api> + + [...] + + </hypervisor> + </libvirt-introspection> + +API groups +---------- + +`virConnectGetIntrospection <html/libvirt-libvirt-host.html#virConnectGetIntrospection>`__ +reports the supported APIs grouped by which driver kind they were queried for. + +Currently only hypervisor drivers are queried and the APIs supported by the +hypervisor driver the connection connects to are reported under ``<hypervisor>`` +sub-element. + + +API element +----------- + +The ``<api>`` element is an entry for an individual API identified by the name +attribute. The value refers to the C function name of the given API. Sub +elements describe possible values for some of the arguments. + +API flags +~~~~~~~~~ + +If the ``<api>`` element has a ``<flags>`` sub-elements, the API accepts a +'flags' parameter. Both ``dec`` and ``hex`` attributes then contain a bitmask +of accepted flag bits by given API in decimal and hexadecimal encoding. + + +``virTypedParams`` argument +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``<typed-parameters>`` element + +The ``name`` attribute specifies the C parameter name that the typed parameters +are passed as. + +The ``type`` attribute specifies whether the typed parameters are arguments to +the API (``input``) or are filled by the API and returned (``output``). + +The ``param`` sub-elenents of ``<typed-parameters>`` then list each supported +parameter name and the type. Following ``type`` values are supported along with +the corresponding `virTypedParameterType <html/libvirt-libvirt-common.html#virTypedParameterType>`__ +value: + + * ``int`` -> ``VIR_TYPED_PARAM_INT`` + * ``uint`` -> ``VIR_TYPED_PARAM_UINT`` + * ``llong`` -> ``VIR_TYPED_PARAM_LLONG`` + * ``ullong`` -> ``VIR_TYPED_PARAM_ULLONG`` + * ``double`` -> ``VIR_TYPED_PARAM_DOUBLE`` + * ``boolean`` -> ``VIR_TYPED_PARAM_BOOLEAN`` + * ``string`` -> ``VIR_TYPED_PARAM_STRING`` + +For typed parameter values which can be specified multiple times with given API +the ``param`` element has a ``multiple='yes'`` attribute. diff --git a/docs/meson.build b/docs/meson.build index 0e74f9c4bf..485356e08b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -67,6 +67,7 @@ docs_rst_files = [ 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', + 'formatintrospection', 'formatnetwork', 'formatnetworkport', 'formatnode', -- 2.54.0