The Datafile PD-CD 4/DATAFILE_PDCD4.iso/utilities/utilsa/armedit/Code/TALK_H

Text File | 1996-01-12 | 9.0 KB | 268 lines

/*
    File        : talk.h
    Date        : 12/1/96
    Author        : © A.Thoukydides, 1995, 1996
    Description    : Communications with the RISC OS ARMEdit module. This
                  provides an interface to the services provided by that
                  module without requiring any knowledge of the underlying
                  interface.
*/

// Only include header file once
#ifndef TALK_H
#define TALK_H

// Include system header files
#include <stdlib.h>

// RISC OS scrap directory to use
#define TALK_SCRAP "<ARMEdit$ScrapDir>"

// ARM registers used on entry and exit from SWIs
typedef struct
{
    long r[10];                            // Only R0 to R9 matter for SWIs
} talk_swi_regs;

// A RISC OS style error block
typedef struct
{
    long errnum;                        // Error number
    char errmess[252];                    // Error message (zero terminated)
} talk_error;

#ifdef __cplusplus
extern "C" {
#endif

/*
    Paramaters    : no            - The number of the SWI to call.
                  in            - Pointer to the values for the ARM registers
                                  on entry to the SWI.
                  out            - Pointer to the values that the ARM
                                  registers contained on exit from the SWI.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Call the specified RISC OS SWI. The SWI is always called
                  with the X bit set.
*/
const talk_error *talk_swi(long no, const talk_swi_regs *in,
                           talk_swi_regs *out);

/*
    Parameters    : buf            - Pointer to buffer to receive data.
                  len            - The number of bytes to read.
                  start            - The start ARM memory address.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Read up to 16372 bytes of ARM memory.
*/
const talk_error *talk_read(void *buf, size_t len, long start);

/*
    Parameters    : buf            - Pointer to buffer containing data.
                  len            - The number of bytes to write.
                  start            - The start ARM memory address.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Write up to 16372 bytes of ARM memory.
*/
const talk_error *talk_write(const void *buf, size_t len, long start);

/*
    Parameters    : len            - Amount of memory to allocate.
                  buf            - Variable to contain address of memory.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Claim the specified amount of ARM memory.
*/
const talk_error *talk_malloc(size_t len, long *buf);

/*
    Parameters    : buf            - Address of block of memory to free.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Free a block of memory previously claimed using talk_alloc.
*/
const talk_error *talk_free(long buf);

/*
    Parameters    : ext            - A file extension.
                  type            - Variable to receive the filetype.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Convert a DOS file extension into a RISC OS filetype.
*/
const talk_error *talk_ext_to_filetype(const char *ext, int *type);

/*
    Parameters    : type            - A RISC OS filetype.
                  ext            - Variable to receive file extension.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Convert a RISC OS filetype into a DOS file extension.
*/
const talk_error *talk_filetype_to_ext(int type, char *ext);


/*
    Parameters    : name            - The name of the file to open.
                  size            - The initial size of the file, or -1 to open
                                  an existing file.
                  del            - Should the file be deleted when closed.
                  handle        - Variable to receive the file handle.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Open a RISC OS file.
*/
const talk_error *talk_file_open(const char *name, long size, int del,
                                 long *handle);

/*
    Parameters    : handle        - Handle of the file to close.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Close a RISC OS file.
*/
const talk_error *talk_file_close(long handle);

/*
    Parameters    : handle        - Handle of the file to read from.
                  ptr            - Sequential file pointer position to read
                                  from, or -1 to use current position.
                  size            - Number of bytes to read.
                  buf            - Buffer to receive the data.
                  done            - Variable to receive number of bytes read.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Read from a RISC OS file.
*/
const talk_error *talk_file_read(long handle, long ptr, long size,
                                 void *buf, long *done);

/*
    Parameters    : handle        - Handle of the file to write to.
                  ptr            - Sequential file pointer position to write
                                  at, or -1 to use current position.
                  size            - Number of bytes to write.
                  buf            - Buffer containing the data.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Write to a RISC OS file.
*/
const talk_error *talk_file_write(long handle, long ptr, long size,
                                  const void *buf);

/*
    Parameters    : handle        - Variable to receive the unique handle for
                                  this task. This should be used with all
                                  future communications.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Register a communications client.
*/
const talk_error *talk_comms_start(long *handle);

/*
    Parameters    : handle        - The previously allocated handle for this
                                  client.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Deregister a communications client.
*/
const talk_error *talk_comms_end(long handle);

/*
    Parameters    : handle        - The previously allocated client handle for
                                  this task.
                  dest            - The destination task ID or handle.
                  buf            - The message to send.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Send a message to one or more other clients.
*/
const talk_error *talk_comms_tx(long handle, long dest, const void *buf);

/*
    Parameters    : handle        - The previously allocated client handle for
                                  this task.
                  src_id        - The ID of the sending task.
                  src_handle    - The handle of the sending task.
                  buf            - The buffer to receive the message in.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Check for any waiting messages, and read the next one if
                  possible. Note that this (currently) returns an error if
                  there is no message to read.
*/
const talk_error *talk_comms_rx(long handle, long *src_id, long *src_handle,
                                void *buf);

/*
    Parameters    : handle        - The unique handle allocated for this
                                  client.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Register a communications client.
*/
const talk_error *talk_comms_start(long *handle);

/*
    Parameters    : handle        - The unique handle previously allocated to
                                  this client.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Deregister a communications client.
*/
const talk_error *talk_comms_end(long handle);

/*
    Parameters    : handle        - The unique handle previously allocated to
                                  this client.
                  dest            - The destination ID or handle.
                  msg            - The message to send.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Transmit a message to another client.
*/
const talk_error *talk_comms_tx(long handle, long dest, const void *msg);

/*
    Parameters    : handle        - The unique handle previously allocated to
                                  this client.
                  src_id        - The ID of the sending task.
                  src_handle    - The handle of the sending task.
                  msg            - The buffer to receive the message.
    Returns        : talk_error    - A pointer to a RISC OS style error block
                                  (in PC memory), or NULL if there was no
                                  error.
    Description    : Receive a message from another task. Note that an error is
                  returned if no message is available.
*/
const talk_error *talk_comms_rx(long handle, long *src_id, long *src_handle,
                                void *msg);

#ifdef __cplusplus
}
#endif

#endif