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