1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 13 #ifndef ISC_MSGCAT_H 14 #define ISC_MSGCAT_H 1 15 16 /***** 17 ***** Module Info 18 *****/ 19 20 /*! \file isc/msgcat.h 21 * \brief The ISC Message Catalog 22 * aids internationalization of applications by allowing 23 * messages to be retrieved from locale-specific files instead of 24 * hardwiring them into the application. This allows translations of 25 * messages appropriate to the locale to be supplied without recompiling 26 * the application. 27 * 28 * Notes: 29 *\li It's very important that message catalogs work, even if only the 30 * default_text can be used. 31 * 32 * MP: 33 *\li The caller must ensure appropriate synchronization of 34 * isc_msgcat_open() and isc_msgcat_close(). isc_msgcat_get() 35 * ensures appropriate synchronization. 36 * 37 * Reliability: 38 *\li No anticipated impact. 39 * 40 * Resources: 41 *\li TBS 42 * 43 * \li Security: 44 * No anticipated impact. 45 * 46 * \li Standards: 47 * None. 48 */ 49 50 /***** 51 ***** Imports 52 *****/ 53 54 #include <isc/lang.h> 55 #include <isc/types.h> 56 57 ISC_LANG_BEGINDECLS 58 59 /***** 60 ***** Methods 61 *****/ 62 63 void 64 isc_msgcat_open(const char *name, isc_msgcat_t **msgcatp); 65 /*%< 66 * Open a message catalog. 67 * 68 * Notes: 69 * 70 *\li If memory cannot be allocated or other failures occur, *msgcatp 71 * will be set to NULL. If a NULL msgcat is given to isc_msgcat_get(), 72 * the default_text will be returned, ensuring that some message text 73 * will be available, no matter what's going wrong. 74 * 75 * Requires: 76 * 77 *\li 'name' is a valid string. 78 * 79 *\li msgcatp != NULL && *msgcatp == NULL 80 */ 81 82 void 83 isc_msgcat_close(isc_msgcat_t **msgcatp); 84 /*%< 85 * Close a message catalog. 86 * 87 * Notes: 88 * 89 *\li Any string pointers returned by prior calls to isc_msgcat_get() are 90 * invalid after isc_msgcat_close() has been called and must not be 91 * used. 92 * 93 * Requires: 94 * 95 *\li *msgcatp is a valid message catalog or is NULL. 96 * 97 * Ensures: 98 * 99 *\li All resources associated with the message catalog are released. 100 * 101 *\li *msgcatp == NULL 102 */ 103 104 const char * 105 isc_msgcat_get(isc_msgcat_t *msgcat, int set, int message, 106 const char *default_text); 107 /*%< 108 * Get message 'message' from message set 'set' in 'msgcat'. If it 109 * is not available, use 'default_text'. 110 * 111 * Requires: 112 * 113 *\li 'msgcat' is a valid message catalog or is NULL. 114 * 115 *\li set > 0 116 * 117 *\li message > 0 118 * 119 *\li 'default_text' is a valid string. 120 */ 121 122 ISC_LANG_ENDDECLS 123 124 #endif /* ISC_MSGCAT_H */ 125