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

enum i18n_ures_type_e

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_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()

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_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

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_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()

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.

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()

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]	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()

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]	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

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]	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

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]	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()

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]	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()

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]	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

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]	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

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]	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

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]	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

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]	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

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]	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()

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]	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.

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]	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

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]	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

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]	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()

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]	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()

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]	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()

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]	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()

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]	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

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]	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

int i18n_ures_reset_iterator ( i18n_ures_h ures )

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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation