Path: utzoo!utgpu!attcan!uunet!lll-winken!lll-tis!helios.ee.lbl.gov!pasteur!ucbvax!POSTGRES.BERKELEY.EDU!dillon
From: dillon@POSTGRES.BERKELEY.EDU (Matt Dillon)
Newsgroups: comp.sys.amiga.tech
Subject: Proposal for new DOS calls
Message-ID: <8811072046.AA04999@postgres.Berkeley.EDU>
Date: 7 Nov 88 20:46:48 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Lines: 110


	There are several lackings in DOS that make interactive handling of
file handles difficult.  For one, there is no way to determine whether data
is pending (e.g. via SER: AUX:, interactive PIPE: etc...) without calling
Read() or WaitForChar().  Neither of these methods are acceptable as
both will block or require busy waiting.  

	I propose the following additional calls.  Since these are in the
domain of DOS packets, you simply get an error if the DOS device does not
support them.  All calls would be implemented via ACTION_<blahblah> on
the packet level.  The actual assignment of id numbers is not pertainent at 
this point.

	fh = some file handle

	Note on Read() calls.  Since 0 is an acceptable return value when
a handle is set to non-blocking, -1 is used to indicate an EOF condition.
either -1 or 0 indicate an EOF condition if the handle is set to blocking.
Use IoErr() to determine whether it is an EOF or error.

				-Matt

mask = Capabilities(fh)

	Return a mask of capabilities provided by this file handle.  I.E.
	each bit is assigned to one of the calls below where a '1' indicates
	the call is implemented and a '0' indicates the call is not.  This
	is a quick way to ensure you can do what you want to do with the 
	handle.

bool = SetRBlockMode(fh, mode)

	0- return less than requested or 0 if no/little read data available
 (def)	1- block if no read data available
	2- (atomic non-blocking): either read everything or nothing.
	   i.e. if you request 30 bytes and only 20 are ready, the call
	   returns 0.

bool = SetWBlockMode(fh, mode)

	0- write less than requested or 0 if no/little buffer space available
	   for write.
 (def)	1- block until all data can be written
	2- (atomic non-blocking): either write everything or nothing.  i.e.
	   if you want to write 30 bytes and it can only write 20, the call
	   returns 0.

bool = SetRSignal(fh, signo, amount)

	-1 disables the function.  Otherwise, set the signal # that should
	occur when read data is available.  This signal is also set when
	a Read() call fails to completely empty the buffer.  The signal
	is also set if Read() is called but the other end closed/shutdown
	(i.e. an exception condition).  The signal is cleared otherwise.

	The minimum amount of data present in the read buffer before you
	get signaled is also specified.  If larger than the read buffer
	it is chopped to the read buffer.  You will get signaled if less
	than this amount is available only if the other end has sent an EOF
	(by closing the channel or shutting it down).

bool = SetWSignal(fh, signo, amount)

	-1 disables the function.  Otherwise, set the signal # that should
	occur when write buffer space is available.  This signal is also
	set when a Write() call does not exhaust the buffer space.  This
	signal is also set when a Write() fails due to the other end
	having closed or shutdown.  The signal is cleared otherwise.

	The amount of space available to write may be set.  If larger than
	the buffer size, it is chopped to the buffer size.

amnt = GetRDataReady(fh)

	Return the number of bytes ready to be read, -1 if no bytes remain
	and the other end closed or shutdown.  This also sets the RSignal
	if >0 or -1 is returned, clears it if 0 is returned.

amnt = GetWSpaceAvail(fh)

	Return the number of bytes that can be written without blocking,
	-1 if the other end closed or shutdown.  This also sets the WSignal
	if >0 or -1 is returned, clears it if 0 is returned.

amnt = SetWBufSize(fh, amount)

	Set the write buffer size, in bytes.  The actual buffer size is 
	returned and may be different then what you request.

	Default: depends on handler.  Normally you can ignore the return
	value unless you are doing atomic IO, in which case the buffer
	has to be at least as big as the largest block you intend to write.

amnt = SetRBufSize(fh, amount)

	Set the read buffer size, in bytes.  The actual buffer size is
	returned and may be different then what you request.

	Default: depends on handler.  Same restrictions apply as for 
	SetWBufSize().

bool = ShutDown(fh, how)

	Shutdown (effectively send an EOF or refuse receive data), how =

	0	nop
	1	disallow further reads
	2	disallow further writes (send EOF)
	3	both

	TRUE is returned if the call is implemented, FALSE if not.