Introduce virStreamRecvFlags

This patch is adding the virStreamRecvFlags as a variant to the
virStreamRecv function in order to allow for future expansion of
functionality for processing sparse streams using a @flags
argument.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>

include/libvirt/libvirt-stream.h

@@ -45,6 +45,11 @@ int virStreamRecv(virStreamPtr st,
                   char *data,
                   size_t nbytes);
 
+int virStreamRecvFlags(virStreamPtr st,
+                       char *data,
+                       size_t nbytes,
+                       unsigned int flags);
+
 
 /**
  * virStreamSourceFunc:

src/driver-stream.h

@@ -35,6 +35,12 @@ typedef int
                     char *data,
                     size_t nbytes);
 
+typedef int
+(*virDrvStreamRecvFlags)(virStreamPtr st,
+                         char *data,
+                         size_t nbytes,
+                         unsigned int flags);
+
 typedef int
 (*virDrvStreamEventAddCallback)(virStreamPtr stream,
                                 int events,
@@ -61,6 +67,7 @@ typedef virStreamDriver *virStreamDriverPtr;
 struct _virStreamDriver {
     virDrvStreamSend streamSend;
     virDrvStreamRecv streamRecv;
+    virDrvStreamRecvFlags streamRecvFlags;
     virDrvStreamEventAddCallback streamEventAddCallback;
     virDrvStreamEventUpdateCallback streamEventUpdateCallback;
     virDrvStreamEventRemoveCallback streamEventRemoveCallback;

src/libvirt-stream.c

@@ -285,6 +285,65 @@ virStreamRecv(virStreamPtr stream,
 }
 
 
+/**
+ * virStreamRecvFlags:
+ * @stream: pointer to the stream object
+ * @data: buffer to read into from stream
+ * @nbytes: size of @data buffer
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Reads a series of bytes from the stream. This method may
+ * block the calling application for an arbitrary amount
+ * of time.
+ *
+ * This is just like virStreamRecv except this one has extra
+ * @flags. Calling this function with no @flags set (equal to
+ * zero) is equivalent to calling virStreamRecv(stream, data, nbytes).
+ *
+ * Returns 0 when the end of the stream is reached, at
+ * which time the caller should invoke virStreamFinish()
+ * to get confirmation of stream completion.
+ *
+ * Returns -1 upon error, at which time the stream will
+ * be marked as aborted, and the caller should now release
+ * the stream with virStreamFree.
+ *
+ * Returns -2 if there is no data pending to be read & the
+ * stream is marked as non-blocking.
+ */
+int
+virStreamRecvFlags(virStreamPtr stream,
+                   char *data,
+                   size_t nbytes,
+                   unsigned int flags)
+{
+    VIR_DEBUG("stream=%p, data=%p, nbytes=%zu flags=%x",
+              stream, data, nbytes, flags);
+
+    virResetLastError();
+
+    virCheckStreamReturn(stream, -1);
+    virCheckNonNullArgGoto(data, error);
+
+    if (stream->driver &&
+        stream->driver->streamRecvFlags) {
+        int ret;
+        ret = (stream->driver->streamRecvFlags)(stream, data, nbytes, flags);
+        if (ret == -2)
+            return -2;
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(stream->conn);
+    return -1;
+}
+
+
 /**
  * virStreamSendAll:
  * @stream: pointer to the stream object

src/libvirt_public.syms

@@ -759,4 +759,9 @@ LIBVIRT_3.1.0 {
         virDomainSetVcpu;
 } LIBVIRT_3.0.0;
 
+LIBVIRT_3.4.0 {
+    global:
+        virStreamRecvFlags;
+} LIBVIRT_3.1.0;
+
 # .... define new API here using predicted next version number ....