dist/ntp/include/isc/msgcat.h

   1 /*      $NetBSD$        */
   2
   3 /*
   4  * Copyright (C) 1999-2001  Internet Software Consortium.
   5  *
   6  * Permission to use, copy, modify, and distribute this software for any
   7  * purpose with or without fee is hereby granted, provided that the above
   8  * copyright notice and this permission notice appear in all copies.
   9  *
  10  * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
  11  * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  12  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  13  * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  15  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  16  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  17  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18  */
  19
  20 /* Id: msgcat.h,v 1.8 2001/01/09 21:57:13 bwelling Exp */
  21
  22 #ifndef ISC_MSGCAT_H
  23 #define ISC_MSGCAT_H 1
  24
  25 /*****
  26  ***** Module Info
  27  *****/
  28
  29 /*
  30  * ISC Message Catalog
  31  *
  32  * Message catalogs aid internationalization of applications by allowing
  33  * messages to be retrieved from locale-specific files instead of
  34  * hardwiring them into the application.  This allows translations of
  35  * messages appropriate to the locale to be supplied without recompiling
  36  * the application.
  37  *
  38  * Notes:
  39  *      It's very important that message catalogs work, even if only the
  40  *      default_text can be used.
  41  *
  42  * MP:
  43  *      The caller must ensure appropriate synchronization of
  44  *      isc_msgcat_open() and isc_msgcat_close().  isc_msgcat_get()
  45  *      ensures appropriate synchronization.
  46  *
  47  * Reliability:
  48  *      No anticipated impact.
  49  *
  50  * Resources:
  51  *      <TBS>
  52  *
  53  * Security:
  54  *      No anticipated impact.
  55  *
  56  * Standards:
  57  *      None.
  58  */
  59
  60 /*****
  61  ***** Imports
  62  *****/
  63
  64 #include <isc/lang.h>
  65 #include <isc/types.h>
  66
  67 ISC_LANG_BEGINDECLS
  68
  69 /*****
  70  ***** Methods
  71  *****/
  72
  73 void
  74 isc_msgcat_open(const char *name, isc_msgcat_t **msgcatp);
  75 /*
  76  * Open a message catalog.
  77  *
  78  * Notes:
  79  *
  80  *      If memory cannot be allocated or other failures occur, *msgcatp
  81  *      will be set to NULL.  If a NULL msgcat is given to isc_msgcat_get(),
  82  *      the default_text will be returned, ensuring that some message text
  83  *      will be available, no matter what's going wrong.
  84  *
  85  * Requires:
  86  *
  87  *      'name' is a valid string.
  88  *
  89  *      msgcatp != NULL && *msgcatp == NULL
  90  */
  91
  92 void
  93 isc_msgcat_close(isc_msgcat_t **msgcatp);
  94 /*
  95  * Close a message catalog.
  96  *
  97  * Notes:
  98  *
  99  *      Any string pointers returned by prior calls to isc_msgcat_get() are
 100  *      invalid after isc_msgcat_close() has been called and must not be
 101  *      used.
 102  *
 103  * Requires:
 104  *
 105  *      *msgcatp is a valid message catalog or is NULL.
 106  *
 107  * Ensures:
 108  *
 109  *      All resources associated with the message catalog are released.
 110  *
 111  *      *msgcatp == NULL
 112  */
 113
 114 const char *
 115 isc_msgcat_get(isc_msgcat_t *msgcat, int set, int message,
 116                const char *default_text);
 117 /*
 118  * Get message 'message' from message set 'set' in 'msgcat'.  If it
 119  * is not available, use 'default_text'.
 120  *
 121  * Requires:
 122  *
 123  *      'msgcat' is a valid message catalog or is NULL.
 124  *
 125  *      set > 0
 126  *
 127  *      message > 0
 128  *
 129  *      'default_text' is a valid string.
 130  */
 131
 132 ISC_LANG_ENDDECLS
 133
 134 #endif /* ISC_MSGCAT_H */