home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / Code < prev    next >
Text File  |  1997-02-21  |  13KB  |  389 lines
  1. File        : Code
  2. Date        : 21-Feb-97
  3. Author      : © A.Thoukydides, 1995, 1996, 1997
  4. Description : Description of the support for writing extra PC side utilities
  5.               using the supplied files.
  6.  
  7.  
  8. INTRODUCTION
  9.  
  10. The ARMEdit suite has been designed to allow other software to developers to
  11. add extra utilities to those supplied; all of the necessary files are
  12. included in the standard distribution.
  13.  
  14. The PC side files were prepared using Borland Turbo C++ version 3.0 for DOS,
  15. but they use C linkage and should be compatible with other compilers. Veneers
  16. to allow the ARMEdit SWIs to be called from C/C++ were assembled using Acorn
  17. ObjAsm version 3.06, and should be used in conjunction with Jonathan
  18. Coxhead's OSLib.
  19.  
  20.  
  21. FILES INCLUDED
  22.  
  23. The following header files are included in this distribution for use on the
  24. PC side:
  25.  
  26.     ARMFILE.H   High level routines for copying individual files between
  27.                 DOS and RISC OS. These perform the core of the GETFILE and
  28.                 PUTFILE utilities. They provide an easy way of transferring
  29.                 large amounts of data between the two environments.
  30.  
  31.     CLI.H       Functions to call RISC OS *commands with different levels of
  32.                 input and output redirection.
  33.                 
  34.     SWI.H       This provides a single function to call a RISC OS SWI by name
  35.                 from the PC. This should not normally be used, because it is
  36.                 very inefficient, but is useful when prototyping code.
  37.     
  38.     TALK.H      This is the main interface to the RISC OS services. It
  39.                 provides routines for performing generally useful functions,
  40.                 e.g. allocating and deallocating memory, 
  41.  
  42. All of the required object files to be linked with are included in a single
  43. library file:
  44.  
  45.     ARMEDIT.LIB
  46.  
  47. The following header files are included for use under RISC OS:
  48.  
  49.     h.armeditswi    C interface functions to all of the SWIs provided by the
  50.                     ARMEdit module. See Docs.Module for details of all the
  51.                     SWIs.
  52.  
  53. A single object file is included containing the assembled veneers:
  54.  
  55.     o.armeditswi
  56.  
  57.  
  58. FUNCTIONS PROVIDED
  59.  
  60. The following sections give brief descriptions of the functions provided in
  61. each header file. For more details read the comments in the header files
  62. themselves.
  63.  
  64. The provided services should allow almost any operation to be performed.
  65. However, please get in touch if extra features would be useful - if they are
  66. sufficiently general they may get added in a future release of the ARMEdit
  67. module.
  68.  
  69.  
  70. ARMFILE.H
  71.  
  72. armfile_copy_dos_riscos
  73.  
  74.     Copy a file from RISC OS to DOS.
  75.     
  76.  
  77. armfile_copy_riscos_dos
  78.  
  79.     Copy a file from DOS to RISC OS.
  80.     
  81.  
  82. armfile_translate_dos_riscos
  83.  
  84.     Convert a DOS filename into a RISC OS equivalent. This performs
  85.     substitutions similar to those performed by DOSFS.
  86.  
  87.  
  88. armfile_translate_riscos_dos
  89.  
  90.     Convert a RISC OS filename into a DOS equivalent. This performs the
  91.     opposite operation to armfile_translate_dos_riscos.
  92.  
  93. armfile_temporary
  94.  
  95.     Generate the filename for a temporary RISC OS file, and ensure it is
  96.     deleted before the program exits.
  97.  
  98. armfile_create_dir
  99.  
  100.     Create a RISC OS directory.
  101.  
  102.  
  103. CLI.H
  104.  
  105. cli_simple
  106.  
  107.     A simple *command interface. If output redirection is required then it
  108.     is performed via a file.
  109.     
  110.  
  111. cli_redir
  112.  
  113.     A more comprehensive *command interface. Both input and ouput can be
  114.     redirected to/from any DOS stream or file. Special action is taken if
  115.     the streams correspond to the keyboard or screen.
  116.     
  117.  
  118. SWI.H
  119.  
  120. swi_swi
  121.  
  122.     Call a specified RISC OS SWI by its name. As mentioned above this is a
  123.     very inefficient operation to perform, so should normally only be used
  124.     during development stages of new software.
  125.  
  126.  
  127. TALK.H
  128.  
  129. talk_swi
  130.  
  131.     Call a RISC OS SWI by number. It should be remembered that the SWI can
  132.     not read PC memory directly; the required data must be copied using the
  133.     other functions provided in the talk module.
  134.  
  135.  
  136. talk_read
  137.  
  138.     Read a block of RISC OS memory.
  139.  
  140.  
  141. talk_write
  142.  
  143.     Write a block of RISC OS memory.
  144.  
  145.  
  146. talk_malloc
  147.  
  148.     Claimed the specified amount of RISC OS memory. The memory should be
  149.     released using talk_free. However, it will automatically be freed when
  150.     the PC card is either reset or quit; ensuring that all claimed memory
  151.     is eventually deallocated even if the PC software terminates abnormally.
  152.  
  153.  
  154. talk_free
  155.  
  156.     Free a block of memory previously claimed using talk_malloc.
  157.  
  158.  
  159. talk_ext_to_filetype
  160.  
  161.     Convert a DOS file extension into a RISC OS filetype. This uses the
  162.     list of mappings set by the DOSMap command. See Docs.Module for more
  163.     details.
  164.  
  165.  
  166. talk_filetype_to_ext
  167.  
  168.     Convert a RISC OS filetype into a DOS file extension. This uses the
  169.     list of mappings set by the DOSMap command. See Docs.Module for more
  170.     details.
  171.  
  172.  
  173. talk_file_open
  174.  
  175.     Open a RISC OS file. It is possible to specify that the file should
  176.     automatically be deleted when it is closed; useful for temporary files.
  177.     The file should be closed using talk_file_close. However, it will
  178.     automatically be closed when the PC card is either reset or quit;
  179.     ensuring that all files are eventually closed (and deleted if required)
  180.     even if the PC software terminates abnormally.
  181.  
  182.  
  183. talk_file_close
  184.  
  185.     Close a RISC OS file previously opened using talk_file_open.
  186.  
  187.  
  188. talk_file_read
  189.  
  190.     Read a block of memory from a RISC OS file.
  191.     
  192.  
  193. talk_file_write
  194.  
  195.     Write a block of memory to a RISC OS file.
  196.  
  197.  
  198. talk_comms_start
  199.  
  200.     Register a communications client.
  201.  
  202.  
  203. talk_comms_end
  204.  
  205.     Deregister a communications client.
  206.     
  207.  
  208. talk_comms_tx
  209.  
  210.     Transmit a message to another client.
  211.     
  212.  
  213. talk_comms_rx
  214.  
  215.     Receive a message from another client.
  216.  
  217.  
  218. talk_date_to_dos
  219.  
  220.     Convert a date and time from RISC OS to DOS format.
  221.     
  222.  
  223. talk_date_to_riscos
  224.  
  225.     Convert a date and time from DOS to RISC OS format.
  226.     
  227.  
  228. talk_comms_reply
  229.  
  230.     Reply to a message from another client.
  231.  
  232. talk_faster
  233.  
  234.     Disable multitasking for faster operations.
  235.  
  236. talk_temporary
  237.  
  238.     Generate a unique filename for a temporary RISC OS file.
  239.  
  240.  
  241. MESSAGE PASSING
  242.  
  243. The ARMEdit module provides a general method for PC software to communicate
  244. with RISC OS applications or modules. The system is intentionally left
  245. simple; many aspects are left to users of the protocol to implement as
  246. required, e.g. detection and handling of problems, and the format and useage
  247. of different messages.
  248.  
  249. The system allows multiple simultaneous clients, both under RISC OS and on
  250. the PC. This makes it suitable for use in multi-tasking (or task
  251. switching) environments such as Windows. Each client has a 4 byte ID which is
  252. preallocated (by me, on request) and a 4 byte dynamically allocated (by the
  253. ARMEdit module) handle. There are two special IDs: ID 0 is always used by PC
  254. software, and ID 1 is used to broadcast messages to all clients (this is
  255. explained in more detail below). Other IDs are allocated to different
  256. services being provided. If a program provides a number of distinct services,
  257. or if required for some other reason, it may have more than one ID. The range
  258. of IDs 2 to 255 may be freely used for development purposes, but must not be
  259. used by distributed software.
  260.  
  261. When messages are sent to ID 1 they are passed to all clients which accept
  262. messages from the ARMEdit module (as specified when the clients register).
  263. This is normally only used for a few specific messages (described in the
  264. next section) which are useful to many clients. Other clients should not use
  265. this facility except under special circumstances.
  266.  
  267. It is intended that each client provides a number of related services for a
  268. particular ID, but it is up to the authors of clients to decide how the
  269. message contents should be used. However, it is recommended that a service
  270. selector field is placed at the start of all messages.
  271.  
  272. Each client has a message buffer (allocated by the ARMEdit module) used to
  273. transmit messages. This buffer is of a fixed size (1kB) and can only contain
  274. a single message. Attempting to send a message with one already in the buffer
  275. overwrites the earlier message, regardless of how many clients it has been
  276. delivered to.
  277.  
  278. To enable easy impleme