Converts a string from the local code page to UTF-8, providing the caller with full control of the mapping and handling of unmappable characters.
#include <unilib.h> int locnx2utf8 ( UniRuleTable_t table, char *dest, size_t *destLen, const char *src, size_t srcLen, Loc2Utf8NoMapFunc_t noMapFunc, void *noMapFuncParm, int noMapFlag);
(IN) Specifies the table to use in the conversion. To use the host's default code page, specify UNI_LOCAL_DEFAULT. Otherwise, specify the value returned from the UniGetTable function.
(OUT) Points to the converted string.
(IN/OUT) Points to the maximum number of bytes that the converted string can contain. When the function returns, it contains the number of bytes in the converted string.
(IN) Points to the source string in local code page format.
(IN) Specifies the number of bytes in the source string.
(IN) Specifies the function to call when unmappable characters are found.
(IN) Points to an optional value for the noMapFunc function, which you can use in your noMapFunc function to distinguish between uses of the function. Whatever value you pass here, that value is passed to the no-map function when the locnx2utf8 function encounters a character that is not in its tables.
(IN) Specifies whether to replace an unmappable character or to simply return an error. It uses one of the following flags, but only the UNI_MAP_CHAR flag enables calling the noMapFunc function.
If successful, returns 0. Otherwise, returns a negative error code:
The function you provide for the noMapFunc parameter must conform to the following syntax:
typedef int (*Loc2Utf8NoMapFunc_t) ( char **dest, size_t remaining, const char **src, void *userParm );
(IN/OUT) Points to a pointer to the current position in the destination string. If the translation by the function results in a character output to this string, this pointer must be updated to point one character beyond it.
(IN/OUT) Specifies the number of characters in the source string that remain to be translated.
(IN/OUT) Points to a pointer to the current position in the source string.
If your noMapFunc consumes the character at this position, do not increment the pointer beyond the present position for locnx2uni does this.
If your noMapFunc consumes n characters, increment the value by n-1.
(IN) Specifies an optional parameter for the noMapFunc function. This is the value passed to locnx2utf8 in the noMapFuncParm parameter.
After your function is called, you can use it to convert the unmappable character and allow locnx2utf8 to continue converting the string, or you can use your function to convert the remaining characters.