An i18n_ures_h handle.

Use i18n_ures_* functions to operate on i18n_ures_h objects.

Since :

6.0

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.

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_name	The 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]	locale	Specifies 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]	ures	A new i18n_ures_h.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

See also:

i18n_ures_destroy()

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_name	The 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]	locale	Specifies 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]	ures	A new i18n_ures_h.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory
I18N_ERROR_MISSING_RESOURCE	The requested resource cannot be found

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_name	The 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]	locale	Specifies 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]	ures	A new i18n_ures_h.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out 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]

ures

An i18n_ures_h.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:

i18n_ures_create()

Gets a binary data from a binary resource.

Since :

6.0

Remarks:

The binary_result is available until ures is released. The binary_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[out]	len	The length of resulting byte chunk
[out]	binary_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An 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()

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]	ures	Resource bundle.
[in]	index_r	An index to the wanted resource.
[in,out]	fill_in	A i18n_ures_h handle. It can be NULL.
[out]	ures_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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]	ures	Resource bundle.
[in]	key	A key associated with the wanted resource
[in,out]	fill_in	A i18n_ures_h handle. It can be NULL.
[out]	ures_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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

Since :

6.0

Parameters:

[in]	ures	Resource bundle.
[out]	int_result	An integer value.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An 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()

Gets a 32 bit integer array from a resource.

Since :

6.0

Remarks:

The int_vector_result is available until ures is released. The int_vector_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[out]	len	The length of resulting byte chunk
[out]	int_vector_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An 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()

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. The key_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[out]	key_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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. The locale should not be released.

Parameters:

[in]	ures	An i18n_ures_h.
[in]	type	You can choose between requested, valid and actual locale. For description see the definition of i18n_ulocale_data_locale_type_e
[out]	locale	A Locale name

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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]	ures	Resource bundle.
[in,out]	fill_in	A i18n_ures_h handle. It can be NULL.
[out]	result	Cannot 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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 key should not be released.

The str_result is available until ures is released. The str_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[out]	len	Fill in length of the string
[out]	key	Fill in for key associated with this string. NULL if no key
[out]	str_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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]	ures	Resource bundle.
[out]	size_result	The number of resources in a given resource.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Gets a string from an i18n_ures_h.

Since :

6.0

Remarks:

The str_result is available until ures is released. The str_result should not be released.

Parameters:

[in]	ures	An i18n_ures_h.
[out]	len	The length of resulting string
[out]	str_result	The 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An 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()

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

Since :

6.0

Remarks:

The str_result is available until ures is released. The str_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[in]	index_s	An index to the wanted string
[out]	len	Fill in length of the string
[out]	str_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An operation is requested over a resource that does not support it.

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. The str_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[in]	key	A key associated with the wanted resource
[out]	len	Fills in length of the string
[out]	str_result	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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

Since :

6.0

Parameters:

[in]	ures	Resource bundle.
[out]	type_result	Type of the given resource.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:

i18n_ures_type_e

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

Since :

6.0

Parameters:

[in]	ures	Resource bundle.
[out]	uint_result	An integer value.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An 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()

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. The str_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[out]	dest	Destination buffer. Can be NULL only if capacity=*length==0.
[in,out]	len	Input: 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_copy	If 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_result	The 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	A result would not fit in the supplied buffer
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An operation is requested over a resource that does not support it.

See also:

i18n_ures_get_string()

i18n_ustring_to_UTF8()

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. The str_result should not be released.

Parameters:

[in]	ures	Resource bundle.
[in]	index_s	An index to the wanted string
[out]	dest	Destination buffer. Can be NULL only if capacity=*length==0.
[in,out]	len	Input: 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_copy	If 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_result	The 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	A result would not fit in the supplied buffer
I18N_ERROR_RESOURCE_TYPE_MISMATCH	An operation is requested over a resource that does not support it.

See also:

i18n_ures_get_string_by_index()

i18n_ustring_to_UTF8()

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]	ures	Resource bundle.
[in]	key	A key associated with the wanted resource
[out]	dest	Destination buffer. Can be NULL only if capacity=*length==0.
[in,out]	len	Input: 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_copy	If 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_result	The 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:

i18n_ures_get_string_by_key()

i18n_ustring_to_UTF8()

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

Since :

6.0

Parameters:

[in]	ures	The resource bundle for which the version is checked.
[out]	version_array	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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

Since :

6.0

Parameters:

[in]	ures	Resource bundle.
[out]	has_next	TRUE 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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

Since :

6.0

Parameters:

[in]

ures

Resource bundle.

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter