Hi Sara, Thanks for making a start on this. Just a couple of things to note about streams:
A "stream" is an object that exhibits "streamable" behaviour. A "wrapper" is additional logic that knows about specific protocols (and encodings) and returns an appropriate stream to access it. A wrapper may modify certain aspects of a streams behaviour. It's quite a common misconception that a stream == a wrapper. So, stream_get_wrappers() lists the registered handlers for specific protocol schemes; this is not the same a listing the types of streams that are available (file, network, zlib, bzip2). There is currently no way to retrieve information about the latter. You can also implement wrapper functions to handle opendir() and readdir() for your schemes in your wrapper class (for stream_register_wrapper()). I gave an explanation of this on php-dev at that time (iirc); user_streams.c 1.24: Sat Sep 28 09:05:47 2002 filters can be defined in C code as well as PHP scripts; there is a "string.rot13" filter implementation written in C included in PHP 4.3.0. So it is important to note in stream_filter_(prepend|append) that extension defined filters can also be used (and not just those registered with stream_register_filter). $filter->oncreate() is called just after the filter object is instantiated, but before it is connected to a stream. It's purpose is to perform any early initialization for the filter based on $filter->params and $filter->filtername which correspond to the appropriately named parameters for stream_filter_(prepend|append). The filtername is (potentially) important because filters can be registered using a pattern (so one class handles a range of filter names). Yes, using a factory class might be a better approach, and I may yet alter the user-filter architecture in this way. It is important to note that a filter instance is reponsible for managing any buffers it requires for data passing through it. $filter->write($data) should return the number of bytes of $data that it consumed, even if the number of bytes that were passed on to the next filter in the chain (via parent::write()) are different. This is important because the return value indicates to the caller (either fread() or an earlier filter) how far to advance its buffer pointer. $filter->write() is allowed to buffer the data internally (and not call parent::write()), provided that it returns the number of bytes of the input it used to create that buffer. Obviously, it needs to be consistent and send that data on to the next filter at the appropriate time (when enough data are accumulated, or $filter->flush() is called). Likewise, $filter->read($size) is welcome to call parent::read() with a larger $size, provided that it maintains its buffers correctly. It is an error for $filter->read() to return more bytes than requested. $filter->onclose() is called during filter shutdown. It is called after $filter->flush(true) is called and it's purpose is to release any resources that were opened by this filter instance. Yes, stream contexts are very thinly documented. That's mostly because you can't do very much with them ATM. There is an open bug report with a reasonable amount of information about them (search the DB); if you feel like integrating that info, I will gladly edit it to make sure it is correct; otherwise, I'm quite happy to delay documenting this in much more detail until there are more things that make it worthwhile (because it's one of those "so-what?" features ATM). --Wez. On Sat, 4 Jan 2003, Sara Golemon wrote: > Okay, > > An initial draft of the streams reference is in CVS documenting all 14 > stream_* functions and providing three examples on the reference page. > While we all wait ((*snore*)) for php.net/manual/en to build, I've got a > local build available on my devbox: > http://169.229.139.97/phpdoc/html/current/ref.stream.html > > Note: There are a couple minor changes on ref.stream which havn't shown on > my local build yet (see r1.4), a new build is running now. > > The documentation on stream contexts is VERY thin as I frankly don't > understand how they work entirely. stream-register-filter.xml also needs > a description of what the oncreate/onclose methods do (I've asked wez in a > somewhat unrelated bug report to explain those). > > Any comments/suggestions would, as always, be appreciated. > > Happy New Year! > > -Pollita > > > > -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
