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
66U_CDECL_BEGIN
67
68/**
69 * An ICU message catalog descriptor, analogous to nl_catd.
70 *
71 * @stable ICU 2.6
72 */
73typedef 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 */
106U_STABLE u_nl_catd U_EXPORT2
107u_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 */
117U_STABLE void U_EXPORT2
118u_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 */
152U_STABLE const UChar* U_EXPORT2
153u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,
154 const UChar* s,
155 int32_t* len, UErrorCode* ec);
156
157U_CDECL_END
158
159#endif /*UCAT_H*/
160/*eof*/
161