Creates and initializes the conversion object.
- cpName - UniChar - input
- Name of the UCS conversion.
- uconvObj - UconvObject - output
- The conversion object returned.
An integer with values of:
character in = "C:\SOMEPATH\FILE.TXT"; size_t cpNameLen = 12; ULONG codePage; ULONG cpLen; // length set by DosQueryCp UniChar cpName, // length of cpNameLen tempPath; // length of CCHMAXPATH UconvObject uconvObj; character out; // allocate to CCHMAXPATH integer rc; rc = DosQueryCp(size of ULONG, codePage, cpLen); /* determine string for the conversion of codePage */ rc = UniMapCpToUcsCp(codePage, cpName, cpNameLen); rc = UniCreateUconvObject(cpName, uconvObj); rc = UniStrToUcs(uconv, tempPath, in, CCHMAXPATH); rc = UniFreeUconvObject(uconvObj); /* conversion for current codepage that can be used for paths */ rc = UniCreateUconvObject((UniChar pointer)L"@path=yes", uconvObj); rc = UniStrFromUcs(uconvObj, out, tempPath, CCHMAXPATH); rc = UniFreeUconvObject(uconvObj); /* use out - don't forget to de-allocate out when finished with it. */ /* error checking left out for brevity */
#include <uconv.h> int UniCreateUconvObject ( UniChar *cpname, /* I - UCS conversion specifier */ UconvObject *uconv_object /* O - Conversion object handle */ )
UniCreateUconvObject returns a conversion object that describes a UCS-2 conversion between the code page specified by cpName and UCS.
A conversion object remains valid until it is freed with UniFreeUconvObject.
The cpName field is normally the Unicode string IBM- followed by the decimal number of the code page. Other names may be used. UCONV tables are kept in the \language\codepage directory on the boot drive.
If the cpName parameter contains an empty string, UniCreateUconvObject will create a conversion object based upon the value of the process codepage setting.
UniCreateUconvObject allows modifiers to be concatenated onto cpName, these modifiers change the default behavior of conversion objects. The caller can concatenate the following modifiers onto cpName.
Modifiers are separated from the conversion object name by an at sign (@), and multiple modifiers are separated by a comma (,).
@map=data All characters less than space are controls. (default) @map=display All characters less than space are glyphs. @map=cdra Use IBM standard control conversion. @map=clrf CR and LF are controls, others are glyphs.
@path=yes When performing Unicode conversions strings are assumed to contain pathnames. This setting is only applicable when converting to or from DBCS codepages. (default) @path=no When performing Unicode conversions strings are assumed to contain non path data. This setting is only applicable when converting to or from DBCS codepages.
@endian=Source:Target @endian=Both Source applies to UniUconvFromUcs; Target applies to UniUconvToUcs. If only one endian is given, it applies to both source and target. The endian type can be one of the following: system Use system endian. big Use big endian. little Use little endian. (default) For example @endian=little @endian=big:system
@sub=yes Perform substitutions when converting to and from Unicode. @sub=no Do not perform substitutions when converting to and from Unicode. @sub=to-ucs Only perform substitutions when converting to Unicode. @sub=from-ucs Only perform substitutions when converting from Unicode. (default) @subchar=\xXX Where XX is a hex number @subchar=\DD Where DD is a decimal number The substitution character attribute specifies which character the conversion object should use when there is no identical character for a given code element while converting from Unicode. @subuni=\xXX\xXX Where XX is a hex number @subuni=\xXXXX Where XXXX is a hex number The substitution character attribute specifies which character the conversion object should use when there is no identical character for a given code element while converting to Unicode.
Examples of typical usage:
This example creates a conversion object based upon an IBM-942 encoding. When conversions are performed all strings will be treated as pathnames and all characters less than space will be considered to be glyphs.
This example creates a conversion object based upon the current process codepage setting. When conversions are performed all strings will be treated as pathnames and no substitutions will occur.
This example creates a conversion object based upon an IBM-850 encoding. When conversions are performed all strings will be treated as non pathnames and substitutions will occur when converting to and from Unicode if necessary.
OS Version Introduced