/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*
 * Title:    msgs.h
 * Purpose:  provide support for messages resource file
 *           (Use this to make your applications "internationalisable!")
 *
 */

#ifndef __msgs_h
#define __msgs_h

#ifndef BOOL
  #define BOOL int
  #define TRUE 1
  #define FALSE 0
#endif

#define msgs_TAG_MAX  10 /*max length of a tag in characters*/
#define msgs_MSG_MAX 255 /*max length of a message*/
#define msgs_VARIANT_MAX 8 /*max no of tags for a single message*/

/* ------------------- msgs_main_control_block --------------------------
 * Description:   Provide access to the MessageTrans control block used
 *                to access the main message file.
 *
 * Parameters:    void
 * Returns:       a pointer to the control block
 */

extern struct msgtrans_control_block *msgs_main_control_block (void);

/* ------------------- msgs_default_control_block --------------------------
 * Description:   Provide access to the MessageTrans control block used
 *                to access RISC_OSLib's messages file
 *
 * Parameters:    void
 * Returns:       a pointer to the control block
 */

extern struct msgtrans_control_block *msgs_default_control_block (void);

/* ---------------------------- msgs_init ----------------------------------
 * Description:   Read in the messages file, and initialise msg system
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    the messages file is a resource of your application and
 *                should be named "Messages".  Each line of this file is a
 *                message with the following format:
 *                      <tags><colon><message text><newline>
 *                where <tags> is a series of alphanumeric identifiers for
 *                the message, separated by '/' characters. These are
 *                used to search for the message, when using msgs_lookup().
 */

void msgs_init(void);


/* ---------------------------- msgs_lookup --------------------------------
 * Description:   Find the text message associated with a given tag.
 *
 * Parameters:    char * tag_and_default -- the tag of the message, and
 *                                          an optional default message (to
 *                                          be used if tagged message not
 *                                          found).
 * Returns:       pointer to the message text (if all is well)
 * Other Info:    If the caller just supplies a tag, he will receive a
 *                pointer to its associated message (if found). A default
 *                message can be given after the tag (separated by a colon)
 *                Typical use would be:
 *                      werr(1, msgs_lookup("error1"))
 *                or    werr(1, msgs_lookup("error1:Not enough memory").
 *
 */

char *msgs_lookup(char *tag_and_default);

/* ---------------------------- msgs_readfile ------------------------------
 * Description:   Read in the messages file, and initialise msg system
 *
 * Parameters:    char *name -- the name of the messages file to be read.
 * Returns:       void.
 * Other Info:    the messages file is a resource of your application and
 *                should normally be named "Messages".  For non-standard
 *                applications this call has been provided to enable
 *                the messages file to be read from elsewhere.  Each line
 *                of this file is a message with the following format:
 *                      <tag><colon><message text><newline>
 *                The tag is an alphanumeric identifier for the message,
 *                which will be used to search for the message, when using
 *                msgs_lookup().
 *
 */

#define msgs_readfile(s) msgs_init()

#endif

/* end msgs.h */