Although we already have virStreamRecv, just like some other
older APIs it is missing @flags argument. This means, the
function is not that flexible and therefore we need
virStreamRecvFlags. The latter is going to be needed when we will
want it to stop at a hole in stream.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 include/libvirt/libvirt-stream.h |  5 ++++
 src/driver-stream.h              |  7 +++++
 src/libvirt-stream.c             | 60 ++++++++++++++++++++++++++++++++++++++++
 src/libvirt_public.syms          |  5 ++++
 4 files changed, 77 insertions(+)

diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h
index 831640d..bee2516 100644
--- a/include/libvirt/libvirt-stream.h
+++ b/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:
diff --git a/src/driver-stream.h b/src/driver-stream.h
index 85b4e3b..d4b0480 100644
--- a/src/driver-stream.h
+++ b/src/driver-stream.h
@@ -36,6 +36,12 @@ typedef int
                     size_t nbytes);
 
 typedef int
+(*virDrvStreamRecvFlags)(virStreamPtr st,
+                         char *data,
+                         size_t nbytes,
+                         unsigned int flags);
+
+typedef int
 (*virDrvStreamEventAddCallback)(virStreamPtr stream,
                                 int events,
                                 virStreamEventCallback cb,
@@ -61,6 +67,7 @@ typedef virStreamDriver *virStreamDriverPtr;
 struct _virStreamDriver {
     virDrvStreamSend streamSend;
     virDrvStreamRecv streamRecv;
+    virDrvStreamRecvFlags streamRecvFlags;
     virDrvStreamEventAddCallback streamEventAddCallback;
     virDrvStreamEventUpdateCallback streamEventUpdateCallback;
     virDrvStreamEventRemoveCallback streamEventRemoveCallback;
diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c
index 8384b37..80b2d47 100644
--- a/src/libvirt-stream.c
+++ b/src/libvirt-stream.c
@@ -286,6 +286,66 @@ 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. In fact, calling virStreamRecvFlags(stream, data,
+ * nbytes, 0) is equivalent to calling virStreamRecv(stream,
+ * data, nbytes) and vice versa.
+ *
+ * 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=%zi 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
  * @handler: source callback for reading data from application
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 428cf2e..af863bb 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -759,4 +759,9 @@ LIBVIRT_3.1.0 {
         virDomainSetVcpu;
 } LIBVIRT_3.0.0;
 
+LIBVIRT_3.3.0 {
+    global:
+        virStreamRecvFlags;
+} LIBVIRT_3.1.0;
+
 # .... define new API here using predicted next version number ....
-- 
2.10.2

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On 04/20/2017 06:01 AM, Michal Privoznik wrote:
> Although we already have virStreamRecv, just like some other
> older APIs it is missing @flags argument. This means, the
> function is not that flexible and therefore we need
> virStreamRecvFlags. The latter is going to be needed when we will
> want it to stop at a hole in stream.

Could just simply state 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 |  5 ++++
>  src/driver-stream.h              |  7 +++++
>  src/libvirt-stream.c             | 60 ++++++++++++++++++++++++++++++++++++++++
>  src/libvirt_public.syms          |  5 ++++
>  4 files changed, 77 insertions(+)
> 

[...]

> diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c
> index 8384b37..80b2d47 100644
> --- a/src/libvirt-stream.c
> +++ b/src/libvirt-stream.c
> @@ -286,6 +286,66 @@ 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. In fact, calling virStreamRecvFlags(stream, data,
> + * nbytes, 0) is equivalent to calling virStreamRecv(stream,
> + * data, nbytes) and vice versa.

Instead, consider:

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=%zi flags=%x",
> +              stream, data, nbytes, flags);

Should 'zi' be 'zu'?  I realize this is cut-n-paste, so perhaps other
usages could be fixed in a trivial patch as well.

> +
> +    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
>   * @handler: source callback for reading data from application
> diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
> index 428cf2e..af863bb 100644
> --- a/src/libvirt_public.syms
> +++ b/src/libvirt_public.syms
> @@ -759,4 +759,9 @@ LIBVIRT_3.1.0 {
>          virDomainSetVcpu;
>  } LIBVIRT_3.0.0;
>  
> +LIBVIRT_3.3.0 {


This will be (at least) 3.4.0...

ACK w/ a couple of adjustments.  Feels strange to not see
remote_protocol.x changed at the same time though...

John
> +    global:
> +        virStreamRecvFlags;
> +} LIBVIRT_3.1.0;
> +
>  # .... define new API here using predicted next version number ....
> 

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list