url: Document the expected behaviour of url_read

Message ID 1332165487-33741-1-git-send-email-martin@martin.st
State Committed
Headers show

Commit Message

Martin Storsjö March 19, 2012, 1:58 p.m.
From: Nicolas George <nicolas.george@normalesup.org>

---
 libavformat/url.h |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)

Comments

Anton Khirnov March 19, 2012, 2:19 p.m. | #1
On Mon, 19 Mar 2012 15:58:07 +0200, Martin Storsjö <martin@martin.st> wrote:
> From: Nicolas George <nicolas.george@normalesup.org>
> 
> ---
>  libavformat/url.h |   13 +++++++++++++
>  1 files changed, 13 insertions(+), 0 deletions(-)
> 
> diff --git a/libavformat/url.h b/libavformat/url.h
> index 265a8ab..66ce4a1 100644
> --- a/libavformat/url.h
> +++ b/libavformat/url.h
> @@ -59,6 +59,19 @@ typedef struct URLProtocol {
>       * for those nested protocols.
>       */
>      int     (*url_open2)(URLContext *h, const char *url, int flags, AVDictionary **options);
> +
> +    /**
> +     * Read data from the protocol.
> +     * If data is immediately available (even less than size), EOF is
> +     * reached or an error occurs (including EINTR), return immediately,

s/,$/./

Otherwise looks ok.

Patch

diff --git a/libavformat/url.h b/libavformat/url.h
index 265a8ab..66ce4a1 100644
--- a/libavformat/url.h
+++ b/libavformat/url.h
@@ -59,6 +59,19 @@  typedef struct URLProtocol {
      * for those nested protocols.
      */
     int     (*url_open2)(URLContext *h, const char *url, int flags, AVDictionary **options);
+
+    /**
+     * Read data from the protocol.
+     * If data is immediately available (even less than size), EOF is
+     * reached or an error occurs (including EINTR), return immediately,
+     * Otherwise:
+     * In non-blocking mode, return AVERROR(EAGAIN) immediately.
+     * In blocking mode, wait for data/EOF/error with a short timeout (0.1s),
+     * and return AVERROR(EAGAIN) on timeout.
+     * Checking interrupt_callback, looping on EINTR and EAGAIN and until
+     * enough data has been read is left to the calling function; see
+     * retry_transfer_wrapper in avio.c.
+     */
     int     (*url_read)( URLContext *h, unsigned char *buf, int size);
     int     (*url_write)(URLContext *h, const unsigned char *buf, int size);
     int64_t (*url_seek)( URLContext *h, int64_t pos, int whence);