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