[libvirt] [PATCH] virDomainDetachDeviceFlags: Clarify update semantics
https://bugzilla.redhat.com/show_bug.cgi?id=1621910
When users want to update a path to a CDROM they tend to
construct a very minimal XML and feed the API with it. This is
not a good practice as it breaks the assumptions the API is built
on. Most notably, leaving an element out should be treated as a
request for removal of the corresponding setting. Just like
leaving out <bandwidth/> clears out any QoS previously set.
Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com>
---
src/libvirt-domain.c | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index ef460277f7..bd8ca6eff2 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -8318,6 +8318,14 @@ virDomainDetachDeviceFlags(virDomainPtr domain,
* media, altering the graphics configuration such as password,
* reconfiguring the NIC device backend connectivity, etc.
*
+ * The supplied XML description of the device should contain all
+ * the information that are found in corresponding domain XML.
+ * Leaving out any piece of information is treated as request for
+ * its removal, which may be denied. For instance, when users
+ * want to change CDROM media only for live XML, they must
+ * provide live disk XML as found in corresponding live domain
+ * XML with only the disk path changed.
+ *
* Returns 0 in case of success, -1 in case of failure.
*/
int
--
2.16.4