home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Code / TALK_H < prev   
Encoding:
Text File  |  1997-02-21  |  13.9 KB  |  323 lines
  1. /*
  2.     File        : talk.h
  3.     Date        : 21-Feb-97
  4.     Author      : © A.Thoukydides, 1995, 1996, 1997
  5.     Description : Communications with the RISC OS ARMEdit module. This
  6.                   provides an interface to the services provided by that
  7.                   module without requiring any knowledge of the underlying
  8.                   interface.
  9. */
  10.  
  11. // Only include header file once
  12. #ifndef TALK_H
  13. #define TALK_H
  14.  
  15. // Include system header files
  16. #include <stdlib.h>
  17.  
  18. // RISC OS scrap directory to use
  19. #define TALK_SCRAP "<ARMEdit$ScrapDir>"
  20.  
  21. // OSCLI status codes
  22. #define TALK_OSCLI_ACTIVE 0x00
  23. #define TALK_OSCLI_FINISHED 0x01
  24. #define TALK_OSCLI_WAITING 0x02
  25.  
  26. // ARM registers used on entry and exit from SWIs
  27. typedef struct
  28. {
  29.     long r[10];                         // Only R0 to R9 matter for SWIs
  30. } talk_swi_regs;
  31.  
  32. // A RISC OS style error block
  33. typedef struct
  34. {
  35.     long errnum;                        // Error number
  36.     char errmess[252];                  // Error message (zero terminated)
  37. } talk_error;
  38.  
  39. // A RISC OS date and time
  40. typedef char talk_date[5];
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. /*
  47.     Paramaters  : no            - The number of the SWI to call.
  48.                   in            - Pointer to the values for the ARM registers
  49.                                   on entry to the SWI.
  50.                   out           - Pointer to the values that the ARM
  51.                                   registers contained on exit from the SWI.
  52.     Returns     : talk_error    - A pointer to a RISC OS style error block
  53.                                   (in PC memory), or NULL if there was no
  54.                                   error.
  55.     Description : Call the specified RISC OS SWI. The SWI is always called
  56.                   with the X bit set.
  57. */
  58. const talk_error *talk_swi(long no, const talk_swi_regs *in,
  59.                            talk_swi_regs *out);
  60.  
  61. /*
  62.     Parameters  : buf           - Pointer to buffer to receive data.
  63.                   len           - The number of bytes to read.
  64.                   start         - The start ARM memory address.
  65.     Returns     : talk_error    - A pointer to a RISC OS style error block
  66.                                   (in PC memory), or NULL if there was no
  67.                                   error.
  68.     Description : Read up to 16372 bytes of ARM memory.
  69. */
  70. const talk_error *talk_read(void *buf, size_t len, long start);
  71.  
  72. /*
  73.     Parameters  : buf           - Pointer to buffer containing data.
  74.                   len           - The number of bytes to write.
  75.                   start         - The start ARM memory address.
  76.     Returns     : talk_error    - A pointer to a RISC OS style error block
  77.                                   (in PC memory), or NULL if there was no
  78.                                   error.
  79.     Description : Write up to 16372 bytes of ARM memory.
  80. */
  81. const talk_error *talk_write(const void *buf, size_t len, long start);
  82.  
  83. /*
  84.     Parameters  : len           - Amount of memory to allocate.
  85.                   buf           - Variable to contain address of memory.
  86.     Returns     : talk_error    - A pointer to a RISC OS style error block
  87.                                   (in PC memory), or NULL if there was no
  88.                                   error.
  89.     Description : Claim the specified amount of ARM memory.
  90. */
  91. const talk_error *talk_malloc(size_t len, long *buf);
  92.  
  93. /*
  94.     Parameters  : buf           - Address of block of memory to free.
  95.     Returns     : talk_error    - A pointer to a RISC OS style error block
  96.                                   (in PC memory), or NULL if there was no
  97.                                   error.
  98.     Description : Free a block of memory previously claimed using talk_alloc.
  99. */
  100. const talk_error *talk_free(long buf);
  101.  
  102. /*
  103.     Parameters  : ext           - A file extension.
  104.                   type          - Variable to receive the filetype.
  105.     Returns     : talk_error    - A pointer to a RISC OS style error block
  106.                                   (in PC memory), or NULL if there was no
  107.                                   error.
  108.     Description : Convert a DOS file extension into a RISC OS filetype.
  109. */
  110. const talk_error *talk_ext_to_filetype(const char *ext, int *type);
  111.  
  112. /*
  113.     Parameters  : type          - A RISC OS filetype.
  114.                   ext           - Variable to receive file extension.
  115.     Returns     : talk_error    - A pointer to a RISC OS style error block
  116.                                   (in PC memory), or NULL if there was no
  117.                                   error.
  118.     Description : Convert a RISC OS filetype into a DOS file extension.
  119. */
  120. const talk_error *talk_filetype_to_ext(int type, char *ext);
  121.  
  122.  
  123. /*
  124.     Parameters  : name          - The name of the file to open.
  125.                   size          - The initial size of the file, or -1 to open
  126.                                   an existing file.
  127.                   del           - Should the file be deleted when closed.
  128.                   handle        - Variable to receive the file handle.
  129.     Returns     : talk_error    - A pointer to a RISC OS style error block
  130.                                   (in PC memory), or NULL if there was no
  131.                                   error.
  132.     Description : Open a RISC OS file.
  133. */
  134. const talk_error *talk_file_open(const char *name, long size, int del,
  135.                                  long *handle);
  136.  
  137. /*
  138.     Parameters  : handle        - Handle of the file to close.
  139.     Returns     : talk_error    - A pointer to a RISC OS style error block
  140.                                   (in PC memory), or NULL if there was no
  141.                                   error.
  142.     Description : Close a RISC OS file.
  143. */
  144. const talk_error *talk_file_close(long handle);
  145.  
  146. /*
  147.     Parameters  : handle        - Handle of the file to read from.
  148.                   ptr           - Sequential file pointer position to read
  149.                                   from, or -1 to use current position.
  150.                   size          - Number of bytes to read.
  151.                   buf           - Buffer to receive the data.
  152.                   done          - Variable to receive number of bytes read.
  153.     Returns     : talk_error    - A pointer to a RISC OS style error block
  154.                                   (in PC memory), or NULL if there was no
  155.                                   error.
  156.     Description : Read from a RISC OS file.
  157. */
  158. const talk_error *talk_file_read(long handle, long ptr, long size,
  159.                                  void *buf, long *done);
  160.  
  161. /*
  162.     Parameters  : handle        - Handle of the file to write to.
  163.                   ptr           - Sequential file pointer position to write
  164.                                   at, or -1 to use current position.
  165.                   size          - Number of bytes to write.
  166.                   buf           - Buffer containing the data.
  167.     Returns     : talk_error    - A pointer to a RISC OS style error block
  168.                                   (in PC memory), or NULL if there was no
  169.                                   error.
  170.     Description : Write to a RISC OS file.
  171. */
  172. const talk_error *talk_file_write(long handle, long ptr, long size,
  173.                                   const void *buf);
  174.  
  175. /*
  176.     Parameters  : handle        - Variable to receive the unique handle for
  177.                                   this task. This should be used with all
  178.                                   future communications.
  179.     Returns     : talk_error    - A pointer to a RISC OS style error block
  180.                                   (in PC memory), or NULL if there was no
  181.                                   error.
  182.     Description : Register a communications client.
  183. */
  184. const talk_error *talk_comms_start(long *handle);
  185.  
  186. /*
  187.     Parameters  : handle        - The previously allocated handle for this
  188.                                   client.
  189.     Returns     : talk_error    - A pointer to a RISC OS style error block
  190.                                   (in PC memory), or NULL if there was no
  191.                                   error.
  192.     Description : Deregister a communications client.
  193. */
  194. const talk_error *talk_comms_end(long handle);
  195.  
  196. /*
  197.     Parameters  : handle        - The previously allocated client handle for
  198.                                   this task.
  199.                   dest          - The destination task ID or handle.
  200.                   buf           - The message to send.
  201.     Returns     : talk_error    - A pointer to a RISC OS style error block
  202.                                   (in PC memory), or NULL if there was no
  203.                                   error.
  204.     Description : Send a message to one or more other clients.
  205. */
  206. const talk_error *talk_comms_tx(long handle, long dest, const void *buf);
  207.  
  208. /*
  209.     Parameters  : handle        - The previously allocated client handle for
  210.                                   this task.
  211.                   src_id        - The ID of the sending task.
  212.                   src_handle    - The handle of the sending task.
  213.                   buf           - The buffer to receive the message in.
  214.     Returns     : talk_error    - A pointer to a RISC OS style error block
  215.                                   (in PC memory), or NULL if there was no
  216.                                   error.
  217.     Description : Check for any waiting messages, and read the next one if
  218.                   possible. Note that this (currently) returns an error if
  219.                   there is no message to read.
  220. */
  221. const talk_error *talk_comms_rx(long handle, long *src_id, long *src_handle,
  222.                                 void *buf);
  223.  
  224. /*
  225.     Parameters  : in            - The RISC OS date and time to convert.
  226.                   time          - The DOS style time.
  227.                   date          - The DOS style date.
  228.     Returns     : talk_error    - A pointer to a RISC OS style error block
  229.                                   (in PC memory), or NULL if there was no
  230.                                   error.
  231.     Description : Convert RISC OS format date and times to the equivalent DOS
  232.                   values.
  233. */
  234. const talk_error *talk_date_to_dos(const talk_date in, unsigned *time,
  235.                                    unsigned *date);
  236.  
  237. /*
  238.     Parameters  : time          - The DOS style time.
  239.                   date          - The DOS style date.
  240.                   out           - The equivalent RISC OS style date and time.
  241.     Returns     : talk_error    - A pointer to a RISC OS style error block
  242.                                   (in PC memory), or NULL if there was no
  243.                                   error.
  244.     Description : Convert DOS format date and times to the equivalent RISC OS
  245.                   value.
  246. */
  247. const talk_error *talk_date_to_riscos(unsigned time, unsigned date,
  248.                                       talk_date out);
  249.  
  250. /*
  251.     Parameters  : cmd           - The command to execute.
  252.                   handle        - The returned handle for this command.
  253.     Returns     : talk_error    - A pointer to a RISC OS style error block
  254.                                   (in PC memory), or NULL if there was no
  255.                                   error.
  256.     Description : Start executing a RISC OS *command.
  257. */
  258. const talk_error *talk_oscli_start(const char *cmd, long *handle);
  259.  
  260. /*
  261.     Parameters  : handle        - The command handle.
  262.                   in_size       - Number of input bytes to send.
  263.                   in            - Bytes to send.
  264.                   status        - Returned status.
  265.                   out_size      - Number of output bytes received.
  266.                   out           - Buffer for received output (at least 256
  267.                                   bytes).
  268.     Returns     : talk_error    - A pointer to a RISC OS style error block
  269.                                   (in PC memory), or NULL if there was no
  270.                                   error.
  271.     Description : Continue executing a RISC OS *command.
  272. */
  273. const talk_error *talk_oscli_poll(long handle, long in_size, const char *in,
  274.                                   long *status, long *out_size, char *out);
  275.  
  276. /*
  277.     Parameters  : handle        - The command handle.
  278.     Returns     : talk_error    - A pointer to a RISC OS style error block
  279.                                   (in PC memory), or NULL if there was no
  280.                                   error.
  281.     Description : Stop executing a RISC OS *command.
  282. */
  283. const talk_error *talk_oscli_end(long handle);
  284.  
  285. /*
  286.     Parameters  : handle        - The previously allocated client handle for
  287.                                   this task.
  288.                   dest          - The destination task handle.
  289.                   buf           - The message to send.
  290.     Returns     : talk_error    - A pointer to a RISC OS style error block
  291.                                   (in PC memory), or NULL if there was no
  292.                                   error.
  293.     Description : Reply to a message from another client.
  294. */
  295. const talk_error *talk_comms_reply(long handle, long dest, const void *buf);
  296.  
  297. /*
  298.     Parameters  : centiseconds  - Time in centiseconds before multitasking
  299.                                   should be reenabled, or 0 to reenable
  300.                                   normal operation.
  301.     Returns     : talk_error    - A pointer to a RISC OS style error block
  302.                                   (in PC memory), or NULL if there was no
  303.                                   error.
  304.     Description : Disable multitasking for a specified length of time.
  305. */
  306. const talk_error *talk_faster(long centiseconds);
  307.  
  308. /*
  309.     Parameters  : buf           - Buffer to receive the filename.
  310.                   len           - Size of the buffer.
  311.     Returns     : talk_error    - A pointer to a RISC OS style error block
  312.                                   (in PC memory), or NULL if there was no
  313.                                   error.
  314.     Description : Generate a unique RISC OS filename for a temporary file.
  315. */
  316. const talk_error *talk_temporary(char *buf, size_t len);
  317.  
  318. #ifdef __cplusplus
  319. }
  320. #endif
  321.  
  322. #endif
  323.