home *** CD-ROM | disk | FTP | other *** search
- The code may be freely distributed as long as the copyright message and
- conditions are kept with each file. Anyone who likes it please feel
- free to send me some money (>=10). You will recieve a disk with the
- latest version of gstream - and any new stream types I've made.
-
- Note: these files are NOT Public Domain, as I retain copyright.
-
- Disclaimer:
- -----------
-
- This code is supplied in good faith, but not liability can be accepted
- for loss incurred through the use or inability to use this code.
-
- Author:
- -------
- Simon Proven
- email: sproven@cs.strath.ac.uk
- snail mail: Castle Cottage,
- Portencross,
- West Kilbride,
- KA23 9QA
- SCOTLAND
-
-
- Docs
- ----
-
- gstream provides a uniform means of communicating with various devices
- or applications in RISC OS. It provides a range of functions similar
- to the stdio functions (eg fprintf == gsprintf ). However, streams are
- opened differently - via a number of bolt on extensions which implement
- the low level access to a given type of stream. This makes it possible
- for users of gstream to add their own types of stream without needing
- to make any changes to gstream itself. This is advantageous in that
- the gstream code will not get hacked up by a million different people,
- which would make updates to newer versions very difficult.
-
- Most of the functions exported by gstream can be understood by looking
- at their stdio equivalents - where differences occur these are
- documented in the sources. It is hoped that these differences will be
- removed when I can be bothered.
-
- The only other functions which need explaining to the user of gstream
- are:
-
- gsopeninternalw
- gsopeninternalr
- gsdiscardinternal
- gsgetbuf
-
- The first three of these provide a means to hold data in flex blocks.
- The system is write once, read many - ie you first of all open a flex
- block to write to with gsopeninternalw, write your data to it, then
- gsclose it. Then, you can open the same stream with gsopeninternalr
- and read the data back, then gsclose it. If you then use
- gsopeninternalr again will be able to read the data back again.
-
- gsdiscardinternal frees the memory used by the internal stream, ready
- losing the data. After it has been called you can then call
- gsopeninternalw again.
-
- gsgetbuf is a function which tries to claim a flex block between
- minsize and maxsize bytes in size, returing the size of block claimed
- (0 if no block was claimed). See examples of its use in gstream,
- osstream and ramstream.
-
- The rest should be fairly self-explanatory. To see how to create your
- own stream types, look at osstream, ramstream and xferstream, and the
- example below.
-
- Things to do
- ------------
-
- * Add stream types for Acorn's Cut/Copy/Paste protocol
-
- * Add stream types to handle RISC OS 3 pipes - so that a m/tasking app
- can not only write to a pipe but also read from one without hanging.
-
- * Add stream types to write to screen and read from keyboard. If in
- m/tasking app, these stream types will open a window on the screen for
- I/O. Suggestions wanted.
-
- * Try to allow saving back to sending task (currently won't work - has
- to be trapped by xferrecv to avoid crash)
-
-