home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / adhesive_1 / tools / h / AdhesiveRS < prev   
Encoding:
Text File  |  1994-09-22  |  4.1 KB  |  139 lines
  1. /***************************************************************************
  2.  
  3.                 Adhesive (C) 1994 George Taylor
  4.                 -------------------------------
  5.  
  6.         Title:   adhesiveRS.h
  7.  
  8.         Purpose: Access to object resources
  9.  
  10.         Author:  George Taylor
  11.  
  12.         Version: 1.00
  13.  
  14. ***************************************************************************/
  15.  
  16. #pragma include_only_once
  17.  
  18. #ifndef __ADHESIVERS
  19. #define __ADHESIVERS
  20.  
  21. #include "kernel.h"  /* for oserror */
  22.  
  23. /* Nice and simple interface to SWIs which can be called from objects.
  24.    The corresponding object file o.AdhesiveRS imports the symbol
  25.    |!!!AdhesiveHeader| to find out where your object is in memory.
  26. */
  27.  
  28. /* Procedure:    adhesive_Resource
  29.  *
  30.  * Description:    Get a pointer to the directory name of your object.
  31.  *
  32.  * Parameters:    none
  33.  *
  34.  * Returns:    const char *dirname
  35.  *            Pointer to read-only directory name or 0 if error.
  36.  *
  37.  * Other Info:  This call can be done from interrupts as it is reentrant.
  38.  *          This call must only be made from within an object.
  39.  */
  40. const char *adhesive_Resource(void);
  41.  
  42.  
  43.  
  44.  
  45. /* Interface to Adhesive_Resource SWI.
  46. */
  47.  
  48.  
  49. /* Message parameters used for parameter substitution.
  50. */
  51. typedef struct {
  52.   const char *p[4];  /* %0..%3, use NULL to avoid substitution */
  53.                /* if a % parameter is not in the message then
  54.                    the corresponding parameter given here is ignored
  55.                */
  56. } MessageParams;
  57.  
  58.  
  59.  
  60. /* Procedure:    adhesive_Messages
  61.  *
  62.  * Description:    Lookup a message from your object's messages file if it
  63.  *        has one.
  64.  *
  65.  * Parameters:    const char *tag - message tag to lookup
  66.  *            *may contain default message i.e. tag:default)
  67.  *
  68.  *        char *buf - buffer for resulting message
  69.  *            0=>no buffer, return read-only copy with no
  70.  *            parameter substitution
  71.  *
  72.  *        unsigned int buflen - length of buffer in bytes
  73.  *            (ignored if buf==0)
  74.  *
  75.  *        MessageParams *params - message parameters
  76.  *            (ignored if buf==0)
  77.  *        - parameters not referred to in the message are not used
  78.  *        - pass NULL for a parameter to avoid substitution
  79.  *        - pass NULL for params if you wish no substituion
  80.  *
  81.  * Returns:    char * - pointer to message, this is either in your
  82.  *             buffer or a read-only copy if buf==0 on entry.
  83.  *             0=> the message tag could not be found and the message
  84.  *                 does not have a default (or if the object has
  85.  *             no messages file)
  86.  *
  87.  * Other Info:    The read-only message returned exists until your object
  88.  *        is removed from memory.
  89.  *
  90.  *        This call can be done from interrupts as it is reentrant.
  91.  *        This call must only be made from within an object.
  92.  *
  93.  *        IMPORTANT:
  94.  *        If buf=0 on entry then the message is terminated
  95.  *        with a ctrl character (not necessarily 0).
  96.  *        MessageTrans is to blame for this.
  97.  *        The string is always terminated by a zero if you specify
  98.  *        a buffer.
  99.  *
  100.  *        You could try solving the above problem by placing
  101.  *        a 0 byte in the original messages file. The PRM defines
  102.  *        that any character apart from \n can appear in a message.
  103.  *        Tests of mine leave me doubting this.
  104.  *
  105.  */
  106. char *adhesive_Messages(const char *tag, char *buf, unsigned int buflen,
  107.             const MessageParams *params);
  108.  
  109.  
  110. /* Procedure:    adhesive_Error
  111.  *
  112.  * Description:    Given a _kernel_oserror block containing a message number
  113.  *        and a message token, return a new _kernel_oserror block
  114.  *        containing the message string instead of the token.
  115.  *
  116.  * Parameters:    const _kernel_oserror * - input error block
  117.  *            (token must be zero terminated)
  118.  *
  119.  *        MessageParams *params - message parameters
  120.  *        - parameters not referred to in the message are not used
  121.  *        - pass NULL for a parameter to avoid substitution
  122.  *        - pass NULL for params if you wish no substituion
  123.  *
  124.  * Returns:    _kernel_oserror * - pointer to readonly error block
  125.  *        (this an internal MessageTrans error block)
  126.  *
  127.  * Other Info:    If the message token could not be found or if the object
  128.  *        has no messages file then the passed error block is
  129.  *        returned.
  130.  *
  131.  *        SWI MessageTrans_ErrorLookup is used, see the PRM for
  132.  *        details of internal error buffers
  133.  */
  134. _kernel_oserror *adhesive_Error(_kernel_oserror block,
  135.                 const MessageParams *params);
  136.  
  137.  
  138. #endif
  139.