contrib/bind-9.5.2/lib/isc/include/isc/msgcat.h

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