home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / clipboard.doc < prev    next >
Encoding:
Text File  |  1992-09-12  |  7.0 KB  |  224 lines
  1. TABLE OF CONTENTS
  2.  
  3. clipboard.device/CBD_POST
  4. clipboard.device/CBD_CLIPREADID
  5. clipboard.device/CBD_CLIPWRITEID
  6. clipboard.device/CMD_READ
  7. clipboard.device/CMD_RESET
  8. clipboard.device/CMD_UPDATE
  9. clipboard.device/CMD_WRITE
  10.  
  11.  
  12. clipboard.device/CBD_POST                             clipboard.device/CBD_POST
  13.  
  14.    NAME
  15.     CBD_POST - post clip to clipboard
  16.  
  17.    FUNCTION
  18.     Indicate to the clipboard device that data is available for
  19.     use by accessors of the clipboard.  This is intended to be
  20.     used when a cut is large, in a private data format, and/or
  21.     changing frequently, and it thus makes sense to avoid
  22.     converting it to an IFF form and writing it to the clipboard
  23.     unless another application wants it.  The post provides a
  24.     message port to which the clipboard device will send a satisfy
  25.     message if the data is required.
  26.  
  27.     If the satisfy message is received, the write associated with
  28.     the post must be performed.  The act of writing the clip
  29.     indicates that the message has been received: it may then be
  30.     re-used by the clipboard device, and so must actually be
  31.     removed from the satisfy message port so that the port is not
  32.     corrupted.
  33.  
  34.     If the application wishes to determine if a post it has
  35.     performed is still the current clip, it should check the
  36.     post's io_ClipID with that returned by the CBD_CLIPREADID
  37.     command.  If ClipID is greater, the clip is not still
  38.     current.
  39.     
  40.     If an application has a pending post and wishes to determine
  41.     if it should satisfy it (e.g. before it exits), it should
  42.     check the post's io_ClipID with that returned by the
  43.     CBD_CLIPWRITEID command.  If CurrentWriteID is greater, there
  44.     is no need to satisfy the post.
  45.  
  46.    IO REQUEST
  47.     io_Message    mn_ReplyPort set up
  48.     io_Device    preset by OpenDevice
  49.     io_Unit        preset by OpenDevice
  50.     io_Command    CBD_POST
  51.     io_Data        pointer to satisfy message port
  52.     io_ClipID    zero
  53.  
  54.    RESULTS
  55.     io_Error    non-zero if an error occurred
  56.     io_ClipID    the clip ID assigned to this post, to be used
  57.             in the write command if this is satisfied
  58.  
  59.  
  60.  
  61. clipboard.device/CBD_CLIPREADID                 clipboard.device/CBD_CLIPREADID
  62.  
  63.    NAME
  64.     CBD_CLIPREADID - determine the current read identifier.
  65.  
  66.    FUNCTION
  67.     CBD_CLIPREADID fills the io_ClipID with a clip identifier that
  68.     can be compared with that of a post command: if greater than
  69.     the post identifier then the post data held privately by an
  70.     application is not valid for its own pasting.
  71.  
  72.    IO REQUEST
  73.     io_Message    mn_ReplyPort set up
  74.     io_Device    preset by OpenDevice
  75.     io_Unit        preset by OpenDevice
  76.     io_Command    CBD_CLIPREADID
  77.  
  78.  
  79.     io_ClipID    the ClipID of the current write is set
  80.  
  81.  
  82. clipboard.device/CBD_CLIPWRITEID               clipboard.device/CBD_CLIPWRITEID
  83.  
  84.    NAME
  85.     CBD_CLIPWRITEID - determine the current write identifier.
  86.  
  87.    FUNCTION
  88.     CBD_CLIPWRITEID fills the io_ClipID with a clip identifier that
  89.     can be compared with that of a post command: if greater than
  90.     the post identifier then the post is obsolete and need never
  91.     be satisfied.
  92.  
  93.    IO REQUEST
  94.     io_Message    mn_ReplyPort set up
  95.     io_Device    preset by OpenDevice
  96.     io_Unit        preset by OpenDevice
  97.     io_Command    CBD_CLIPWRITEID
  98.  
  99.  
  100.     io_ClipID    the ClipID of the current write is set
  101.  
  102.  
  103. clipboard.device/CMD_READ                             clipboard.device/CMD_READ
  104.  
  105.    NAME
  106.     CMD_READ - read clip from clipboard
  107.  
  108.    FUNCTION
  109.     The read function serves two purposes.
  110.  
  111.     When io_Offset is within the clip, this acts as a normal read
  112.     request, and io_Data is filled with data from the clipboard.
  113.     The first read request should have a zero io_ClipID, which
  114.     will be filled with the ID assigned for this read.  Normal
  115.     sequential access from the beginning of the clip is achieved
  116.     by setting io_Offset to zero for the first read, then leaving
  117.     it untouched for subsequent reads.  If io_Data is null, then
  118.     io_Offset is incremented by io_Actual as if io_Length bytes
  119.     had been read: this is useful to skip to the end of file
  120.     by using a huge io_Length.
  121.  
  122.     When io_Offset is beyond the end of the clip, this acts as a
  123.     signal to the clipboard device that the application is
  124.     through reading this clip.  Realize that while an application
  125.     is in the middle of reading a clip, any attempts to write new
  126.     data to the clipboard are held off.  This read past the end
  127.     of file indicates that those operations may now be initiated.
  128.  
  129.    IO REQUEST
  130.     io_Message    mn_ReplyPort set up
  131.     io_Device    preset by OpenDevice
  132.     io_Unit        preset by OpenDevice
  133.     io_Command    CMD_READ
  134.     io_Length    number of bytes to put in data buffer
  135.     io_Data        pointer to buffer of data to fill, or null to
  136.             skip over data
  137.     io_Offset    byte offset of data to read
  138.     io_ClipID    zero if this is the initial read
  139.  
  140.    RESULTS
  141.     io_Error    non-zero if an error occurred
  142.     io_Actual    filled with the actual number of bytes read
  143.     io_Data        (the buffer now has io_Actual bytes of data)
  144.     io_Offset    updated to next read position, which is
  145.             beyond EOF if io_Actual != io_Length
  146.     io_ClipID    the clip ID assigned to this read: do not
  147.             alter for subsequent reads
  148.  
  149.  
  150. clipboard.device/CMD_RESET                           clipboard.device/CMD_RESET
  151.  
  152.    NAME
  153.     CMD_RESET - reset the clipboard
  154.  
  155.    FUNCTION
  156.     CMD_RESET resets the clipboard device without destroying handles
  157.     to the open device.
  158.  
  159.    IO REQUEST
  160.     io_Message    mn_ReplyPort set up
  161.     io_Device    preset by OpenDevice
  162.     io_Command    CMD_RESET
  163.     io_Flags    IOB_QUICK set if quick I/O is possible
  164.  
  165.  
  166. clipboard.device/CMD_UPDATE                         clipboard.device/CMD_UPDATE
  167.  
  168.    NAME
  169.     CMD_UPDATE - terminate the writing of a cut to the clipboard
  170.  
  171.    FUNCTION
  172.     Indicate to the clipboard that the previous write commands are
  173.     complete and can be used for any pending pastes (reads).  This
  174.     command cannot be issued while any of the write commands are
  175.     pending.
  176.  
  177.    IO REQUEST
  178.     io_Message    mn_ReplyPort set up
  179.     io_Device    preset by OpenDevice
  180.     io_Unit        preset by OpenDevice
  181.     io_Command    CMD_UPDATE
  182.     io_ClipID    the ClipID of the write
  183.  
  184.    RESULTS
  185.     io_Error    non-zero if an error occurred
  186.  
  187.  
  188. clipboard.device/CMD_WRITE                           clipboard.device/CMD_WRITE
  189.  
  190.    NAME
  191.     CMD_WRITE - write clip to clipboard
  192.  
  193.    FUNCTION
  194.     This command writes data to the clipboard.  This data can be
  195.     provided sequentially by clearing io_Offset for the initial
  196.     write, and using the incremented value unaltered for
  197.     subsequent writes.  If io_Offset is ever beyond the current
  198.     clip size, the clip is padded with zeros.
  199.  
  200.     If this write is in response to a SatisfyMsg for a pending
  201.     post, then the io_ClipID returned by the Post command must
  202.     be used.  Otherwise, a new ID is obtained by clearing the
  203.     io_ClipID for the first write.  Subsequent writes must not
  204.     alter the io_ClipID.
  205.  
  206.    IO REQUEST
  207.     io_Message    mn_ReplyPort set up
  208.     io_Device    preset by OpenDevice
  209.     io_Unit        preset by OpenDevice
  210.     io_Command    CMD_WRITE
  211.     io_Length    number of bytes from io_Data to write
  212.     io_Data        pointer to block of data to write
  213.     io_Offset    usually zero if this is the initial write
  214.     io_ClipID    zero if this is the initial write, ClipID of
  215.             the Post if this is to satisfy a post
  216.  
  217.    RESULTS
  218.     io_Error    non-zero if an error occurred
  219.     io_Actual    filled with the actual number of bytes written
  220.     io_Offset    updated to next write position
  221.     io_ClipID    the clip ID assigned to this write: do not
  222.             alter for subsequent writes
  223.  
  224.