TABLE OF CONTENTS

clipboard.device/CBD_CHANGEHOOK
clipboard.device/CBD_CURRENTREADID
clipboard.device/CBD_CURRENTWRITEID
clipboard.device/CBD_POST
clipboard.device/CMD_READ
clipboard.device/CMD_UPDATE
clipboard.device/CMD_WRITE
clipboard.device/CBD_CHANGEHOOK               clipboard.device/CBD_CHANGEHOOK

   NAME
	CBD_CHANGEHOOK -- Add or remove a clip change hook

   FUNCTION
	CBD_CHANGEHOOK allows specification of a hook to be called
	when the data on the clipboard has changed.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CBD_CHANGEHOOK
	io_Length -     0 to remove, 1 to install this hook
	io_Data -       struct Hook *, the clip change hook

   HOOK ENVIRONMENT
       hook message - a ClipHookMsg, as defined in devices/clipboard.h
           chm_Type - 0, indicating that the message has the
               following fields:
           chm_ClipID - the clip ID of the clip triggering the change
       hook object - io_Unit

clipboard.device/CBD_CURRENTREADID         clipboard.device/CBD_CURRENTREADID

   NAME
	CBD_CURRENTREADID - Determine the current read identifier.

   FUNCTION
	CBD_CURRENTREADID fills the io_ClipID with a clip identifier that
	can be compared with that of a post command: if greater than
	the post identifier then the post data held privately by an
	application is not valid for its own pasting.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CBD_CURRENTREADID

   RESULTS
	io_ClipID	the ClipID of the current write is set

clipboard.device/CBD_CURRENTWRITEID       clipboard.device/CBD_CURRENTWRITEID

   NAME
	CBD_CURRENTWRITEID -- Determine the current write identifier.

   FUNCTION
	CBD_CURRENTWRITEID fills the io_ClipID with a clip identifier that
	can be compared with that of a post command: if greater than
	the post identifier then the post is obsolete and need never
	be satisfied.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CBD_CURRENTWRITEID

   RESULTS
	io_ClipID	the ClipID of the current write is set

clipboard.device/CBD_POST                           clipboard.device/CBD_POST

   NAME
	CBD_POST -- Post availability of a clip to the clipboard.

   FUNCTION
	Indicate to the clipboard device that data is available for
	use by accessors of the clipboard.  This is intended to be
	used when a cut is large, in a private data format, and/or
	changing frequently, and it thus makes sense to avoid
	converting it to an IFF form and writing it to the clipboard
	unless another application wants it.  The post provides a
	message port to which the clipboard device will send a satisfy
	message if the data is required.

	If the satisfy message is received, the write associated with
	the post must be performed.  The act of writing the clip
	indicates that the message has been received: it may then be
	re-used by the clipboard device, and so must actually be
	removed from the satisfy message port so that the port is not
	corrupted.

	If the application wishes to determine if a post it has
	performed is still the current clip, it should check the
	post's io_ClipID with that returned by the CBD_CURRENTREADID
	command.  If the current read io_ClipID is greater, the clip
	is not still current.

	If an application has a pending post and wishes to determine
	if it should satisfy it (e.g. before it exits), it should
	check the post's io_ClipID with that returned by the
	CBD_CURRENTWRITEID command.  If the current write io_ClipID is
	greater, there is no need to satisfy the post.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CBD_POST
	io_Data		pointer to satisfy message port
	io_ClipID	zero

   RESULTS
	io_Error	non-zero if an error occurred
	io_ClipID	the clip ID assigned to this post, to be used
			in the write command if this is satisfied


clipboard.device/CMD_READ                           clipboard.device/CMD_READ

   NAME
	CMD_READ -- Read from a clip on the clipboard.

   FUNCTION
	The read function serves two purposes.

	When io_Offset is within the clip, this acts as a normal read
	request, and io_Data is filled with data from the clipboard.
	The first read request should have a zero io_ClipID, which
	will be filled with the ID assigned for this read.  Normal
	sequential access from the beginning of the clip is achieved
	by setting io_Offset to zero for the first read, then leaving
	it untouched for subsequent reads.  If io_Data is null, then
	io_Offset is incremented by io_Actual as if io_Length bytes
	had been read: this is useful to skip to the end of file
	by using a huge io_Length.

	When io_Offset is beyond the end of the clip, this acts as a
	signal to the clipboard device that the application is
	through reading this clip.  Realize that while an application
	is in the middle of reading a clip, any attempts to write new
	data to the clipboard are held off.  This read past the end
	of file indicates that those operations may now be initiated.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CMD_READ
	io_Length	number of bytes to put in data buffer
	io_Data		pointer to buffer of data to fill, or null to
			skip over data
	io_Offset	byte offset of data to read
	io_ClipID	zero if this is the initial read

   RESULTS
	io_Error	non-zero if an error occurred
	io_Actual	filled with the actual number of bytes read
	io_Data		(the buffer now has io_Actual bytes of data)
	io_Offset	updated to next read position, which is
			beyond EOF if io_Actual != io_Length
	io_ClipID	the clip ID assigned to this read: do not
			alter for subsequent reads

clipboard.device/CMD_UPDATE                       clipboard.device/CMD_UPDATE

   NAME
	CMD_UPDATE -- Terminate the writing of a clip to the clipboard.

   FUNCTION
	Indicate to the clipboard that the previous write commands are
	complete and can be used for any pending pastes (reads).  This
	command cannot be issued while any of the write commands are
	pending.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CMD_UPDATE
	io_ClipID	the ClipID of the write

   RESULTS
	io_Error	non-zero if an error occurred

clipboard.device/CMD_WRITE                         clipboard.device/CMD_WRITE

   NAME
	CMD_WRITE -- Write to a clip on the clipboard.

   FUNCTION
	This command writes data to the clipboard.  This data can be
	provided sequentially by clearing io_Offset for the initial
	write, and using the incremented value unaltered for
	subsequent writes.  If io_Offset is ever beyond the current
	clip size, the clip is padded with zeros.

	If this write is in response to a SatisfyMsg for a pending
	post, then the io_ClipID returned by the CBD_POST command must
	be used.  Otherwise, a new ID is obtained by clearing the
	io_ClipID for the first write.  Subsequent writes must not
	alter the io_ClipID.

   IO REQUEST
	io_Message	mn_ReplyPort set up
	io_Device	preset by OpenDevice
	io_Unit		preset by OpenDevice
	io_Command	CMD_WRITE
	io_Length	number of bytes from io_Data to write
	io_Data		pointer to block of data to write
	io_Offset	usually zero if this is the initial write
	io_ClipID	zero if this is the initial write, ClipID of
			the Post if this is to satisfy a post

   RESULTS
	io_Error	non-zero if an error occurred
	io_Actual	filled with the actual number of bytes written
	io_Offset	updated to next write position
	io_ClipID	the clip ID assigned to this write: do not
			alter for subsequent writes