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