Fix for php_stream_gets when the implementation does not support it

natively (Thanks Marcus).

Implement php_stream_make_seekable() and add STREAM_MUST_SEEK as an
option to php_stream_open_wrapper().
See README.STREAMS for usage.

1 files changed, 43 insertions, 1 deletions

diff --git a/README.STREAMS b/README.STREAMS
index 897d40db4e..6100c8b272 100644
--- a/README.STREAMS
+++ b/README.STREAMS
@@ -51,7 +51,16 @@ Where:
         IGNORE_URL      - do not use plugin wrappers
         REPORT_ERRORS   - show errors in a standard format if something
                           goes wrong.
-    opened_path is used to return the path of the actual file opened.
+        STREAM_MUST_SEEK - If you really need to be able to seek the stream
+                           and don't need to be able to write to the original
+                           file/URL, use this option to arrange for the stream
+                           to be copied (if needed) into a stream that can
+                           be seek()ed.
+                           
+    opened_path is used to return the path of the actual file opened,
+    but if you used STREAM_MUST_SEEK, may not be valid.  You are
+    responsible for efree()ing opened_path.  opened_path may be (and usually
+    is) NULL.
 
 If you need to open a specific stream, or convert standard resources into
 streams there are a range of functions to do this defined in php_streams.h.
@@ -109,6 +118,39 @@ The buffer is allocated using pemalloc(); you need to call pefree() to
 release the memory when you are done.
 As with copy_to_stream, this function will try use mmap where it can.
 
+If you have an existing stream and need to be able to seek() it, you
+can use this function to copy the contents into a new stream that can
+be seek()ed:
+
+PHPAPI int php_stream_make_seekable(php_stream *origstream, php_stream **newstream);
+
+It returns one of the following values:
+#define PHP_STREAM_UNCHANGED	0 /* orig stream was seekable anyway */
+#define PHP_STREAM_RELEASED		1 /* newstream should be used; origstream is no longer valid */
+#define PHP_STREAM_FAILED		2 /* an error occurred while attempting conversion */
+#define PHP_STREAM_CRITICAL		3 /* an error occurred; origstream is in an unknown state; you should close origstream */
+
+make_seekable will always set newstream to be the stream that is valid
+if the function succeeds.
+When you have finished, remember to close the stream.
+
+NOTE: If you only need to seek forwards, there is no need to call this
+function, as the php_stream_seek can emulate forward seeking when the
+whence parameter is SEEK_CUR.
+
+NOTE: Writing to the stream may not affect the original source, so it
+only makes sense to use this for read-only use.
+
+NOTE: If the origstream is network based, this function will block
+until the whole contents have been downloaded.
+
+NOTE: Never call this function with an origstream that is referenced
+as a resource! It will close the origstream on success, and this
+can lead to a crash when the resource is later used/released.
+
+NOTE: If you are opening a stream and need it to be seekable, use the
+STREAM_MUST_SEEK option to php_stream_open_wrapper();
+
 Casting Streams
 ===============
 What if your extension needs to access the FILE* of a user level file pointer?