#ifndef __Desk_OSBuffer_h
#define __Desk_OSBuffer_h

/*
These functions provide easy-to-use interfaces to buffer service
routines as decribed in PRMs 5a-213.

Thes buffer service routines allow one to deal with buffers via a
conventional function call without the overhead of calling a SWI. They
can also be called in USR, IRQ or SVC mode with interrupts disabled or
enabled.

The interface veneers provided here are all written in assembler, and
use 2 words of stack.

Note that currently only the Insert/RemoveByte/Block interface veneers
have been written. If you require the others, it should be
straightforward to write them yourself.

Note that this sub-library requires RISC OS 3.5 or later.
 */



typedef struct	{
	void*	id;
	void	(*serviceroutine)( void);
	void*	pw;
	}
	Desk_osbuffer_block;
/*
Created by Desk_OSBuffer_Init.
 */


Desk_osbuffer_block*	Desk_OSBuffer_Init( int bufferhandle);
/*
Calls Buffer_InternalInfo for the specified buffer handle, and returns a
suitably malloced and set-up Desk_osbuffer_block.

Pass this block to any of Desk_OSBuffer_InsertByte,
Desk_OSBuffer_InsertBlock, Desk_OSBuffer_RemoveByte,
Desk_OSBuffer_RemoveBlock, Desk_OSBuffer_ExamineByte,
Desk_OSBuffer_ExamineBlock, Desk_OSBuffer_ReturnUsedSpace,
Desk_OSBuffer_ReturnFreeSpace, Desk_OSBuffer_PurgeBuffer,
Desk_OSBuffer_NextFilledBlock.

Call Desk_OSBuffer_Final when you have finished with the osbuffer.
 */

void	Desk_OSBuffer_Final( Desk_osbuffer_block* osbuffer);
/*
Frees osbuffer.
 */

int	Desk_OSBuffer_InsertByte( Desk_osbuffer_block* osbuffer, int byte);
/*
Returns non-zero if failed to insert (ie C set by service routine).
PRMs 5a-216.
 */

int	Desk_OSBuffer_InsertBlock( Desk_osbuffer_block* osbuffer, void* data, int numbytes);
/*
Returns numbytes not inserted (ie r3 on return from service routine).
PRMs 5a-216.
 */

int	Desk_OSBuffer_RemoveByte( Desk_osbuffer_block* osbuffer);
/*
Returns byte removed, or -1 if failed.
PRMs 5a-217.
 */

int	Desk_OSBuffer_RemoveBlock( Desk_osbuffer_block* osbuffer, void* buffer, int numbytes);
/*
Returns number of bytes not removed (ie r3 on return from service routine).
PRMs 5a-217.
 */

int	Desk_OSBuffer_ExamineByte( Desk_osbuffer_block* osbuffer);
/*
Returns next byte to be removed, or -1 if failed.
PRMs 5a-218.
 */

int	Desk_OSBuffer_ExamineBlock( Desk_osbuffer_block* osbuffer, void* buffer, int numbytes);
/*
Returns number of bytes not transferred.
 */

int	Desk_OSBuffer_ReturnUsedSpace( Desk_osbuffer_block* osbuffer);
/*
Returns number of bytes in the specified buffer.
PRMs 5a-219.
 */

int	Desk_OSBuffer_ReturnFreeSpace( Desk_osbuffer_block* osbuffer);
/*
Returns number of fre bytes in the specified buffer.
PRMs 5a-219.
 */

void	Desk_OSBuffer_PurgeBuffer( Desk_osbuffer_block* osbuffer);
/*
Purges all data in the specified buffer.
PRMs 5a-219.
 */

void*	Desk_OSBuffer_NextFilledBlock( Desk_osbuffer_block* osbuffer, int* numbytes);
/*
On exit, returns r2 from the service routine. *numbytes contains r3 from
service routine. If buffer is empy (ie C=1 on exit from service
routine), *numbytes will be 0, and will return NULL. PRMs 5a-220.
 */


#endif
