home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsa / armedit / Docs / Code next >
Encoding:
Text File  |  1996-01-12  |  9.7 KB  |  305 lines
  1. File        : Code
  2. Date        : 12-Jan-96
  3. Author      : © A.Thoukydides, 1995, 1996
  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. These files were prepared using
  13. Turbo C++ version 3.0, but they use C linkage and should be compatible with
  14. other compilers.
  15.  
  16.  
  17. FILES INCLUDED
  18.  
  19. The following header files are included in this distribution:
  20.  
  21.     ARMFILE.H   High level routines for copying individual files between
  22.                 DOS and RISC OS. These perform the core of the GETFILE and
  23.                 PUTFILE utilities. They provide an easy way of transferring
  24.                 large amounts of data between the two environments.
  25.                 
  26.     SWI.H       This provides a single function to call a RISC OS SWI by name
  27.                 from the PC. This should not normally be used, because it is
  28.                 very inefficient, but is useful when prototyping code.
  29.     
  30.     TALK.H      This is the main interface to the RISC OS services. It
  31.                 provides routines for performing generally useful functions,
  32.                 e.g. allocating and deallocating memory, 
  33.  
  34. The following object files need to be linked with any code produced:
  35.  
  36.     ARMFILE.OBJ
  37.     HPC.OBJ
  38.     SWI.OBJ
  39.     TALK.OBJ
  40.  
  41.  
  42. FUNCTIONS PROVIDED
  43.  
  44. The following sections give brief descriptions of the functions provided in
  45. each header file. For more details read the comments in the header files
  46. themselves.
  47.  
  48. The provided services should allow almost any operation to be performed.
  49. However, please get in touch if extra features would be useful - if they are
  50. sufficiently general they may get added in a future release of the ARMEdit
  51. module.
  52.  
  53.  
  54. ARMFILE.H
  55.  
  56. armfile_copy_dos_riscos
  57.  
  58.     Copy a file from RISC OS to DOS.
  59.     
  60.  
  61. armfile_copy_riscos_dos
  62.  
  63.     Copy a file from DOS to RISC OS.
  64.     
  65.  
  66. armfile_translate_dos_riscos
  67.  
  68.     Convert a DOS filename into a RISC OS equivalent. This performs
  69.     substitutions similar to those performed by DOSFS.
  70.  
  71.  
  72. armfile_translate_riscos_dos
  73.  
  74.     Convert a RISC OS filename into a DOS equivalent. This performs the
  75.     opposite operation to armfile_translate_dos_riscos.
  76.  
  77.  
  78.  
  79. SWI.H
  80.  
  81. swi_swi
  82.  
  83.     Call a specified RISC OS SWI by its name. As mentioned above this is a
  84.     very inefficient operation to perform, so should normally only be used
  85.     during development stages of new software.
  86.  
  87.  
  88. TALK.H
  89.  
  90. talk_swi
  91.  
  92.     Call a RISC OS SWI by number. It should be remembered that the SWI can
  93.     not read PC memory directly; the required data must be copied using the
  94.     other functions provided in the talk module.
  95.  
  96.  
  97. talk_read
  98.  
  99.     Read a block of RISC OS memory.
  100.  
  101.  
  102. talk_write
  103.  
  104.     Write a block of RISC OS memory.
  105.  
  106.  
  107. talk_malloc
  108.  
  109.     Claimed the specified amount of RISC OS memory. The memory should be
  110.     released using talk_free. However, it will automatically be freed when
  111.     the PC card is either reset or quit; ensuring that all claimed memory
  112.     is eventually deallocated even if the PC software terminates abnormally.
  113.  
  114.  
  115. talk_free
  116.  
  117.     Free a block of memory previously claimed using talk_malloc.
  118.  
  119.  
  120. talk_ext_to_filetype
  121.  
  122.     Convert a DOS file extension into a RISC OS filetype. This uses the
  123.     list of mappings set by the DOSMap command. See Docs.Module for more
  124.     details.
  125.  
  126.  
  127. talk_filetype_to_ext
  128.  
  129.     Convert a RISC OS filetype into a DOS file extension. This uses the
  130.     list of mappings set by the DOSMap command. See Docs.Module for more
  131.     details.
  132.  
  133.  
  134. talk_file_open
  135.  
  136.     Open a RISC OS file. It is possible to specify that the file should
  137.     automatically be deleted when it is closed; useful for temporary files.
  138.     The file should be closed using talk_file_close. However, it will
  139.     automatically be closed when the PC card is either reset or quit;
  140.     ensuring that all files are eventually closed (and deleted if required)
  141.     even if the PC software terminates abnormally.
  142.  
  143.  
  144. talk_file_close
  145.  
  146.     Close a RISC OS file previously opened using talk_file_open.
  147.  
  148.  
  149. talk_file_read
  150.  
  151.     Read a block of memory from a RISC OS file.
  152.     
  153.  
  154. talk_file_write
  155.  
  156.     Write a block of memory to a RISC OS file.
  157.  
  158.  
  159. talk_comms_start
  160.  
  161.     Register a communications client.
  162.  
  163.  
  164. talk_comms_end
  165.  
  166.     Deregister a communications client.
  167.     
  168.  
  169. talk_comms_tx
  170.  
  171.     Transmit a message to another client.
  172.     
  173.  
  174. talk_comms_rx
  175.  
  176.     Receive a message from another client.
  177.  
  178.  
  179. MESSAGE PASSING
  180.  
  181. The ARMEdit module provides a general method for PC software to communicate
  182. with RISC OS applications or modules. The system is intentionally left
  183. simple; many aspects are left to users of the protocol to implement as
  184. required, e.g. detection and handling of problems, and the format and useage
  185. of different messages.
  186.  
  187. The system allows multiple simultaneous clients, both under RISC OS and on
  188. the PC. This makes it suitable for use in multi-tasking (or task
  189. switching) environments such as Windows. Each client has a 4 byte ID which is
  190. preallocated (by me, on request) and a 4 byte dynamically allocated (by the
  191. ARMEdit module) handle. There are two special IDs: ID 0 is always used by PC
  192. software, and ID 1 is used to broadcast messages to all clients (this is
  193. explained in more detail below). Other IDs are allocated to different
  194. services being provided. If a program provides a number of distinct services,
  195. or if required for some other reason, it may have more than one ID. The range
  196. of IDs 2 to 255 may be freely used for development purposes, but must not be
  197. used by distributed software.
  198.  
  199. When messages are sent to ID 1 they are passed to all clients which accept
  200. messages from the ARMEdit module (as specified when the clients register).
  201. This is normally only used for a few specific messages (described in the
  202. next section) which are useful to many clients. Other clients should not use
  203. this facility except under special circumstances.
  204.  
  205. It is intended that each client provides a number of related services for a
  206. particular ID, but it is up to the authors of clients to decide how the
  207. message contents should be used. However, it is recommended that a service
  208. selector field is placed at the start of all messages.
  209.  
  210. Each client has a message buffer (allocated by the ARMEdit module) used to
  211. transmit messages. This buffer is of a fixed size (1kB) and can only contain
  212. a single message. Attempting to send a message with one already in the buffer
  213. overwrites the earlier message, regardless of how many clients it has been
  214. delivered to.
  215.  
  216. Large blocks of data should be transferred via files. This reduces the
  217. required memory usage and should speed up operations; to send a message from
  218. the PC to a WIMP task requires the PC front-end to be paged in and then the
  219. WIMP task to be subsequently paged in. However, transferring data to or from
  220. a file can all be done while the PC front-end is paged in.
  221.  
  222. When a message is sent it is necessary to detect and handle non-delivery.
  223. Unfortunately it is not easy to detect problems since the sender and receiver
  224. cannot (generally) be active at the same time, and it is necessary for the PC
  225. front-end to be multi-tasking in a window for communication to be possible
  226. between PC and RISC OS tasks.
  227.  
  228. The suggested approach is that after the message is sent, the program waits
  229. for a short time for a reply. If no reply is received then a message is
  230. displayed to the user prompting for the PC to be placed in multi-tasking mode
  231. and the relevant application to be started. The program should continue to
  232. poll for a reply until either successful or aborted by the user.
  233.  
  234. This can be simplified in many situations to simply waiting for a reply or
  235. for the user to abort the operation, especially after one successful
  236. communication has occurred.
  237.  
  238. If the PC front-end is either reset or quit then all registered PC clients
  239. are automatically deregistered, and any pending messages to or from them are
  240. discarded.
  241.  
  242.  
  243. STANDARD MESSAGES
  244.  
  245. The following messages are sent by the ARMEdit module to clients which
  246. request them. All of the messages are sent from client ID 1. Any unrecognised
  247. messages should be ignored.
  248.  
  249.     Reset
  250.     
  251.         Equivalent of power-on reset. This should normally be used to reset
  252.         any state.
  253.     
  254.         Offset  Size    Description
  255.         
  256.         0       4       Reason code = 0.
  257.     
  258.     
  259.     Shutdown
  260.     
  261.         The PC front-end is being quit (normal or error exit).
  262.         
  263.         Offset  Size    Description
  264.         
  265.         0       4       Reason code = 1.
  266.  
  267.  
  268. LEGAL MATTERS
  269.  
  270. The "ARMEdit" header files, object files and documentation are supplied "as
  271. is"; no warranty, express or implied, of the merchantability of this software
  272. or its fitness for any particular purpose is given. In no circumstances shall
  273. the author, or any provider or distributor of this software, be liable for
  274. any damage, loss of profits, or any indirect or consequential loss arising
  275. out of the use of this software or inability to use this software.
  276.  
  277. These files are FreeWare. Permission is granted for anyone to use them for
  278. the sole purpose of developing software for use with the ARMEdit suite. Any
  279. such software may be freely distributed, providing that use of the supplied
  280. files is acknowledged in the documentation.
  281.  
  282. However, the ARMEdit module may only be distibuted in accordance with the
  283. conditions contained in the ReadMe file enclosed in this distribution.
  284.  
  285.  
  286. THINGS TO DO
  287.  
  288. The following are changes that may be made to the externally available
  289. services sometime in the future.
  290.  
  291.     None at the moment!
  292.  
  293.  
  294. VERSION HISTORY
  295.  
  296. 0.00 (12-Nov-95)    Original development version.
  297.  
  298. 0.04 (16-Dec-95)    First public development release.
  299.  
  300. 0.05 (17-Dec-95)    Improved filename translation.
  301.  
  302. 0.07 (28-Dec-95)    Added message passing protocol.
  303.  
  304. 1.00 (12-Jan-96)    First official release version.
  305.