[PATCH 1/9] libvirt-storage: Document volume upload/download stream format
For libvirt, the volume is just a binary blob and it doesn't
interpret data on volume upload/download. But as it turns out,
this unspoken assumption is not clear to our users. Document it
explicitly.
Suggested in: https://bugzilla.redhat.com/show_bug.cgi?id=1851023#c17
Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com>
---
src/libvirt-storage.c | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c
index a45c8b98c1..8738f6dd14 100644
--- a/src/libvirt-storage.c
+++ b/src/libvirt-storage.c
@@ -1590,7 +1590,9 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
*
* Download the content of the volume as a stream. If @length
* is zero, then the remaining contents of the volume after
- * @offset will be downloaded.
+ * @offset will be downloaded. Please note, that the data is
+ * not interpreted and therefore data received by stream
+ * client are in the very same format the volume is in.
*
* If VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM is set in @flags
* effective transmission of holes is enabled. This assumes using
@@ -1663,7 +1665,9 @@ virStorageVolDownload(virStorageVolPtr vol,
* will fail if @offset + @length exceeds the size of the
* volume. Otherwise, if @length is non-zero, an error
* will be raised if an attempt is made to upload greater
- * than @length bytes of data.
+ * than @length bytes of data. Please note, that the data is
+ * not interpreted and therefore data sent by stream client
+ * must be in the very same format the volume is in.
*
* If VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM is set in @flags
* effective transmission of holes is enabled. This assumes using
--
2.26.2