Tizen Native API  6.5

Ures module provides API for Resource Bundle.

Required Header

#include <utils_i18n.h>

Overview

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.

Resource bundles in ICU4C are currently defined using text files which conform to the following BNF definition. More on resource bundle concepts and syntax can be found in the Users Guide.

Functions

int i18n_ures_create (const char *package_name, const char *locale, i18n_ures_h *ures)
 Creates a i18n_ures_h, from which users can extract strings by using their corresponding keys.
int i18n_ures_create_direct (const char *package_name, const char *locale, i18n_ures_h *ures)
 Creates a i18n_ures_h and does not care what kind of localeID is passed in.
int i18n_ures_create_unicode (const i18n_uchar *package_name, const char *locale, i18n_ures_h *ures)
 Creates a i18n_ures_h.
int i18n_ures_destroy (i18n_ures_h ures)
 Destroys an i18n_ures_h, all pointers returned from the various i18n_ures_getXXX calls on this particular resource bundle should be considered invalid henceforth.
int i18n_ures_get_version (i18n_ures_h ures, i18n_uversion_info version_array)
 Gets the version number associated with the i18n_ures_h as an i18n_uversion_info array.
int i18n_ures_get_locale_by_type (i18n_ures_h ures, i18n_ulocale_data_locale_type_e type, const char **locale)
 Gets the name of the locale associated with ures. You can choose between requested, valid and real locale.
int i18n_ures_get_string (i18n_ures_h ures, int32_t *len, const i18n_uchar **str_result)
 Gets a string from an i18n_ures_h.
int i18n_ures_get_UTF8_string (i18n_ures_h ures, char *dest, int32_t *len, i18n_ubool force_copy, const char **str_result)
 Gets a UTF-8 string from a string resource.
int i18n_ures_get_binary (i18n_ures_h ures, int32_t *len, const uint8_t **binary_result)
 Gets a binary data from a binary resource.
int i18n_ures_get_int_vector (i18n_ures_h ures, int32_t *len, const int32_t **int_vector_result)
 Gets a 32 bit integer array from a resource.
int i18n_ures_get_uint (i18n_ures_h ures, uint32_t *uint_result)
 Gets an unsigned integer from a resource. This integer is originally 28 bits.
int i18n_ures_get_int (i18n_ures_h ures, int32_t *int_result)
 Gets a signed integer from a resource. This integer is originally 28 bit and the sign gets propagated.
int i18n_ures_get_size (i18n_ures_h ures, int32_t *size_result)
 Gets the size of a resource.
int i18n_ures_get_type (i18n_ures_h ures, i18n_ures_type_e *type_result)
 Gets the type of a resource. Available types are defined in enum i18n_ures_type_e.
int i18n_ures_get_key (i18n_ures_h ures, const char **key_result)
 Gets the key associated with a given resource. Not all the resources have a key - only those that are members of a table.
int i18n_ures_reset_iterator (i18n_ures_h ures)
 Resets the internal context of a resource so that iteration starts from the first element.
int i18n_ures_has_next (i18n_ures_h ures, bool *has_next)
 Checks whether the given resource has another element to iterate over.
int i18n_ures_get_next_resource (i18n_ures_h ures, i18n_ures_h fill_in, i18n_ures_h *result)
 Gets the next resource in a given resource or NULL if there are no more resources to iterate over. Features a fill-in parameter.
int i18n_ures_get_next_string (i18n_ures_h ures, int32_t *len, const char **key, const i18n_uchar **str_result)
 Gets the next string in a given resource or NULL if there are no more resources to iterate over.
int i18n_ures_get_by_index (i18n_ures_h ures, int32_t index_r, i18n_ures_h fill_in, i18n_ures_h *ures_result)
 Gets the resource in a given resource at the specified index. Features a fill-in parameter.
int i18n_ures_get_string_by_index (i18n_ures_h ures, int32_t index_s, int32_t *len, const i18n_uchar **str_result)
 Gets the string in a given resource at the specified index.
int i18n_ures_get_UTF8_string_by_index (i18n_ures_h ures, int32_t index_s, char *dest, int32_t *len, i18n_ubool force_copy, const char **str_result)
 Gets a UTF-8 string from a resource at the specified index.
int i18n_ures_get_by_key (i18n_ures_h ures, const char *key, i18n_ures_h fill_in, i18n_ures_h *ures_result)
 Gets a resource in a given resource that has a given key. This procedure works only with table resources. Features a fill-in parameter.
int i18n_ures_get_string_by_key (i18n_ures_h ures, const char *key, int32_t *len, const i18n_uchar **str_result)
 Gets a string in a given resource that has a given key. This procedure works only with table resources.
int i18n_ures_get_UTF8_string_by_key (i18n_ures_h ures, const char *key, char *dest, int32_t *len, i18n_ubool force_copy, const char **str_result)
 Gets a UTF-8 string from a resource and a key. This function works only with table resources.

Typedefs

typedef void * i18n_ures_h
 An i18n_ures_h handle.

Typedef Documentation

typedef void* i18n_ures_h

An i18n_ures_h handle.

Use i18n_ures_* functions to operate on i18n_ures_h objects.

Since :
6.0

Enumeration Type Documentation

Numeric constants for types of resource items.

Since :
6.0
Enumerator:
I18N_URES_NONE 

Resource type constant for "no resource".

I18N_URES_STRING 

Resource type constant for 16-bit Unicode strings.

I18N_URES_BINARY 

Resource type constant for binary data.

I18N_URES_TABLE 

Resource type constant for tables of key-value pairs.

I18N_URES_ALIAS 

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.

I18N_URES_INT 

Resource type constant for a single 28-bit integer, interpreted as signed or unsigned by the i18n_ures_getInt() or i18n_ures_getUInt() function.

I18N_URES_ARRAY 

Resource type constant for arrays of resources.

I18N_URES_INT_VECTOR 

Resource type constant for vectors of 32-bit integers.


Function Documentation

int i18n_ures_create ( const char *  package_name,
const char *  locale,
i18n_ures_h ures 
)

Creates a i18n_ures_h, from which users can extract strings by using their corresponding keys.

Since :
6.0
Remarks:
The ures should be released using i18n_ures_destroy().
Parameters:
[in]package_nameThe package_name and locale together point to an i18n_ures_h. Typically, package_name will refer to a (.dat) file. Using a full file or directory pathname for package_name is deprecated. If NULL, ICU data will be used.
[in]localeSpecifies the locale for which we want to create the resource If NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
[out]uresA new i18n_ures_h.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
See also:
i18n_ures_destroy()
int i18n_ures_create_direct ( const char *  package_name,
const char *  locale,
i18n_ures_h ures 
)

Creates a i18n_ures_h and does not care what kind of localeID is passed in.

It simply creates a resource bundle with package_name. Fallback mechanism is disabled for the new resource bundle. If the requested bundle contains an ALIAS directive, the results are undefined.

Since :
6.0
Remarks:
The ures should be released using i18n_ures_destroy().
Parameters:
[in]package_nameThe package_name and locale together point to an i18n_ures_h. Typically, package_name will refer to a (.dat) file. Using a full file or directory pathname for package_name is deprecated. If NULL, ICU data will be used.
[in]localeSpecifies the locale for which we want to create the resource If NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
[out]uresA new i18n_ures_h.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
I18N_ERROR_MISSING_RESOURCEThe requested resource cannot be found
int i18n_ures_create_unicode ( const i18n_uchar package_name,
const char *  locale,
i18n_ures_h ures 
)

Creates a i18n_ures_h.

package_name will be converted to char * using the default converter, then i18n_ures_create() is called.

Since :
6.0
Remarks:
The ures should be released using i18n_ures_destroy().
Parameters:
[in]package_nameThe package_name and locale together point to an i18n_ures_h. Typically, package_name will refer to a (.dat) file. Using a full file or directory pathname for package_name is deprecated. If NULL, ICU data will be used.
[in]localeSpecifies the locale for which we want to create the resource If NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
[out]uresA new i18n_ures_h.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
See also:
i18n_ures_create()

Destroys an i18n_ures_h, all pointers returned from the various i18n_ures_getXXX calls on this particular resource bundle should be considered invalid henceforth.

Since :
6.0
Parameters:
[in]uresAn i18n_ures_h.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_ures_create()
int i18n_ures_get_binary ( i18n_ures_h  ures,
int32_t *  len,
const uint8_t **  binary_result 
)

Gets a binary data from a binary resource.

Since :
6.0
Remarks:
The binary_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[out]lenThe length of resulting byte chunk
[out]binary_resultA pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string()
i18n_ures_get_int_vector()
i18n_ures_get_int()
i18n_ures_get_uint()
int i18n_ures_get_by_index ( i18n_ures_h  ures,
int32_t  index_r,
i18n_ures_h  fill_in,
i18n_ures_h ures_result 
)

Gets the resource in a given resource at the specified index. Features a fill-in parameter.

If fill_in is not NULL, it will be filled with output data, and result will not be created. result can be NULL in this case. If fill_in is NULL, then a new handle will be created in result. result cannot be NULL in this case. This function may set ures_result to a non-NULL value even if an error occurs. This function's return value should be checked.

Since :
6.0
Remarks:
If fill_in is NULL, the result should be released using i18n_ures_destroy().
Parameters:
[in]uresResource bundle.
[in]index_rAn index to the wanted resource.
[in,out]fill_inA i18n_ures_h handle. It can be NULL.
[out]ures_resultA new i18n_ures_h if fill_in is NULL. Otherwise no changes are made to this parameter.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_by_key ( i18n_ures_h  ures,
const char *  key,
i18n_ures_h  fill_in,
i18n_ures_h ures_result 
)

Gets a resource in a given resource that has a given key. This procedure works only with table resources. Features a fill-in parameter.

If fill_in is not NULL, it will be filled with output data, and result will not be created. result can be NULL in this case. If fill_in is NULL, then a new handle will be created in result. result cannot be NULL in this case.

Since :
6.0
Remarks:
If fill_in is NULL, the result should be released using i18n_ures_destroy().
Parameters:
[in]uresResource bundle.
[in]keyA key associated with the wanted resource
[in,out]fill_inA i18n_ures_h handle. It can be NULL.
[out]ures_resultA new i18n_ures_h if fill_in is NULL. Otherwise no changes are made to this parameter.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_int ( i18n_ures_h  ures,
int32_t *  int_result 
)

Gets a signed integer from a resource. This integer is originally 28 bit and the sign gets propagated.

Since :
6.0
Parameters:
[in]uresResource bundle.
[out]int_resultAn integer value.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string()
i18n_ures_get_binary()
i18n_ures_get_uint()
i18n_ures_get_int_vector()
int i18n_ures_get_int_vector ( i18n_ures_h  ures,
int32_t *  len,
const int32_t **  int_vector_result 
)

Gets a 32 bit integer array from a resource.

Since :
6.0
Remarks:
The int_vector_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[out]lenThe length of resulting byte chunk
[out]int_vector_resultA pointer to a chunk of integers which live in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string()
i18n_ures_get_binary()
i18n_ures_get_int()
i18n_ures_get_uint()
int i18n_ures_get_key ( i18n_ures_h  ures,
const char **  key_result 
)

Gets the key associated with a given resource. Not all the resources have a key - only those that are members of a table.

Since :
6.0
Remarks:
The key_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[out]key_resultA key associated to this resource, or NULL if it doesn't have a key
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_locale_by_type ( i18n_ures_h  ures,
i18n_ulocale_data_locale_type_e  type,
const char **  locale 
)

Gets the name of the locale associated with ures. You can choose between requested, valid and real locale.

Since :
6.0
Remarks:
The locale is available until ures is released.
Parameters:
[in]uresAn i18n_ures_h.
[in]typeYou can choose between requested, valid and actual locale. For description see the definition of i18n_ulocale_data_locale_type_e
[out]localeA Locale name
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_next_resource ( i18n_ures_h  ures,
i18n_ures_h  fill_in,
i18n_ures_h result 
)

Gets the next resource in a given resource or NULL if there are no more resources to iterate over. Features a fill-in parameter.

If fill_in is not NULL, it will be filled with the next resource, and a new i18n_ures_h in result will not be created. If fill_in is NULL, then result will be set to a new i18n_ures_h containing the next resource.

If there are no more resources to iterate over, result will be set to NULL.

This function may set result to a non-NULL value even if an error occurs. This function's return value should be checked.

Since :
6.0
Remarks:
If fill_in is NULL, the result should be released using i18n_ures_destroy().
Parameters:
[in]uresResource bundle.
[in,out]fill_inA i18n_ures_h handle. It can be NULL.
[out]resultCannot be NULL. Will be set to a new i18n_ures_h if fill_in is NULL. Will be set to NULL if there are no more resources to iterate over.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_next_string ( i18n_ures_h  ures,
int32_t *  len,
const char **  key,
const i18n_uchar **  str_result 
)

Gets the next string in a given resource or NULL if there are no more resources to iterate over.

Since :
6.0
Remarks:
The key is available until ures is released.
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[out]lenFill in length of the string
[out]keyFill in for key associated with this string. NULL if no key
[out]str_resultA pointer to a zero-terminated i18n_uchar array which lives in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_size ( i18n_ures_h  ures,
int32_t *  size_result 
)

Gets the size of a resource.

Size for scalar types is always 1, and for vector/table types is the number of child resources.

Since :
6.0
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.
Parameters:
[in]uresResource bundle.
[out]size_resultThe number of resources in a given resource.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_string ( i18n_ures_h  ures,
int32_t *  len,
const i18n_uchar **  str_result 
)

Gets a string from an i18n_ures_h.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresAn i18n_ures_h.
[out]lenThe length of resulting string
[out]str_resultThe pointer to a zero-terminated i18n_uchar array which lives in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_binary()
i18n_ures_get_int_vector()
i18n_ures_get_int()
i18n_ures_get_uint()
int i18n_ures_get_string_by_index ( i18n_ures_h  ures,
int32_t  index_s,
int32_t *  len,
const i18n_uchar **  str_result 
)

Gets the string in a given resource at the specified index.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[in]index_sAn index to the wanted string
[out]lenFill in length of the string
[out]str_resultA pointer to a zero-terminated i18n_uchar array which lives in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
int i18n_ures_get_string_by_key ( i18n_ures_h  ures,
const char *  key,
int32_t *  len,
const i18n_uchar **  str_result 
)

Gets a string in a given resource that has a given key. This procedure works only with table resources.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[in]keyA key associated with the wanted resource
[out]lenFills in length of the string
[out]str_resultA pointer to a zero-terminated i18n_uchar array which lives in a memory mapped/DLL file.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_get_type ( i18n_ures_h  ures,
i18n_ures_type_e type_result 
)

Gets the type of a resource. Available types are defined in enum i18n_ures_type_e.

Since :
6.0
Parameters:
[in]uresResource bundle.
[out]type_resultType of the given resource.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_ures_type_e
int i18n_ures_get_uint ( i18n_ures_h  ures,
uint32_t *  uint_result 
)

Gets an unsigned integer from a resource. This integer is originally 28 bits.

Since :
6.0
Parameters:
[in]uresResource bundle.
[out]uint_resultAn integer value.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string()
i18n_ures_get_binary()
i18n_ures_get_int()
i18n_ures_get_int_vector()
int i18n_ures_get_UTF8_string ( i18n_ures_h  ures,
char *  dest,
int32_t *  len,
i18n_ubool  force_copy,
const char **  str_result 
)

Gets 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 i18n_ustring_to_UTF8() or equivalent. If force_copy==TRUE, then the string is always written to the dest buffer and dest is returned. If force_copy==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 I18N_ERROR_BUFFER_OVERFLOW is 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.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[out]destDestination buffer. Can be NULL only if capacity=*length==0.
[in,out]lenInput: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of I18N_ERROR_BUFFER_OVERFLOW. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
[in]force_copyIf TRUE, then the output string will always be written to dest, with I18N_ERROR_BUFFER_OVERFLOW 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 retval indicates overflow etc. as usual.
[out]str_resultThe pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !force_copy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string()
i18n_ustring_to_UTF8()
int i18n_ures_get_UTF8_string_by_index ( i18n_ures_h  ures,
int32_t  index_s,
char *  dest,
int32_t *  len,
i18n_ubool  force_copy,
const char **  str_result 
)

Gets 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 i18n_ustring_to_UTF8() or equivalent. If force_copy==TRUE, then the string is always written to the dest buffer and dest is returned. If force_copy==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 I18N_ERROR_BUFFER_OVERFLOW is 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.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[in]index_sAn index to the wanted string
[out]destDestination buffer. Can be NULL only if capacity=*length==0.
[in,out]lenInput: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of I18N_ERROR_BUFFER_OVERFLOW. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
[in]force_copyIf TRUE, then the output string will always be written to dest, with I18N_ERROR_BUFFER_OVERFLOW 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 I18N_ERROR parameter indicates overflow etc. as usual.
[out]str_resultThe pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !force_copy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
I18N_ERROR_RESOURCE_TYPE_MISMATCHAn operation is requested over a resource that does not support it.
See also:
i18n_ures_get_string_by_index()
i18n_ustring_to_UTF8()
int i18n_ures_get_UTF8_string_by_key ( i18n_ures_h  ures,
const char *  key,
char *  dest,
int32_t *  len,
i18n_ubool  force_copy,
const char **  str_result 
)

Gets 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 i18n_ustring_to_UTF8() or equivalent. If force_copy==TRUE, then the string is always written to the dest buffer and dest is returned. If force_copy==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 I18N_ERROR_BUFFER_OVERFLOW is 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.

Since :
6.0
Remarks:
The str_result is available until ures is released.
Parameters:
[in]uresResource bundle.
[in]keyA key associated with the wanted resource
[out]destDestination buffer. Can be NULL only if capacity=*length==0.
[in,out]lenInput: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of I18N_ERROR_BUFFER_OVERFLOW. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
[in]force_copyIf TRUE, then the output string will always be written to dest, with I18N_ERROR_BUFFER_OVERFLOW 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 I18N_ERROR parameter indicates overflow etc. as usual.
[out]str_resultThe pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !force_copy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_ures_get_string_by_key()
i18n_ustring_to_UTF8()
int i18n_ures_get_version ( i18n_ures_h  ures,
i18n_uversion_info  version_array 
)

Gets the version number associated with the i18n_ures_h as an i18n_uversion_info array.

Since :
6.0
Parameters:
[in]uresThe resource bundle for which the version is checked.
[out]version_arrayA i18n_uversion_info array that is filled with the version number as specified in the resource bundle or its parent.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ures_has_next ( i18n_ures_h  ures,
bool *  has_next 
)

Checks whether the given resource has another element to iterate over.

Since :
6.0
Parameters:
[in]uresResource bundle.
[out]has_nextTRUE if there are more elements, FALSE if there is no more elements
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Resets the internal context of a resource so that iteration starts from the first element.

Since :
6.0
Parameters:
[in]uresResource bundle.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter