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