locnx2unipath

Converts a path from local code page to Unicode, providing the caller with full control of mapping and handling unmappable characters.

Library:LibC
Service:Characters and Strings

Syntax

  #include <unilib.h> 
   
  int locnx2unipath (
     UniRuleTable_t       table,
     unicode_t           *dest,
     size_t              *destLen,
     const char          *src,
     size_t               srcLen,
     Loc2UniNoMapFunc_t   noMapFunc,
     void                *noMapFuncParm,
     int                  noMapFlag,
     size_t              *dryRunSize );

Parameters

table

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

dest

(OUT) Points to the converted path.

destLen

(IN/OUT) Points to the maximum number of bytes that the destination path can hold when the function is called. When the function returns, it contains the number of bytes in the converted path.

src

(IN) Points to the source path to use in the conversion.

srcLen

(IN) Specifies the length of the source path.

noMapFunc

(IN) Specifies the function to call when unmappable characters are found. See Remarks for the prototype.

noMapFuncParm

(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 locnx2unipath function encounters a character that is not in its tables.

noMapFlag

(IN) Specifies whether to replace an unmappable character or simply return an error. It uses one of the following flags, but only the UNI_MAP_BY_FUNC flag enables calling the noMapFunc function.

Flag

Value

Description

UNI_MAP_NO_CHAR

0

Returns the UNI_ERR_UNMAPPABLE_CHAR error code as soon as a character is found to be unmappable. The result is null-terminated at the offending position in the string.

UNI_MAP_BY_FUNC

1

Passes a pointer to the current locations in the source and destination strings to the noMapFunc function if the noMapFunc parameter is not nil.

UNI_MAP_SELF

2

Uses the source character. In many cases this does not result in anything useful.
dryRunSize

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

Return Values

If successful, returns 0. Otherwise, returns a negative error code:

Decimal

Name

Description

-496

UNI_ERR_BAD_HANDLE

The table parameter specifies a nonexistent rule table.

-532

UNI_ERR_UNMAPPABLE_CHAR

A character in the source path is unmappable.

Remarks

The function you provide for the noMapFunc parameter must conform to the following syntax:

  typedef int (*Loc2UniNoMapFunc_t)
     ( unicode_t     **dest,
       size_t          remaining,
       const char    **src,
       void           *userParm );
dest

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

remaining

(IN/OUT) Specifies the number of characters in the source string that remain to be translated.

src

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

userParm

(IN) Specifies an optional parameter for the noMapFunc function. This is the value passed to locnx2unipath in the noMapFuncParm parameter.

After your function is called, you can use it to convert the unmappable character and allow locnx2unipath to continue converting the string, or you can use your function to convert the remaining characters.

See Also