home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / Talk < prev   
Text File  |  1997-02-21  |  4KB  |  147 lines
  1. File        : Talk
  2. Date        : 21-Feb-97
  3. Author      : © A.Thoukydides, 1996, 1997
  4. Description : ARMEdit messages supported by the !ARMEdit front-end.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. The !ARMEdit front-end supports several messages used by PC software. The
  10. messages are arranged in pairs: code running on the PC card send a message,
  11. and the front-end sends an acknowledgement (with the same reason code). No
  12. messages are sent from the front-end unrequested.
  13.  
  14. All of the messages use the ID 256.
  15.  
  16.  
  17. MSG_ARMEDIT_FIND
  18.  
  19.     Check whether the front-end is running.
  20.     
  21.     Data sent:
  22.  
  23.         Offset  Size    Description
  24.     
  25.         0       4       Reason code = &00000000.
  26.     
  27.     Data returned:
  28.     
  29.         Offset  Size    Description
  30.         
  31.         0       4       Reason code = &00000000.
  32.  
  33.     The PC software sends this message to ID 256 to find the handle of the
  34.     front-end software. A timeout should be used to detect whether the
  35.     message has been delivered.
  36.     
  37.     All future messages should use the message handle.
  38.  
  39.  
  40. MSG_ARMEDIT_START
  41.  
  42.     Start an external edit.
  43.     
  44.     Data sent:
  45.     
  46.         Offset  Size    Description
  47.         
  48.         0       4       Reason code = &00000001.
  49.         4       4       Byte offset of initial cursor position.
  50.         8       20      Null terminated DOS leaf name of file to edit.
  51.         28      256     Null terminated name of RISC OS file to edit.
  52.     
  53.     Data returned:
  54.     
  55.         Offset  Size    Description
  56.         
  57.         0       4       Reason code = &00000001.
  58.         4       4       Handle for this edit.
  59.  
  60.     This message is used to start an external edit. The leaf name is used for
  61.     display purposes - only the RISC OS name is used to access the file
  62.     (which must exist when the message is sent).
  63.     
  64.     No status is returned by this message. Use MSG_ARMEDIT_POLL to check the
  65.     state of the edit.
  66.     
  67.     A unique handle is returned for this file. This handle should be used
  68.     when polling the status of the edit.
  69.  
  70.  
  71. MSG_ARMEDIT_POLL
  72.  
  73.     Poll the status of the external edit.
  74.     
  75.     Data sent:
  76.     
  77.         Offset  Size    Description
  78.         
  79.         0       4       Reason code = &00000002.
  80.         4       4       Handle of edit to poll.
  81.         8       4       Flags:
  82.                             bit 0   Set to retrieve data.
  83.                             bit 1   Set to end external edit.
  84.                             bit 2   Set to mark file as safely saved.
  85.     
  86.     Data returned:
  87.     
  88.         Offset  Size    Description
  89.         
  90.         0       4       Reason code = &00000002.
  91.         4       4       Flags:
  92.                             bit 0   Set if file modified since last poll.
  93.                             bit 1   Set if external edit aborted.
  94.  
  95.     This message is used to check or update the status of an external edit.
  96.     The input flags allow the file to be retrieved from the editor, or to
  97.     abandon the edit. It is also possible to mark the edit as safely saved
  98.     after it has been saved by the editor.
  99.     
  100.     If a request has been made to retrieve a file then the returned flags
  101.     should be checked until the modified flag is set.
  102.     
  103.     If the returned flags indicate that the edit has been aborted then no
  104.     more messages should be sent for this edit.
  105.  
  106.  
  107. MSG_ARMEDIT_SAVEAS
  108.  
  109.     Display a Save As window for a specified file.
  110.     
  111.     Data sent:
  112.     
  113.         Offset  Size    Description
  114.         
  115.         0       4       Reason code = &00000003.
  116.         4       256     Null terminated name of RISC OS file to save.
  117.         260     256     Null terminated suggested name of file to save.
  118.     
  119.     Data returned:
  120.     
  121.         Offset  Size    Description
  122.         
  123.         0       4       Reason code = &00000003.
  124.  
  125.     Allow a file to be saved under a user specifiable name. This is intended
  126.     for use by the PUTFILE command when no destination is specified. The
  127.     file is deleted when it has either been saved, or when the user has
  128.     cancelled the operation. No method for determining the success or
  129.     failure of the operation is provided.
  130.     
  131.  
  132. THINGS TO DO
  133.  
  134. The following are changes that may be made to the HPC services sometime in
  135. the future.
  136.  
  137.     Support execution of commands in a TaskWindow from the OSCLI command.
  138.  
  139.  
  140. VERSION HISTORY
  141.  
  142. 0.00 (10-Sep-96)    Original development version.
  143.  
  144. 0.01 (05-Feb-97)    Cursor position in external edits can be specified.
  145.                     Added Save As window support.
  146.  
  147. 1.03 (21-Feb-97)    First official release version.