1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 **********************************************************************
5 * Copyright (c) 2003-2004, International Business Machines
6 * Corporation and others.  All Rights Reserved.
7 **********************************************************************
8 * Author: Alan Liu
9 * Created: March 19 2003
10 * Since: ICU 2.6
11 **********************************************************************
12 */
13 #ifndef UCAT_H
14 #define UCAT_H
15 
16 #include "unicode/utypes.h"
17 #include "unicode/ures.h"
18 
19 /**
20  * \file
21  * \brief C API: Message Catalog Wrappers
22  *
23  * This C API provides look-alike functions that deliberately resemble
24  * the POSIX catopen, catclose, and catgets functions.  The underlying
25  * implementation is in terms of ICU resource bundles, rather than
26  * POSIX message catalogs.
27  *
28  * The ICU resource bundles obey standard ICU inheritance policies.
29  * To facilitate this, sets and messages are flattened into one tier.
30  * This is done by creating resource bundle keys of the form
31  * <set_num>%<msg_num> where set_num is the set number and msg_num is
32  * the message number, formatted as decimal strings.
33  *
34  * Example:  Consider a message catalog containing two sets:
35  *
36  * Set 1: Message 4  = "Good morning."
37  *        Message 5  = "Good afternoon."
38  *        Message 7  = "Good evening."
39  *        Message 8  = "Good night."
40  * Set 4: Message 14 = "Please "
41  *        Message 19 = "Thank you."
42  *        Message 20 = "Sincerely,"
43  *
44  * The ICU resource bundle source file would, assuming it is named
45  * "greet.txt", would look like this:
46  *
47  * greet
48  * {
49  *     1%4  { "Good morning." }
50  *     1%5  { "Good afternoon." }
51  *     1%7  { "Good evening." }
52  *     1%8  { "Good night." }
53  *
54  *     4%14 { "Please " }
55  *     4%19 { "Thank you." }
56  *     4%20 { "Sincerely," }
57  * }
58  *
59  * The catgets function is commonly used in combination with functions
60  * like printf and strftime.  ICU components like message format can
61  * be used instead, although they use a different format syntax.
62  * There is an ICU package, icuio, that provides some of
63  * the POSIX-style formatting API.
64  */
65 
66 U_CDECL_BEGIN
67 
68 /**
69  * An ICU message catalog descriptor, analogous to nl_catd.
70  *
71  * @stable ICU 2.6
72  */
73 typedef UResourceBundle* u_nl_catd;
74 
75 /**
76  * Open and return an ICU message catalog descriptor. The descriptor
77  * may be passed to u_catgets() to retrieve localized strings.
78  *
79  * @param name string containing the full path pointing to the
80  * directory where the resources reside followed by the package name
81  * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
82  * If NULL, ICU default data files will be used.
83  *
84  * Unlike POSIX, environment variables are not interpolated within the
85  * name.
86  *
87  * @param locale the locale for which we want to open the resource. If
88  * NULL, the default ICU locale will be used (see uloc_getDefault). If
89  * strlen(locale) == 0, the root locale will be used.
90  *
91  * @param ec input/output error code. Upon output,
92  * U_USING_FALLBACK_WARNING indicates that a fallback locale was
93  * used. For example, 'de_CH' was requested, but nothing was found
94  * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the
95  * default locale data or root locale data was used; neither the
96  * requested locale nor any of its fallback locales were found.
97  *
98  * @return a message catalog descriptor that may be passed to
99  * u_catgets(). If the ec parameter indicates success, then the caller
100  * is responsible for calling u_catclose() to close the message
101  * catalog. If the ec parameter indicates failure, then NULL will be
102  * returned.
103  *
104  * @stable ICU 2.6
105  */
106 U_CAPI u_nl_catd U_EXPORT2
107 u_catopen(const char* name, const char* locale, UErrorCode* ec);
108 
109 /**
110  * Close an ICU message catalog, given its descriptor.
111  *
112  * @param catd a message catalog descriptor to be closed. May be NULL,
113  * in which case no action is taken.
114  *
115  * @stable ICU 2.6
116  */
117 U_CAPI void U_EXPORT2
118 u_catclose(u_nl_catd catd);
119 
120 /**
121  * Retrieve a localized string from an ICU message catalog.
122  *
123  * @param catd a message catalog descriptor returned by u_catopen.
124  *
125  * @param set_num the message catalog set number. Sets need not be
126  * numbered consecutively.
127  *
128  * @param msg_num the message catalog message number within the
129  * set. Messages need not be numbered consecutively.
130  *
131  * @param s the default string. This is returned if the string
132  * specified by the set_num and msg_num is not found. It must be
133  * zero-terminated.
134  *
135  * @param len fill-in parameter to receive the length of the result.
136  * May be NULL, in which case it is ignored.
137  *
138  * @param ec input/output error code. May be U_USING_FALLBACK_WARNING
139  * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that
140  * the set_num/msg_num tuple does not specify a valid message string
141  * in this catalog.
142  *
143  * @return a pointer to a zero-terminated UChar array which lives in
144  * an internal buffer area, typically a memory mapped/DLL file. The
145  * caller must NOT delete this pointer. If the call is unsuccessful
146  * for any reason, then s is returned.  This includes the situation in
147  * which ec indicates a failing error code upon entry to this
148  * function.
149  *
150  * @stable ICU 2.6
151  */
152 U_CAPI const UChar* U_EXPORT2
153 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,
154           const UChar* s,
155           int32_t* len, UErrorCode* ec);
156 
157 U_CDECL_END
158 
159 #endif /*UCAT_H*/
160 /*eof*/
161