Converts a path from Unicode to the local code page, using the special semantics of file system paths.
#include <unilib.h>
int uni2locpath (
UniRuleTable_t table,
char *dest,
const unicode_t *src,
size_t *dryRunSize);
(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 path.
(IN) Points to the source path to use in the conversion.
(IN) Indicates whether to perform the conversion or merely compute the size of the converted string:
To perform the conversion, pass NULL.
To calculate the size of the converted string, pass the address of a variable of type size_t. The function returns in this parameter the number of characters that would be consumed in dest if the function were to perform the actual conversion. No conversion is performed. The count includes only the number of characters and does not include any null-terminating characters
If successful, returns 0. Otherwise, returns a negative error code:
Irrespective of any assumed language represented by the Unicode string in src, uni2locpath interprets Unicode Yen (0x00A5), Won (0x20A9), the backslash (0x005C) and the path separator character for Novell® (0xF8F7) as reserved characters, converting each one to the backslash character (0x5C) in the (ASCIIZ) output.
The uni2locpath function converts any unmappable Unicode character to the special sequence “[XxYy]” where Xx represents the character set as a 2-byte hexadecimal number and Yy represents the character as a 2-byte hexadecimal number and these four are enclosed between square brackets. The specially created sequence is recognized by loc2unipath when translated back in and results in a completely accurate round trip.
An unmappable character is defined as a Unicode value that has no equivalent in the local code page. For example, if the Won character (0x20A9) appeared in the Unicode source string and that string were to be translated via uni2locpath in a US English environment (codepage 437), then the output (ASCIIZ) string would contain “[20A9]” effectively lengthening the string by 5 more characters than might have been provided for. Because of this, either a dry run needs to be performed to effectively size the destination string, or a sufficient amount of extra room must be routinely provided based on the caller's experience.