Non-blocking protocols: flag and documentation

Signed-off-by: Nicolas George <nicolas.george@normalesup.org>
Signed-off-by: Ronald S. Bultje <rsbultje@gmail.com>
(cherry picked from commit fe174fc8)

doc/APIchanges

@@ -13,6 +13,9 @@ libavutil:   2009-03-08
 
 API changes, most recent first:
 
+2011-02-XX - XXXXXXX - lavf 52.XX.0 - avio.h
+  Add flag for non-blocking protocols: URL_FLAG_NONBLOCK
+
 2011-02-04 - f124b08 - lavf 52.96.0 - avformat_free_context()
   Add avformat_free_context() in avformat.h.
 

libavformat/avio.h

@@ -63,9 +63,32 @@ typedef struct URLPollEntry {
     int revents;
 } URLPollEntry;
 
-#define URL_RDONLY 0
-#define URL_WRONLY 1
-#define URL_RDWR   2
+/**
+ * @defgroup open_modes URL open modes
+ * The flags argument to url_open and cosins must be one of the following
+ * constants, optionally ORed with other flags.
+ * @{
+ */
+#define URL_RDONLY 0  /**< read-only */
+#define URL_WRONLY 1  /**< write-only */
+#define URL_RDWR   2  /**< read-write */
+/**
+ * @}
+ */
+
+/**
+ * Use non-blocking mode.
+ * If this flag is set, operations on the context will return
+ * AVERROR(EAGAIN) if they can not be performed immediately.
+ * If this flag is not set, operations on the context will never return
+ * AVERROR(EAGAIN).
+ * Note that this flag does not affect the opening/connecting of the
+ * context. Connecting a protocol will always block if necessary (e.g. on
+ * network protocols) but never hang (e.g. on busy devices).
+ * Warning: non-blocking protocols is work-in-progress; this flag may be
+ * silently ignored.
+ */
+#define URL_FLAG_NONBLOCK 4
 
 typedef int URLInterruptCB(void);