home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / MsgTrans < prev    next >
Encoding:
Text File  |  1996-09-12  |  14.4 KB  |  446 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    MsgTrans.h
  12.     Author:  Copyright © 1994 Tony Houghton, 1996 Julian Smith
  13.     Version: 1.10 (12 Jun 1996)
  14.     Purpose: Interface to some of the most useful MessageTrans routines
  15.     History:
  16.         1.02 (05 Nov 1994) TH
  17.         1.10 (12 Jun 1996) JS    Added:
  18.                     Desk_MessageTrans_LookupGetSize
  19.                     Desk_MessageTrans_LookupIntoBuffer
  20.                         Desk_MessageTrans_LookupIntoBufferPos
  21.                         Desk_MessageTrans_LookupIntoBufferCat
  22.                         Desk_MessageTrans_OpenLookupCloseIntoBufferPos
  23.                         Desk_MessageTrans_OpenLookupCloseIntoBuffer
  24.                         Desk_MessageTrans_OpenLookupCloseIntoBufferCat
  25.             1.11 (05 Jul 1996) JS    Added
  26.                     Desk_MessageTrans_OpenFileRMA
  27.                     Desk_MessageTrans_CloseFileRMA
  28.         
  29.         12 Sep 1996 JS        Ammended docs for Desk_MessageTrans_Lookup
  30.                     - clarified what to do when not wanting
  31.                     data to be copied.
  32.  
  33.     NOTE: This is a veneer for the OS 'MsgTrans' system. An analogue of
  34.           this system is provided by the 'Msgs' sublibrary (Msgs.h).
  35.           Note that each system has advantages and disavantages compared
  36.           to the other...
  37. */
  38.  
  39. #ifndef __Desk_MsgTrans_h
  40. #define __Desk_MsgTrans_h
  41.  
  42. #ifdef __cplusplus
  43.     extern "C" {
  44. #endif
  45.  
  46.  
  47. #ifndef __Desk_DeskMem_h
  48.     #include "Desk.DeskMem.h"
  49. #endif
  50.  
  51.  
  52. /*K*************************************************************************
  53.  
  54. > MessageTrans
  55.  
  56. MessageTrans is Acorn's module for looking up messages in a text file; it
  57. is standard with RISC OS 3 onwards. You may prefer to use it to DeskLib's
  58. Msgs.h to avoid duplicating OS functionality or to gain access to system
  59. Messages files, because Msgs.h has an incompatible token format.
  60.  
  61. A Messages file has the following structure:
  62.  
  63.   # Comment lines begin with a #
  64.   Token:Text message with parameters %0 to %3
  65.   Token1
  66.   Token2/Token3:Message with more than one token
  67.   Percent:Message with a percent sign - %%
  68.  
  69. The final line must have a terminating LF.
  70.  
  71. PARAMETER SUBSTITUTION: Parameter substitution can be carried out by passing
  72.   up to 4 additional string parameters which are substituted for %0 to %3.
  73.  
  74. DEFAULT STRINGS: By supplying a token in the form "Token:Default string", if
  75.   the token is not matched in the file, the supplied string is used instead.
  76.  
  77. WILDCARDED/MULTIPLE TOKENS: A '?' in a token in the file matches any
  78.   character in the token supplied to be matched. A message can have more
  79.   than one token separated by '/' or LF.
  80.  
  81. DeskLib's MessageTrans library provides low level interfaces to the most
  82. essential of the module's SWIs. The others are unlikely to be useful in the
  83. context of a program written with DeskLib. In addition, there are some
  84. functions prefixed Desk_MsgTrans_ which provide higher level access to the calls.
  85.  
  86.  
  87. ****************************************************************************/
  88.  
  89.  
  90. /*K*************************************************************************
  91.  
  92. > MsgTrans
  93.  
  94. A group of functions providing higher level access to MessageTrans SWI
  95. functions. MsgTrans maintains a linked list of message files to allow it to find their
  96. buffers in memory for freeing.
  97.  
  98.  
  99. ****************************************************************************/
  100.  
  101.  
  102. typedef struct {
  103.   int data[4];
  104. } Desk_msgtrans_filedesc;
  105. /*
  106.   Purpose:  A file descriptor block for use with MessageTrans SWIs.
  107.   Fields:   Not available to user.
  108.   SeeAlso:  Desk_MessageTrans_OpenFile; Desk_MessageTrans_Lookup;
  109.             Desk_MessageTrans_CloseFile
  110. */
  111.  
  112.  
  113.  
  114. extern void    Desk_MessageTrans_FileInfo(char *filename, int *flags, int *size);
  115. /*
  116.   Purpose:  Get information about a Messages file prior to opening it
  117.   Inputs:   filename - Messages file path name
  118.   Outputs:  *flags   - bit 1 set indicates file is held in memory; all other
  119.                        bits are reserved
  120.             *size    - size of buffer necessary to hold file
  121.   Returns:  Pointer to an error block or NULL if successful
  122.   Errors:   -
  123.   SeeAlso:  Desk_MessageTrans_OpenFile
  124. */
  125.  
  126.  
  127.  
  128. extern void    Desk_MessageTrans_OpenFile(Desk_msgtrans_filedesc *filedesc,
  129.                                        char *filename, char *buffer);
  130. /*
  131.   Purpose:  Open or load a Messages file ready for reading
  132.   Inputs:   filedesc - Pointer to a file descriptor block which must be
  133.                          held in the RMA if buffer is NULL on entry
  134.             filename   - Messages file path name; string must be held in the
  135.                          RMA if buffer is NULL on entry
  136.             buffer     - Pointer to buffer to hold file or NULL; in the
  137.                          latter case the file will be used directly if
  138.                          possible, otherwise space will be allocated in the
  139.                          RMA.
  140.   Outputs:  -  
  141.   Returns:  Pointer to an error block or NULL if successful
  142.   Errors:   "Message file already open" if descriptor is in use
  143.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_CloseFile
  144. */
  145.  
  146.  
  147.  
  148. extern void    Desk_MessageTrans_Lookup(Desk_msgtrans_filedesc *filedesc, char *token,
  149.                                      char **buffer, int *size,
  150.                                      char *p0, char *p1, char *p2, char *p3);
  151. /*
  152.   Purpose:  Look up a token in an open Messages file and return its string
  153.   Inputs:   filedesc - pointer to a file descriptor block
  154.             token      - token to match
  155.             *buffer    - a pointer to the buffer to copy the string or NULL
  156.                          if the string is not to be copied
  157.             *size      - size of the buffer
  158.             p0 to p3   - optional parameters (NULL for no substitution)
  159.             Note that 'buffer' and 'size' should both be the address of
  160.             bona-fide variables. If the message is not to be copied, both
  161.             of these variables should contain 0 (so 'buffer' and 'size' will
  162.             both point to words which contain zero).
  163.             
  164.   Outputs:  *buffer    - now points to result string
  165.             *size      - updated to size of result before terminator
  166.   Returns:  Pointer to an error block or NULL if successful
  167.   Errors:   -
  168.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_OpenFile
  169. */
  170.  
  171.  
  172.  
  173. extern void    Desk_MessageTrans_CloseFile(Desk_msgtrans_filedesc *filedesc);
  174. /*
  175.   Purpose:  Close a Messages file
  176.   Inputs:   filedesc - Pointer to the file descriptor block
  177.   Outputs:  -  
  178.   Returns:  Pointer to an error block or NULL if successful
  179.   Errors:   -
  180.   SeeAlso:  Desk_mesgtrans_filedesc; Desk_MessageTrans_OpenFile
  181. */
  182.  
  183.  
  184.  
  185.  
  186.  
  187. extern void    Desk_MsgTrans_LoadFile(Desk_msgtrans_filedesc **filedesc, char *filename);
  188. /*
  189.   Purpose:  Allocate space for a Messages file and load it
  190.   Inputs:   filename  - path name of Messages file
  191.   Outputs:  *filedesc - points to file descriptor block
  192.   Returns:  An error if one of the SWIs fails or NULL
  193.   Errors:   As for Desk_MessageTrans_FileInfo and Desk_MessageTrans_OpenFile,
  194.             or 'NoStore' from Resources:Global.Messages
  195.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_FileInfo; Desk_MessageTrans_OpenFile;
  196.               MsgTrans
  197. */
  198.  
  199.  
  200.  
  201. #define Desk_MsgTrans_Lookup(filedesc, token, buffer, bufflen) \
  202.   Desk_MsgTrans_LookupPS((filedesc), (token), (buffer), (bufflen), \
  203.                     NULL, NULL, NULL, NULL)
  204. /*
  205.   MACRO:    extern Desk_os_error *Desk_MsgTrans_Lookup(Desk_msgtrans_filedesc *filedesc,
  206.                                              char *token,
  207.                                              char *buffer, int bufflen);
  208.  
  209.   Purpose:  Copy the matched token's string to a buffer and ensure it is NULL
  210.             terminated.
  211.   Inputs:   filedesc - descriptor or NULL for Global messages
  212.             token    - token to match
  213.             buffer   - where to store result
  214.             bufflen  - size of buffer available
  215.   Outputs:  *buffer - result string is copied here
  216.   Returns:  An error if Desk_MessageTrans_Lookup fails or NULL
  217.   Errors:   As for Desk_MessageTrans_Lookup
  218.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_Lookup; MsgTrans
  219. */
  220.  
  221.  
  222.  
  223. extern void    Desk_MsgTrans_LookupPS(Desk_msgtrans_filedesc *filedesc, char *token,
  224.                                    char *buffer, int bufflen,
  225.                                    char *p0, char *p1, char *p2, char *p3);
  226. /*
  227.   Purpose:  Desk_MsgTrans_Lookup with parameter substitution
  228.   Inputs:   filedesc - descriptor or NULL for Global messages
  229.             token    - token to match
  230.             buffer   - where to store result
  231.             bufflen  - size of buffer available
  232.             p0 to p3 - strings to substitute in result or NULL
  233.   Outputs:  *buffer - result string is copied here
  234.   Returns:  An error if Desk_MessageTrans_Lookup fails or NULL
  235.   Errors:   As for Desk_MessageTrans_Lookup
  236.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_Lookup; Desk_MsgTrans_Lookup; MsgTrans
  237. */
  238.  
  239.  
  240.  
  241. extern void    Desk_MsgTrans_LoseFile(Desk_msgtrans_filedesc *filedesc);
  242. /*
  243.   Purpose:  Closes a Messages file and frees memory used
  244.   Inputs:   block - pointer to Desk_msgtrans_block for file
  245.   Outputs:  -
  246.   Returns:  Pointer to an error block or NULL if successful
  247.   Errors:   As for Desk_MessageTrans_CloseFile
  248.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_LoadFile; Desk_MessageTrans_CloseFile;
  249.             MsgTrans
  250. */
  251.  
  252.  
  253.  
  254. #define Desk_MsgTrans_Report(filedesc, token, fatal) \
  255.   Desk_MsgTrans_ReportPS((filedesc), (token), (fatal), 0, 0, 0, 0)
  256. /*
  257.   MACRO:    extern Desk_os_error *Desk_MsgTrans_Report(Desk_msgtrans_filedesc *filedesc,
  258.                                              char *token, Desk_bool fatal);
  259.  
  260.   Purpose:  Looks up a message into an internal buffer and passes it to
  261.             Desk_Error_Report or Desk_Error_ReportFatal
  262.   Inputs:   filedesc - file descriptor
  263.             token    - token to match
  264.             fatal    - whether to call Desk_Error_Report or Desk_Error_ReportFatal
  265.   Outputs:  -
  266.   Returns:  Pointer to an error block or NULL if successful
  267.   Errors:   As for Desk_MessageTrans_Lookup
  268.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_Lookup; Desk_MsgTrans_ReportPS; MsgTrans;
  269.             Desk_Error_Report; Desk_Error_ReportFatal
  270. */
  271.  
  272.  
  273.  
  274. extern void    Desk_MsgTrans_ReportPS(Desk_msgtrans_filedesc *filedesc, char *token,
  275.                                    Desk_bool fatal,
  276.                                    char *p0, char *p1, char *p2, char *p3);
  277. /*
  278.   Purpose:  Looks up a message with parameter substitution into an
  279.             internal buffer and passes it to Desk_Error_Report or Desk_Error_ReportFatal
  280.   Inputs:   filedesc - file descriptor
  281.             token    - token to match
  282.             fatal    - whether to call Desk_Error_Report or Desk_Error_ReportFatal
  283.   Outputs:  -
  284.   Returns:  Pointer to an error block or NULL if successful
  285.   Errors:   As for Desk_MessageTrans_Lookup
  286.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_LookupPS; Desk_MsgTrans_Report; MsgTrans;
  287.             Desk_Error_Report; Desk_Error_ReportFatal
  288. */
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295. int    Desk_MessageTrans_LookupGetSize( 
  296.         Desk_msgtrans_filedesc*    filedesc, 
  297.         const char*        token, 
  298.         const char*        p0, 
  299.         const char*        p1, 
  300.         const char*        p2, 
  301.         const char*        p3
  302.         );
  303. /*
  304. Returns the length of the string that would be generated when 'token' is
  305. expanded with p0-p3. This length excludes the terminating '\0'.
  306.  
  307. At the moment (12 Jun 1996), this works by trying temporary buffer sizes
  308. of 32,64, 128, ... until the returned text doesn't fill the buffer.
  309.  */
  310.  
  311.  
  312. void    Desk_MessageTrans_LookupIntoBuffer( 
  313.         Desk_deskmem_buffer*    buffer,
  314.         Desk_msgtrans_filedesc*    filedesc,
  315.         const char*        token,
  316.         const char*        p0,
  317.         const char*        p1,
  318.         const char*        p2,
  319.         const char*        p3
  320.         );
  321. /*
  322. Expands token into buffer, ensuring buffer is large enough.
  323.  */
  324.  
  325.  
  326. void    Desk_MessageTrans_LookupIntoBufferPos( 
  327.         Desk_deskmem_buffer*    buffer,
  328.         int            pos,
  329.         Desk_msgtrans_filedesc*    filedesc,
  330.         const char*        token,
  331.         const char*        p0,
  332.         const char*        p1,
  333.         const char*        p2,
  334.         const char*        p3
  335.         );
  336. /*
  337. Expands 'token' into 'buffer' starting at pos 'pos', after ensuring
  338. 'buffer' is large enough.
  339.  */
  340.  
  341.  
  342. void    Desk_MessageTrans_LookupIntoBufferCat( 
  343.         Desk_deskmem_buffer*    buffer,
  344.         Desk_msgtrans_filedesc*    filedesc,
  345.         const char*        token,
  346.         const char*        p0,
  347.         const char*        p1,
  348.         const char*        p2,
  349.         const char*        p3
  350.         );
  351. /*
  352. Appends expanded token to end of string in 'buffer'.
  353. */
  354.  
  355.  
  356. void    Desk_MessageTrans_OpenLookupCloseIntoBufferPos( 
  357.         Desk_deskmem_buffer*    buffer,
  358.         int            pos,
  359.         const char*        filename,
  360.         const char*        token,
  361.         const char*        p0,
  362.         const char*        p1,
  363.         const char*        p2,
  364.         const char*        p3
  365.         );
  366. /*
  367. As Desk_MessageTrans_LookupIntoBufferPos, except that the messages file
  368. is opened, the lookup performed, and then closed again.
  369.  */
  370.  
  371.  
  372. void    Desk_MessageTrans_OpenLookupCloseIntoBuffer( 
  373.         Desk_deskmem_buffer*    buffer,
  374.         const char*        filename,
  375.         const char*        token,
  376.         const char*        p0,
  377.         const char*        p1,
  378.         const char*        p2,
  379.         const char*        p3
  380.         );
  381. /*
  382. As Desk_MessageTrans_LookupIntoBuffer, except that the messages file
  383. is opened, the lookup performed, and then closed again.
  384.  */
  385.  
  386.  
  387.  
  388.  
  389. void    Desk_MessageTrans_OpenLookupCloseIntoBufferCat( 
  390.         Desk_deskmem_buffer*    buffer,
  391.         const char*        filename,
  392.         const char*        token,
  393.         const char*        p0,
  394.         const char*        p1,
  395.         const char*        p2,
  396.         const char*        p3
  397.         );
  398. /*
  399. As Desk_MessageTrans_LookupIntoBufferCat, except that the messages file
  400. is opened, the lookup performed, and then closed again.
  401.  */
  402.  
  403.  
  404.  
  405. typedef struct    {
  406.     char*            filename;
  407.     Desk_msgtrans_filedesc*    desc;
  408.     }
  409.     Desk_msgtrans_rmafiledesc;
  410. /*
  411. Used with Desk_MessageTrans_OpenFileRMA and
  412. Desk_MessageTrans_CloseFileRMA.
  413.  
  414. For safety, you should initialise a Desk_msgtrans_rmafiledesc to NULLs
  415. before use. Eg:
  416.  
  417. Desk_msgtrans_rmafiledesc    messages = { NULL, NULL};
  418.  */
  419.  
  420.  
  421. void    Desk_MessageTrans_OpenFileRMA( Desk_msgtrans_rmafiledesc* filedesc, const char* filename);
  422. /*
  423. Opens a message file, instructing MessageTrans to buffer the file
  424. automatically in the RMA. For such use, MessageTrans requires that the
  425. Desk_msgtrans_filedesc and filename are stored in the RMA (see PRMs
  426. 3-743), so 'filename' is copied into a block of RMA, and a
  427. 'Desk_msgtrans_filedesc' is also allocated in the RMA.
  428.  
  429. To use message file, call Desk_MessageTrans_Lookup etc with
  430. 'filedesc->desc'.
  431.  */
  432.  
  433. void    Desk_MessageTrans_CloseFileRMA( Desk_msgtrans_rmafiledesc* filedesc);
  434. /*
  435. Closes and frees all RMA memory associated with 'filedesc'.
  436.  */
  437.  
  438.  
  439.  
  440. #ifdef __cplusplus
  441. }
  442. #endif
  443.  
  444.  
  445. #endif
  446.