summaryrefslogtreecommitdiffstats
path: root/intl/icu/source/common/unicode/ures.h
blob: 620d9268aaceeb4bf678beacec8e004adc18d67d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
**********************************************************************
*   Copyright (C) 1997-2016, International Business Machines
*   Corporation and others.  All Rights Reserved.
**********************************************************************
*
* File URES.H (formerly CRESBUND.H)
*
* Modification History:
*
*   Date        Name        Description
*   04/01/97    aliu        Creation.
*   02/22/99    damiba      overhaul.
*   04/04/99    helena      Fixed internal header inclusion.
*   04/15/99    Madhu       Updated Javadoc
*   06/14/99    stephen     Removed functions taking a filename suffix.
*   07/20/99    stephen     Language-independent ypedef to void*
*   11/09/99    weiv        Added ures_getLocale()
*   06/24/02    weiv        Added support for resource sharing
******************************************************************************
*/

#ifndef URES_H
#define URES_H

#include "unicode/utypes.h"
#include "unicode/uloc.h"
#include "unicode/localpointer.h"

/**
 * \file
 * \brief C API: Resource Bundle
 *
 * <h2>C API: Resource Bundle</h2>
 *
 * C API representing a collection of resource information pertaining to a given
 * locale. A resource bundle provides a way of accessing locale- specific information in
 * a data file. You create a resource bundle that manages the resources for a given
 * locale and then ask it for individual resources.
 * <P>
 * Resource bundles in ICU4C are currently defined using text files which conform to the following
 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
 * More on resource bundle concepts and syntax can be found in the
 * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
 * <P>
 */

/**
 * UResourceBundle is an opaque type for handles for resource bundles in C APIs.
 * @stable ICU 2.0
 */
struct UResourceBundle;

/**
 * @stable ICU 2.0
 */
typedef struct UResourceBundle UResourceBundle;

/**
 * Numeric constants for types of resource items.
 * @see ures_getType
 * @stable ICU 2.0
 */
typedef enum {
    /** Resource type constant for "no resource". @stable ICU 2.6 */
    URES_NONE=-1,

    /** Resource type constant for 16-bit Unicode strings. @stable ICU 2.6 */
    URES_STRING=0,

    /** Resource type constant for binary data. @stable ICU 2.6 */
    URES_BINARY=1,

    /** Resource type constant for tables of key-value pairs. @stable ICU 2.6 */
    URES_TABLE=2,

    /**
     * Resource type constant for aliases;
     * internally stores a string which identifies the actual resource
     * storing the data (can be in a different resource bundle).
     * Resolved internally before delivering the actual resource through the API.
     * @stable ICU 2.6
     */
    URES_ALIAS=3,

    /**
     * Resource type constant for a single 28-bit integer, interpreted as
     * signed or unsigned by the ures_getInt() or ures_getUInt() function.
     * @see ures_getInt
     * @see ures_getUInt
     * @stable ICU 2.6
     */
    URES_INT=7,

    /** Resource type constant for arrays of resources. @stable ICU 2.6 */
    URES_ARRAY=8,

    /**
     * Resource type constant for vectors of 32-bit integers.
     * @see ures_getIntVector
     * @stable ICU 2.6
     */
    URES_INT_VECTOR = 14,
#ifndef U_HIDE_DEPRECATED_API
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_NONE=URES_NONE,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_STRING=URES_STRING,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_BINARY=URES_BINARY,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_TABLE=URES_TABLE,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_ALIAS=URES_ALIAS,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_INT=URES_INT,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_ARRAY=URES_ARRAY,
    /** @deprecated ICU 2.6 Use the URES_ constant instead. */
    RES_INT_VECTOR=URES_INT_VECTOR,
    /** @deprecated ICU 2.6 Not used. */
    RES_RESERVED=15,

    /**
     * One more than the highest normal UResType value.
     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
     */
    URES_LIMIT = 16
#endif  // U_HIDE_DEPRECATED_API
} UResType;

/*
 * Functions to create and destroy resource bundles.
 */

/**
 * Opens a UResourceBundle, from which users can extract strings by using
 * their corresponding keys.
 * Note that the caller is responsible of calling <TT>ures_close</TT> on each succesfully
 * opened resource bundle.
 * @param packageName   The packageName and locale together point to an ICU udata object,
 *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
 *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
 *                      a package registered with udata_setAppData(). Using a full file or directory
 *                      pathname for packageName is deprecated. If NULL, ICU data will be used.
 * @param locale  specifies the locale for which we want to open the resource
 *                if NULL, the default locale will be used. If strlen(locale) == 0
 *                root locale will be used.
 *
 * @param status  fills in the outgoing error code.
 * The UErrorCode err parameter is used to return status information to the user. To
 * check whether the construction succeeded or not, you should check the value of
 * U_SUCCESS(err). If you wish more detailed information, you can check for
 * informational status results which still indicate success. U_USING_FALLBACK_WARNING
 * indicates that a fall back 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 fall back locales could be found. Please see the users guide for more
 * information on this topic.
 * @return      a newly allocated resource bundle.
 * @see ures_close
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle*  U_EXPORT2
ures_open(const char*    packageName,
          const char*  locale,
          UErrorCode*     status);


/** This function does not care what kind of localeID is passed in. It simply opens a bundle with
 *  that name. Fallback mechanism is disabled for the new bundle. If the requested bundle contains
 *  an %%ALIAS directive, the results are undefined.
 * @param packageName   The packageName and locale together point to an ICU udata object,
 *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
 *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
 *                      a package registered with udata_setAppData(). Using a full file or directory
 *                      pathname for packageName is deprecated. If NULL, ICU data will be used.
 * @param locale  specifies the locale for which we want to open the resource
 *                if NULL, the default locale will be used. If strlen(locale) == 0
 *                root locale will be used.
 *
 * @param status fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR
 * @return      a newly allocated resource bundle or NULL if it doesn't exist.
 * @see ures_close
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle* U_EXPORT2
ures_openDirect(const char* packageName,
                const char* locale,
                UErrorCode* status);

/**
 * Same as ures_open() but takes a const UChar *path.
 * This path will be converted to char * using the default converter,
 * then ures_open() is called.
 *
 * @param packageName   The packageName and locale together point to an ICU udata object,
 *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
 *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
 *                      a package registered with udata_setAppData(). Using a full file or directory
 *                      pathname for packageName is deprecated. If NULL, ICU data will be used.
 * @param locale  specifies the locale for which we want to open the resource
 *                if NULL, the default locale will be used. If strlen(locale) == 0
 *                root locale will be used.
 * @param status  fills in the outgoing error code.
 * @return      a newly allocated resource bundle.
 * @see ures_open
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle* U_EXPORT2
ures_openU(const UChar* packageName,
           const char* locale,
           UErrorCode* status);

#ifndef U_HIDE_DEPRECATED_API
/**
 * Returns the number of strings/arrays in resource bundles.
 * Better to use ures_getSize, as this function will be deprecated.
 *
 *@param resourceBundle resource bundle containing the desired strings
 *@param resourceKey key tagging the resource
 *@param err fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_FALLBACK_WARNING </TT>
 *@return: for    <STRONG>Arrays</STRONG>: returns the number of resources in the array
 *                <STRONG>Tables</STRONG>: returns the number of resources in the table
 *                <STRONG>single string</STRONG>: returns 1
 *@see ures_getSize
 * @deprecated ICU 2.8 User ures_getSize instead
 */
U_DEPRECATED int32_t U_EXPORT2
ures_countArrayItems(const UResourceBundle* resourceBundle,
                     const char* resourceKey,
                     UErrorCode* err);
#endif  /* U_HIDE_DEPRECATED_API */

/**
 * Close a resource bundle, all pointers returned from the various ures_getXXX calls
 * on this particular bundle should be considered invalid henceforth.
 *
 * @param resourceBundle a pointer to a resourceBundle struct. Can be NULL.
 * @see ures_open
 * @stable ICU 2.0
 */
U_STABLE void U_EXPORT2
ures_close(UResourceBundle* resourceBundle);

#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

/**
 * \class LocalUResourceBundlePointer
 * "Smart pointer" class, closes a UResourceBundle via ures_close().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 4.4
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUResourceBundlePointer, UResourceBundle, ures_close);

U_NAMESPACE_END

#endif

#ifndef U_HIDE_DEPRECATED_API
/**
 * Return the version number associated with this ResourceBundle as a string. Please
 * use ures_getVersion as this function is going to be deprecated.
 *
 * @param resourceBundle The resource bundle for which the version is checked.
 * @return  A version number string as specified in the resource bundle or its parent.
 *          The caller does not own this string.
 * @see ures_getVersion
 * @deprecated ICU 2.8 Use ures_getVersion instead.
 */
U_DEPRECATED const char* U_EXPORT2
ures_getVersionNumber(const UResourceBundle*   resourceBundle);
#endif  /* U_HIDE_DEPRECATED_API */

/**
 * Return the version number associated with this ResourceBundle as an
 * UVersionInfo array.
 *
 * @param resB The resource bundle for which the version is checked.
 * @param versionInfo A UVersionInfo array that is filled with the version number
 *                    as specified in the resource bundle or its parent.
 * @stable ICU 2.0
 */
U_STABLE void U_EXPORT2
ures_getVersion(const UResourceBundle* resB,
                UVersionInfo versionInfo);

#ifndef U_HIDE_DEPRECATED_API
/**
 * Return the name of the Locale associated with this ResourceBundle. This API allows
 * you to query for the real locale of the resource. For example, if you requested
 * "en_US_CALIFORNIA" and only "en_US" bundle exists, "en_US" will be returned.
 * For subresources, the locale where this resource comes from will be returned.
 * If fallback has occured, getLocale will reflect this.
 *
 * @param resourceBundle resource bundle in question
 * @param status just for catching illegal arguments
 * @return  A Locale name
 * @deprecated ICU 2.8 Use ures_getLocaleByType instead.
 */
U_DEPRECATED const char* U_EXPORT2
ures_getLocale(const UResourceBundle* resourceBundle,
               UErrorCode* status);
#endif  /* U_HIDE_DEPRECATED_API */

/**
 * Return the name of the Locale associated with this ResourceBundle.
 * You can choose between requested, valid and real locale.
 *
 * @param resourceBundle resource bundle in question
 * @param type You can choose between requested, valid and actual
 *             locale. For description see the definition of
 *             ULocDataLocaleType in uloc.h
 * @param status just for catching illegal arguments
 * @return  A Locale name
 * @stable ICU 2.8
 */
U_STABLE const char* U_EXPORT2
ures_getLocaleByType(const UResourceBundle* resourceBundle,
                     ULocDataLocaleType type,
                     UErrorCode* status);


#ifndef U_HIDE_INTERNAL_API
/**
 * Same as ures_open() but uses the fill-in parameter instead of allocating
 * a bundle, if r!=NULL.
 * TODO need to revisit usefulness of this function
 *      and usage model for fillIn parameters without knowing sizeof(UResourceBundle)
 * @param r The resourcebundle to open
 * @param packageName   The packageName and locale together point to an ICU udata object,
 *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
 *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
 *                      a package registered with udata_setAppData(). Using a full file or directory
 *                      pathname for packageName is deprecated. If NULL, ICU data will be used.
 * @param localeID specifies the locale for which we want to open the resource
 * @param status The error code
 * @return a newly allocated resource bundle or NULL if it doesn't exist.
 * @internal
 */
U_INTERNAL void U_EXPORT2
ures_openFillIn(UResourceBundle *r,
                const char* packageName,
                const char* localeID,
                UErrorCode* status);
#endif  /* U_HIDE_INTERNAL_API */

/**
 * Returns a string from a string resource type
 *
 * @param resourceBundle a string resource
 * @param len    fills in the length of resulting string
 * @param status fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                Always check the value of status. Don't count on returning NULL.
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 * @see ures_getBinary
 * @see ures_getIntVector
 * @see ures_getInt
 * @see ures_getUInt
 * @stable ICU 2.0
 */
U_STABLE const UChar* U_EXPORT2
ures_getString(const UResourceBundle* resourceBundle,
               int32_t* len,
               UErrorCode* status);

/**
 * Returns a UTF-8 string from a string resource.
 * The UTF-8 string may be returnable directly as a pointer, or
 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
 * or equivalent.
 *
 * If forceCopy==TRUE, then the string is always written to the dest buffer
 * and dest is returned.
 *
 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
 * without needing a dest buffer (it can be NULL). If the string needs to be
 * copied or transformed, then it may be placed into dest at an arbitrary offset.
 *
 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
 *
 * If the string is transformed from UTF-16, then a conversion error may occur
 * if an unpaired surrogate is encountered. If the function is successful, then
 * the output UTF-8 string is always well-formed.
 *
 * @param resB Resource bundle.
 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
 * @param length Input: Capacity of destination buffer.
 *               Output: Actual length of the UTF-8 string, not counting the
 *               terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
 *               Can be NULL, meaning capacity=0 and the string length is not
 *               returned to the caller.
 * @param forceCopy If TRUE, then the output string will always be written to
 *                  dest, with U_BUFFER_OVERFLOW_ERROR and
 *                  U_STRING_NOT_TERMINATED_WARNING set if appropriate.
 *                  If FALSE, then the dest buffer may or may not contain a
 *                  copy of the string. dest may or may not be modified.
 *                  If a copy needs to be written, then the UErrorCode parameter
 *                  indicates overflow etc. as usual.
 * @param status Pointer to a standard ICU error code. Its input value must
 *               pass the U_SUCCESS() test, or else the function returns
 *               immediately. Check for U_FAILURE() on output or use with
 *               function chaining. (See User Guide for details.)
 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
 *         from dest (only if !forceCopy), or in unrelated memory.
 *         Always NUL-terminated unless the string was written to dest and
 *         length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
 *
 * @see ures_getString
 * @see u_strToUTF8
 * @stable ICU 3.6
 */
U_STABLE const char * U_EXPORT2
ures_getUTF8String(const UResourceBundle *resB,
                   char *dest, int32_t *length,
                   UBool forceCopy,
                   UErrorCode *status);

/**
 * Returns a binary data from a binary resource.
 *
 * @param resourceBundle a string resource
 * @param len    fills in the length of resulting byte chunk
 * @param status fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                Always check the value of status. Don't count on returning NULL.
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
 * @see ures_getString
 * @see ures_getIntVector
 * @see ures_getInt
 * @see ures_getUInt
 * @stable ICU 2.0
 */
U_STABLE const uint8_t* U_EXPORT2
ures_getBinary(const UResourceBundle* resourceBundle,
               int32_t* len,
               UErrorCode* status);

/**
 * Returns a 32 bit integer array from a resource.
 *
 * @param resourceBundle an int vector resource
 * @param len    fills in the length of resulting byte chunk
 * @param status fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                Always check the value of status. Don't count on returning NULL.
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return a pointer to a chunk of integers which live in a memory mapped/DLL file.
 * @see ures_getBinary
 * @see ures_getString
 * @see ures_getInt
 * @see ures_getUInt
 * @stable ICU 2.0
 */
U_STABLE const int32_t* U_EXPORT2
ures_getIntVector(const UResourceBundle* resourceBundle,
                  int32_t* len,
                  UErrorCode* status);

/**
 * Returns an unsigned integer from a resource.
 * This integer is originally 28 bits.
 *
 * @param resourceBundle a string resource
 * @param status fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return an integer value
 * @see ures_getInt
 * @see ures_getIntVector
 * @see ures_getBinary
 * @see ures_getString
 * @stable ICU 2.0
 */
U_STABLE uint32_t U_EXPORT2
ures_getUInt(const UResourceBundle* resourceBundle,
             UErrorCode *status);

/**
 * Returns a signed integer from a resource.
 * This integer is originally 28 bit and the sign gets propagated.
 *
 * @param resourceBundle a string resource
 * @param status  fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return an integer value
 * @see ures_getUInt
 * @see ures_getIntVector
 * @see ures_getBinary
 * @see ures_getString
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
ures_getInt(const UResourceBundle* resourceBundle,
            UErrorCode *status);

/**
 * Returns the size of a resource. Size for scalar types is always 1,
 * and for vector/table types is the number of child resources.
 * @warning Integer array is treated as a scalar type. There are no
 *          APIs to access individual members of an integer array. It
 *          is always returned as a whole.
 * @param resourceBundle a resource
 * @return number of resources in a given resource.
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
ures_getSize(const UResourceBundle *resourceBundle);

/**
 * Returns the type of a resource. Available types are defined in enum UResType
 *
 * @param resourceBundle a resource
 * @return type of the given resource.
 * @see UResType
 * @stable ICU 2.0
 */
U_STABLE UResType U_EXPORT2
ures_getType(const UResourceBundle *resourceBundle);

/**
 * Returns the key associated with a given resource. Not all the resources have a key - only
 * those that are members of a table.
 *
 * @param resourceBundle a resource
 * @return a key associated to this resource, or NULL if it doesn't have a key
 * @stable ICU 2.0
 */
U_STABLE const char * U_EXPORT2
ures_getKey(const UResourceBundle *resourceBundle);

/* ITERATION API
    This API provides means for iterating through a resource
*/

/**
 * Resets the internal context of a resource so that iteration starts from the first element.
 *
 * @param resourceBundle a resource
 * @stable ICU 2.0
 */
U_STABLE void U_EXPORT2
ures_resetIterator(UResourceBundle *resourceBundle);

/**
 * Checks whether the given resource has another element to iterate over.
 *
 * @param resourceBundle a resource
 * @return TRUE if there are more elements, FALSE if there is no more elements
 * @stable ICU 2.0
 */
U_STABLE UBool U_EXPORT2
ures_hasNext(const UResourceBundle *resourceBundle);

/**
 * Returns the next resource in a given resource or NULL if there are no more resources
 * to iterate over. Features a fill-in parameter.
 *
 * @param resourceBundle    a resource
 * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
 *                          Alternatively, you can supply a struct to be filled by this function.
 * @param status            fills in the outgoing error code. You may still get a non NULL result even if an
 *                          error occured. Check status instead.
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle* U_EXPORT2
ures_getNextResource(UResourceBundle *resourceBundle,
                     UResourceBundle *fillIn,
                     UErrorCode *status);

/**
 * Returns the next string in a given resource or NULL if there are no more resources
 * to iterate over.
 *
 * @param resourceBundle    a resource
 * @param len               fill in length of the string
 * @param key               fill in for key associated with this string. NULL if no key
 * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 *                          count on it. Check status instead!
 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 * @stable ICU 2.0
 */
U_STABLE const UChar* U_EXPORT2
ures_getNextString(UResourceBundle *resourceBundle,
                   int32_t* len,
                   const char ** key,
                   UErrorCode *status);

/**
 * Returns the resource in a given resource at the specified index. Features a fill-in parameter.
 *
 * @param resourceBundle    the resource bundle from which to get a sub-resource
 * @param indexR            an index to the wanted resource.
 * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
 *                          Alternatively, you can supply a struct to be filled by this function.
 * @param status            fills in the outgoing error code. Don't count on NULL being returned if an error has
 *                          occured. Check status instead.
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle* U_EXPORT2
ures_getByIndex(const UResourceBundle *resourceBundle,
                int32_t indexR,
                UResourceBundle *fillIn,
                UErrorCode *status);

/**
 * Returns the string in a given resource at the specified index.
 *
 * @param resourceBundle    a resource
 * @param indexS            an index to the wanted string.
 * @param len               fill in length of the string
 * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 *                          count on it. Check status instead!
 * @return                  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 * @stable ICU 2.0
 */
U_STABLE const UChar* U_EXPORT2
ures_getStringByIndex(const UResourceBundle *resourceBundle,
                      int32_t indexS,
                      int32_t* len,
                      UErrorCode *status);

/**
 * Returns a UTF-8 string from a resource at the specified index.
 * The UTF-8 string may be returnable directly as a pointer, or
 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
 * or equivalent.
 *
 * If forceCopy==TRUE, then the string is always written to the dest buffer
 * and dest is returned.
 *
 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
 * without needing a dest buffer (it can be NULL). If the string needs to be
 * copied or transformed, then it may be placed into dest at an arbitrary offset.
 *
 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
 *
 * If the string is transformed from UTF-16, then a conversion error may occur
 * if an unpaired surrogate is encountered. If the function is successful, then
 * the output UTF-8 string is always well-formed.
 *
 * @param resB Resource bundle.
 * @param stringIndex An index to the wanted string.
 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
 * @param pLength Input: Capacity of destination buffer.
 *               Output: Actual length of the UTF-8 string, not counting the
 *               terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
 *               Can be NULL, meaning capacity=0 and the string length is not
 *               returned to the caller.
 * @param forceCopy If TRUE, then the output string will always be written to
 *                  dest, with U_BUFFER_OVERFLOW_ERROR and
 *                  U_STRING_NOT_TERMINATED_WARNING set if appropriate.
 *                  If FALSE, then the dest buffer may or may not contain a
 *                  copy of the string. dest may or may not be modified.
 *                  If a copy needs to be written, then the UErrorCode parameter
 *                  indicates overflow etc. as usual.
 * @param status Pointer to a standard ICU error code. Its input value must
 *               pass the U_SUCCESS() test, or else the function returns
 *               immediately. Check for U_FAILURE() on output or use with
 *               function chaining. (See User Guide for details.)
 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
 *         from dest (only if !forceCopy), or in unrelated memory.
 *         Always NUL-terminated unless the string was written to dest and
 *         length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
 *
 * @see ures_getStringByIndex
 * @see u_strToUTF8
 * @stable ICU 3.6
 */
U_STABLE const char * U_EXPORT2
ures_getUTF8StringByIndex(const UResourceBundle *resB,
                          int32_t stringIndex,
                          char *dest, int32_t *pLength,
                          UBool forceCopy,
                          UErrorCode *status);

/**
 * Returns a resource in a given resource that has a given key. This procedure works only with table
 * resources. Features a fill-in parameter.
 *
 * @param resourceBundle    a resource
 * @param key               a key associated with the wanted resource
 * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
 *                          Alternatively, you can supply a struct to be filled by this function.
 * @param status            fills in the outgoing error code.
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
 * @stable ICU 2.0
 */
U_STABLE UResourceBundle* U_EXPORT2
ures_getByKey(const UResourceBundle *resourceBundle,
              const char* key,
              UResourceBundle *fillIn,
              UErrorCode *status);

/**
 * Returns a string in a given resource that has a given key. This procedure works only with table
 * resources.
 *
 * @param resB              a resource
 * @param key               a key associated with the wanted string
 * @param len               fill in length of the string
 * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 *                          count on it. Check status instead!
 * @return                  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 * @stable ICU 2.0
 */
U_STABLE const UChar* U_EXPORT2
ures_getStringByKey(const UResourceBundle *resB,
                    const char* key,
                    int32_t* len,
                    UErrorCode *status);

/**
 * Returns a UTF-8 string from a resource and a key.
 * This function works only with table resources.
 *
 * The UTF-8 string may be returnable directly as a pointer, or
 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
 * or equivalent.
 *
 * If forceCopy==TRUE, then the string is always written to the dest buffer
 * and dest is returned.
 *
 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
 * without needing a dest buffer (it can be NULL). If the string needs to be
 * copied or transformed, then it may be placed into dest at an arbitrary offset.
 *
 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
 *
 * If the string is transformed from UTF-16, then a conversion error may occur
 * if an unpaired surrogate is encountered. If the function is successful, then
 * the output UTF-8 string is always well-formed.
 *
 * @param resB Resource bundle.
 * @param key  A key associated with the wanted resource
 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
 * @param pLength Input: Capacity of destination buffer.
 *               Output: Actual length of the UTF-8 string, not counting the
 *               terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
 *               Can be NULL, meaning capacity=0 and the string length is not
 *               returned to the caller.
 * @param forceCopy If TRUE, then the output string will always be written to
 *                  dest, with U_BUFFER_OVERFLOW_ERROR and
 *                  U_STRING_NOT_TERMINATED_WARNING set if appropriate.
 *                  If FALSE, then the dest buffer may or may not contain a
 *                  copy of the string. dest may or may not be modified.
 *                  If a copy needs to be written, then the UErrorCode parameter
 *                  indicates overflow etc. as usual.
 * @param status Pointer to a standard ICU error code. Its input value must
 *               pass the U_SUCCESS() test, or else the function returns
 *               immediately. Check for U_FAILURE() on output or use with
 *               function chaining. (See User Guide for details.)
 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
 *         from dest (only if !forceCopy), or in unrelated memory.
 *         Always NUL-terminated unless the string was written to dest and
 *         length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
 *
 * @see ures_getStringByKey
 * @see u_strToUTF8
 * @stable ICU 3.6
 */
U_STABLE const char * U_EXPORT2
ures_getUTF8StringByKey(const UResourceBundle *resB,
                        const char *key,
                        char *dest, int32_t *pLength,
                        UBool forceCopy,
                        UErrorCode *status);

#if U_SHOW_CPLUSPLUS_API
#include "unicode/unistr.h"

U_NAMESPACE_BEGIN
/**
 * Returns the string value from a string resource bundle.
 *
 * @param resB    a resource, should have type URES_STRING
 * @param status: fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return The string value, or a bogus string if there is a failure UErrorCode.
 * @stable ICU 2.0
 */
inline UnicodeString
ures_getUnicodeString(const UResourceBundle *resB, UErrorCode* status) {
    UnicodeString result;
    int32_t len = 0;
    const UChar *r = ures_getString(resB, &len, status);
    if(U_SUCCESS(*status)) {
        result.setTo(TRUE, r, len);
    } else {
        result.setToBogus();
    }
    return result;
}

/**
 * Returns the next string in a resource, or an empty string if there are no more resources
 * to iterate over.
 * Use ures_getNextString() instead to distinguish between
 * the end of the iteration and a real empty string value.
 *
 * @param resB              a resource
 * @param key               fill in for key associated with this string
 * @param status            fills in the outgoing error code
 * @return The string value, or a bogus string if there is a failure UErrorCode.
 * @stable ICU 2.0
 */
inline UnicodeString
ures_getNextUnicodeString(UResourceBundle *resB, const char ** key, UErrorCode* status) {
    UnicodeString result;
    int32_t len = 0;
    const UChar* r = ures_getNextString(resB, &len, key, status);
    if(U_SUCCESS(*status)) {
        result.setTo(TRUE, r, len);
    } else {
        result.setToBogus();
    }
    return result;
}

/**
 * Returns the string in a given resource array or table at the specified index.
 *
 * @param resB              a resource
 * @param indexS            an index to the wanted string.
 * @param status            fills in the outgoing error code
 * @return The string value, or a bogus string if there is a failure UErrorCode.
 * @stable ICU 2.0
 */
inline UnicodeString
ures_getUnicodeStringByIndex(const UResourceBundle *resB, int32_t indexS, UErrorCode* status) {
    UnicodeString result;
    int32_t len = 0;
    const UChar* r = ures_getStringByIndex(resB, indexS, &len, status);
    if(U_SUCCESS(*status)) {
        result.setTo(TRUE, r, len);
    } else {
        result.setToBogus();
    }
    return result;
}

/**
 * Returns a string in a resource that has a given key.
 * This procedure works only with table resources.
 *
 * @param resB              a resource
 * @param key               a key associated with the wanted string
 * @param status            fills in the outgoing error code
 * @return The string value, or a bogus string if there is a failure UErrorCode.
 * @stable ICU 2.0
 */
inline UnicodeString
ures_getUnicodeStringByKey(const UResourceBundle *resB, const char* key, UErrorCode* status) {
    UnicodeString result;
    int32_t len = 0;
    const UChar* r = ures_getStringByKey(resB, key, &len, status);
    if(U_SUCCESS(*status)) {
        result.setTo(TRUE, r, len);
    } else {
        result.setToBogus();
    }
    return result;
}

U_NAMESPACE_END

#endif

/**
 * Create a string enumerator, owned by the caller, of all locales located within
 * the specified resource tree.
 * @param packageName name of the tree, such as (NULL) or U_ICUDATA_ALIAS or  or "ICUDATA-coll"
 * This call is similar to uloc_getAvailable().
 * @param status error code
 * @stable ICU 3.2
 */
U_STABLE UEnumeration* U_EXPORT2
ures_openAvailableLocales(const char *packageName, UErrorCode *status);


#endif /*_URES*/
/*eof*/