ucat.h File Reference

C API: Message Catalog Wrappers. More...

#include "unicode/utypes.h"
#include "unicode/ures.h"

Go to the source code of this file.

Typedefs
typedef UResourceBundle *	u_nl_catd
	An ICU message catalog descriptor, analogous to nl_catd.

Functions
U_CAPI u_nl_catd	u_catopen (const char *name, const char *locale, UErrorCode *ec)
	Open and return an ICU message catalog descriptor.
U_CAPI void	u_catclose (u_nl_catd catd)
	Close an ICU message catalog, given its descriptor.
U_CAPI const UChar *	u_catgets (u_nl_catd catd, int32_t set_num, int32_t msg_num, const UChar *s, int32_t *len, UErrorCode *ec)
	Retrieve a localized string from an ICU message catalog.

Detailed Description

C API: Message Catalog Wrappers.

This C API provides look-alike functions that deliberately resemble the POSIX catopen, catclose, and catgets functions. The underlying implementation is in terms of ICU resource bundles, rather than POSIX message catalogs.

The ICU resource bundles obey standard ICU inheritance policies. To facilitate this, sets and messages are flattened into one tier. This is done by creating resource bundle keys of the form <set_num>%<msg_num> where set_num is the set number and msg_num is the message number, formatted as decimal strings.

Example: Consider a message catalog containing two sets:

Set 1: Message 4 = "Good morning." Message 5 = "Good afternoon." Message 7 = "Good evening." Message 8 = "Good night." Set 4: Message 14 = "Please " Message 19 = "Thank you." Message 20 = "Sincerely,"

The ICU resource bundle source file would, assuming it is named "greet.txt", would look like this:

greet { 1%4 { "Good morning." } 1%5 { "Good afternoon." } 1%7 { "Good evening." } 1%8 { "Good night." }

4%14 { "Please " } 4%19 { "Thank you." } 4%20 { "Sincerely," } }

The catgets function is commonly used in combination with functions like printf and strftime. ICU components like message format can be used instead, although they use a different format syntax. There is an ICU package, icuio, that provides some of the POSIX-style formatting API.

Definition in file ucat.h.

Typedef Documentation

u_nl_catd

typedef UResourceBundle* u_nl_catd

An ICU message catalog descriptor, analogous to nl_catd.

Stable:

ICU 2.6

Definition at line 73 of file ucat.h.

Function Documentation

u_catclose()

U_CAPI void u_catclose

(

u_nl_catd

catd

)

Close an ICU message catalog, given its descriptor.

Parameters

catd	a message catalog descriptor to be closed. May be NULL, in which case no action is taken.

Stable:

ICU 2.6

u_catgets()

U_CAPI const UChar * u_catgets	(	u_nl_catd	catd,
		int32_t	set_num,
		int32_t	msg_num,
		const UChar *	s,
		int32_t *	len,
		UErrorCode *	ec
	)

Retrieve a localized string from an ICU message catalog.

Parameters

catd	a message catalog descriptor returned by u_catopen.
set_num	the message catalog set number. Sets need not be numbered consecutively.
msg_num	the message catalog message number within the set. Messages need not be numbered consecutively.
s	the default string. This is returned if the string specified by the set_num and msg_num is not found. It must be zero-terminated.
len	fill-in parameter to receive the length of the result. May be NULL, in which case it is ignored.
ec	input/output error code. May be U_USING_FALLBACK_WARNING or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that the set_num/msg_num tuple does not specify a valid message string in this catalog.

Returns

a pointer to a zero-terminated UChar array which lives in an internal buffer area, typically a memory mapped/DLL file. The caller must NOT delete this pointer. If the call is unsuccessful for any reason, then s is returned. This includes the situation in which ec indicates a failing error code upon entry to this function.

Stable:

ICU 2.6

u_catopen()

U_CAPI u_nl_catd u_catopen	(	const char *	name,
		const char *	locale,
		UErrorCode *	ec
	)

Open and return an ICU message catalog descriptor.

The descriptor may be passed to u_catgets() to retrieve localized strings.

Parameters

name	string containing the full path pointing to the directory where the resources reside followed by the package name e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. If NULL, ICU default data files will be used.

Unlike POSIX, environment variables are not interpolated within the name.

Parameters

locale	the locale for which we want to open the resource. If NULL, the default ICU locale will be used (see uloc_getDefault). If strlen(locale) == 0, the root locale will be used.
ec	input/output error code. Upon output, U_USING_FALLBACK_WARNING indicates that a fallback locale was used. For example, 'de_CH' was requested, but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the default locale data or root locale data was used; neither the requested locale nor any of its fallback locales were found.

Returns

a message catalog descriptor that may be passed to u_catgets(). If the ec parameter indicates success, then the caller is responsible for calling u_catclose() to close the message catalog. If the ec parameter indicates failure, then NULL will be returned.

Stable:

ICU 2.6