/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    MsgTrans.h
    Author:  Copyright  1994 Tony Houghton
    Version: 1.02 (05 Nov 1994)
    Purpose: Interface to some of the most useful MessageTrans routines

    NOTE: This is a veneer for the OS 'MsgTrans' system. An analogue of
          this system is provided by the 'Msgs' sublibrary (Msgs.h).
          Note that each system has advantages and disavantages compared
          to the other...
*/

#ifndef __dl_msgtrans_h
#define __dl_msgtrans_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_core_h
#include "Core.h"
#endif

/*K*************************************************************************

> MessageTrans

MessageTrans is Acorn's module for looking up messages in a text file; it
is standard with RISC OS 3 onwards. You may prefer to use it to DeskLib's
Msgs.h to avoid duplicating OS functionality or to gain access to system
Messages files, because Msgs.h has an incompatible token format.

A Messages file has the following structure:

  # Comment lines begin with a #
  Token:Text message with parameters %0 to %3
  Token1
  Token2/Token3:Message with more than one token
  Percent:Message with a percent sign - %%

The final line must have a terminating LF.

PARAMETER SUBSTITUTION: Parameter substitution can be carried out by passing
  up to 4 additional string parameters which are substituted for %0 to %3.

DEFAULT STRINGS: By supplying a token in the form "Token:Default string", if
  the token is not matched in the file, the supplied string is used instead.

WILDCARDED/MULTIPLE TOKENS: A '?' in a token in the file matches any
  character in the token supplied to be matched. A message can have more
  than one token separated by '/' or LF.

DeskLib's MessageTrans library provides low level interfaces to the most
essential of the module's SWIs. The others are unlikely to be useful in the
context of a program written with DeskLib. In addition, there are some
functions prefixed MsgTrans_ which provide higher level access to the calls.


****************************************************************************/


/*K*************************************************************************

> MsgTrans

A group of functions providing higher level access to MessageTrans SWI
functions. MsgTrans maintains a linked list of message files to allow it to find their
buffers in memory for freeing.


****************************************************************************/


typedef struct {
  int data[4];
} msgtrans_filedesc;
/*
  Purpose:  A file descriptor block for use with MessageTrans SWIs.
  Fields:   Not available to user.
  SeeAlso:  MessageTrans_OpenFile; MessageTrans_Lookup;
            MessageTrans_CloseFile
*/



extern os_error *MessageTrans_FileInfo(char *filename, int *flags, int *size);
/*
  Purpose:  Get information about a Messages file prior to opening it
  Inputs:   filename - Messages file path name
  Outputs:  *flags   - bit 1 set indicates file is held in memory; all other
                       bits are reserved
            *size    - size of buffer necessary to hold file
  Returns:  Pointer to an error block or NULL if successful
  Errors:   -
  SeeAlso:  MessageTrans_OpenFile
*/



extern os_error *MessageTrans_OpenFile(msgtrans_filedesc *filedesc,
                                       char *filename, char *buffer);
/*
  Purpose:  Open or load a Messages file ready for reading
  Inputs:   filedesc - Pointer to a file descriptor block which must be
                         held in the RMA if buffer is NULL on entry
            filename   - Messages file path name; string must be held in the
                         RMA if buffer is NULL on entry
            buffer     - Pointer to buffer to hold file or NULL; in the
                         latter case the file will be used directly if
                         possible, otherwise space will be allocated in the
                         RMA.
  Outputs:  -  
  Returns:  Pointer to an error block or NULL if successful
  Errors:   "Message file already open" if descriptor is in use
  SeeAlso:  msgtrans_filedesc; MessageTrans_CloseFile
*/



extern os_error *MessageTrans_Lookup(msgtrans_filedesc *filedesc, char *token,
                                     char **buffer, int *size,
                                     char *p0, char *p1, char *p2, char *p3);
/*
  Purpose:  Look up a token in an open Messages file and return its string
  Inputs:   filedesc - pointer to a file descriptor block
            token      - token to match
            *buffer    - a pointer to the buffer to copy the string or NULL
                         if the string is not to be copied
            *size      - size of the buffer
            p0 to p3   - optional parameters (NULL for no substitution)
  Outputs:  *buffer    - now points to result string
            *size      - updated to size of result before terminator
  Returns:  Pointer to an error block or NULL if successful
  Errors:   -
  SeeAlso:  msgtrans_filedesc; MessageTrans_OpenFile
*/



extern os_error *MessageTrans_CloseFile(msgtrans_filedesc *filedesc);
/*
  Purpose:  Close a Messages file
  Inputs:   filedesc - Pointer to the file descriptor block
  Outputs:  -  
  Returns:  Pointer to an error block or NULL if successful
  Errors:   -
  SeeAlso:  mesgtrans_filedesc; MessageTrans_OpenFile
*/





extern os_error *MsgTrans_LoadFile(msgtrans_filedesc **filedesc,char *filename);
/*
  Purpose:  Allocate space for a Messages file and load it
  Inputs:   filename  - path name of Messages file
  Outputs:  *filedesc - points to file descriptor block
  Returns:  An error if one of the SWIs fails or NULL
  Errors:   As for MessageTrans_FileInfo and MessageTrans_OpenFile,
            or 'NoStore' from Resources:Global.Messages
  SeeAlso:  msgtrans_filedesc; MessageTrans_FileInfo; MessageTrans_OpenFile;
              MsgTrans
*/



#define MsgTrans_Lookup(filedesc, token, buffer, bufflen) \
  MsgTrans_LookupPS((filedesc), (token), (buffer), (bufflen), \
                    NULL, NULL, NULL, NULL)
/*
  MACRO:    extern os_error *MsgTrans_Lookup(msgtrans_filedesc *filedesc,
                                             char *token,
                                             char *buffer, int bufflen);

  Purpose:  Copy the matched token's string to a buffer and ensure it is NULL
            terminated.
  Inputs:   filedesc - descriptor or NULL for Global messages
            token    - token to match
            buffer   - where to store result
            bufflen  - size of buffer available
  Outputs:  *buffer - result string is copied here
  Returns:  An error if MessageTrans_Lookup fails or NULL
  Errors:   As for MessageTrans_Lookup
  SeeAlso:  msgtrans_filedesc; MessageTrans_Lookup; MsgTrans
*/



extern os_error *MsgTrans_LookupPS(msgtrans_filedesc *filedesc, char *token,
                                   char *buffer, int bufflen,
                                   char *p0, char *p1, char *p2, char *p3);
/*
  Purpose:  MsgTrans_Lookup with parameter substitution
  Inputs:   filedesc - descriptor or NULL for Global messages
            token    - token to match
            buffer   - where to store result
            bufflen  - size of buffer available
            p0 to p3 - strings to substitute in result or NULL
  Outputs:  *buffer - result string is copied here
  Returns:  An error if MessageTrans_Lookup fails or NULL
  Errors:   As for MessageTrans_Lookup
  SeeAlso:  msgtrans_filedesc; MessageTrans_Lookup; MsgTrans_Lookup; MsgTrans
*/



extern os_error *MsgTrans_LoseFile(msgtrans_filedesc *filedesc);
/*
  Purpose:  Closes a Messages file and frees memory used
  Inputs:   block - pointer to msgtrans_block for file
  Outputs:  -
  Returns:  Pointer to an error block or NULL if successful
  Errors:   As for MessageTrans_CloseFile
  SeeAlso:  msgtrans_filedesc; MsgTrans_LoadFile; MessageTrans_CloseFile;
            MsgTrans
*/



#define MsgTrans_Report(filedesc, token, fatal) \
  MsgTrans_ReportPS((filedesc),(token),(fatal),0,0,0,0)
/*
  MACRO:    extern os_error *MsgTrans_Report(msgtrans_filedesc *filedesc,
                                             char *token,BOOL fatal);

  Purpose:  Looks up a message into an internal buffer and passes it to
            Error_Report or Error_ReportFatal
  Inputs:   filedesc - file descriptor
            token    - token to match
            fatal    - whether to call Error_Report or Error_ReportFatal
  Outputs:  -
  Returns:  Pointer to an error block or NULL if successful
  Errors:   As for MessageTrans_Lookup
  SeeAlso:  msgtrans_filedesc; MsgTrans_Lookup; MsgTrans_ReportPS; MsgTrans;
            Error_Report; Error_ReportFatal
*/



extern os_error *MsgTrans_ReportPS(msgtrans_filedesc *filedesc,char *token,
                                   BOOL fatal,
                                   char *p0,char *p1,char *p2,char *p3);
/*
  Purpose:  Looks up a message with parameter substitution into an
            internal buffer and passes it to Error_Report or Error_ReportFatal
  Inputs:   filedesc - file descriptor
            token    - token to match
            fatal    - whether to call Error_Report or Error_ReportFatal
  Outputs:  -
  Returns:  Pointer to an error block or NULL if successful
  Errors:   As for MessageTrans_Lookup
  SeeAlso:  msgtrans_filedesc; MsgTrans_LookupPS; MsgTrans_Report; MsgTrans;
            Error_Report; Error_ReportFatal
*/

#ifdef __cplusplus
}
#endif


#endif
