@database "clipboard"
@master "AMIDEV:NDK/Autodocs/clipboard.doc"

@Node Main "clipboard.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" CBD_CHANGEHOOK " Link "CBD_CHANGEHOOK"}
    @{" CBD_CURRENTREADID " Link "CBD_CURRENTREADID"}
    @{" CBD_CURRENTWRITEID " Link "CBD_CURRENTWRITEID"}
    @{" CBD_POST " Link "CBD_POST"}
    @{" CMD_READ " Link "CMD_READ"}
    @{" CMD_UPDATE " Link "CMD_UPDATE"}
    @{" CMD_WRITE " Link "CMD_WRITE"}
@EndNode

@Node "CBD_CHANGEHOOK" "clipboard.device/CBD_CHANGEHOOK"

@{b}   NAME@{ub}
	CBD_CHANGEHOOK -- Add or remove a clip change hook

@{b}   FUNCTION@{ub}
	CBD_CHANGEHOOK allows specification of a hook to be called
	when the data on the clipboard has changed.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CBD_CHANGEHOOK
	io_Length -     0 to remove, 1 to install this hook
	io_Data -       struct @{"Hook" Link "INCLUDE:utility/hooks.h/Main" 26} *, the clip change hook

@{b}   HOOK ENVIRONMENT@{ub}
       hook message - a @{"ClipHookMsg" Link "INCLUDE:devices/clipboard.h/Main" 61}, as defined in @{"devices/clipboard.h" Link "INCLUDE:devices/clipboard.h/Main" 0}
           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

@EndNode

@Node "CBD_CURRENTREADID" "clipboard.device/CBD_CURRENTREADID"

@{b}   NAME@{ub}
	CBD_CURRENTREADID - Determine the current read identifier.

@{b}   FUNCTION@{ub}
	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.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CBD_CURRENTREADID

@{b}   RESULTS@{ub}
	io_ClipID	the ClipID of the current write is set

@EndNode

@Node "CBD_CURRENTWRITEID" "clipboard.device/CBD_CURRENTWRITEID"

@{b}   NAME@{ub}
	CBD_CURRENTWRITEID -- Determine the current write identifier.

@{b}   FUNCTION@{ub}
	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.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CBD_CURRENTWRITEID

@{b}   RESULTS@{ub}
	io_ClipID	the ClipID of the current write is set

@{b}   BUGS@{ub}
       This information is less helpful than it might seem because any
       other task may write to the clipboard at any time.

@EndNode

@Node "CBD_POST" "clipboard.device/CBD_POST"

@{b}   NAME@{ub}
	CBD_POST -- Post availability of a clip to the clipboard.

@{b}   FUNCTION@{ub}
	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" Link "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" Link "CBD_CURRENTWRITEID"} command.  If the current write io_ClipID is
	greater, there is no need to satisfy the post.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CBD_POST
	io_Data		pointer to satisfy message port
	io_ClipID	zero

@{b}   RESULTS@{ub}
	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


@EndNode

@Node "CMD_READ" "clipboard.device/CMD_READ"

@{b}   NAME@{ub}
	CMD_READ -- @{"Read" Link "dos/Read()"} from a clip on the clipboard.

@{b}   FUNCTION@{ub}
	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.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/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

@{b}   RESULTS@{ub}
	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

@EndNode

@Node "CMD_UPDATE" "clipboard.device/CMD_UPDATE"

@{b}   NAME@{ub}
	CMD_UPDATE -- Terminate the writing of a clip to the clipboard.

@{b}   FUNCTION@{ub}
	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.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CMD_UPDATE
	io_ClipID	the ClipID of the write

@{b}   RESULTS@{ub}
	io_Error	non-zero if an error occurred

@EndNode

@Node "CMD_WRITE" "clipboard.device/CMD_WRITE"

@{b}   NAME@{ub}
	CMD_WRITE -- @{"Write" Link "dos/Write()"} to a clip on the clipboard.

@{b}   FUNCTION@{ub}
	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" Link "INCLUDE:devices/clipboard.h/Main" 55} for a pending
	post, then the io_ClipID returned by the @{"CBD_POST" Link "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.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set up
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/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

@{b}   RESULTS@{ub}
	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

@EndNode