UniStrFromUcs: Difference between revisions
No edit summary |
No edit summary |
||
| Line 3: | Line 3: | ||
=== Parameters === | === Parameters === | ||
; uconvObj - [[ | ; uconvObj - [[UconvObject]] - input : The conversion object created from [[UniCreateUconvObject]]. | ||
; outBuffer - [[ | ; outBuffer - [[CHAR]] - output : The output buffer to hold code page. | ||
; ucsString - [[ | ; ucsString - [[UniChar]] - input : Null terminated Unicode string. | ||
; outBufferLen - (int) - input/output : The output buffer's length, in bytes. | ; outBufferLen - (int) - input/output : The output buffer's length, in bytes. | ||
| Line 17: | Line 17: | ||
* [[OS2 API:Unicode:error#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]] | * [[OS2 API:Unicode:error#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]] | ||
* [[OS2 API:Unicode:error#ULS_SUCCESS|ULS_SUCCESS]] | * [[OS2 API:Unicode:error#ULS_SUCCESS|ULS_SUCCESS]] | ||
=== Calling conversion === | === Calling conversion === | ||
| Line 31: | Line 25: | ||
size_t unicodeBuffLen = 12; | size_t unicodeBuffLen = 12; | ||
[[ | [[ULONG]] codePage; | ||
ULONG cpLen; // length set by [[DosQueryCp]] | |||
[[ | [[UniChar]] unicodeBuff, // length of unicodeBuffLen | ||
ucsString; // length of CCHMAXPATH | ucsString; // length of CCHMAXPATH | ||
[[ | [[UconvObject]] uconv; | ||
character outBuffer; // allocate to CCHMAXPATH | character outBuffer; // allocate to CCHMAXPATH | ||
integer rc; | integer rc; | ||
| Line 56: | Line 50: | ||
=== Related Functions === | === Related Functions === | ||
[[ | [[UniconvFromUcs]] | ||
[[ | [[UniconvToUcs]] | ||
[[ | [[UniStrToUcs]] | ||
=== Notes === | === Notes === | ||
The sequence of code elements in ucsString is converted into a sequence of code page characters to outBuffer. The code page was set by [[ | The sequence of code elements in ucsString is converted into a sequence of code page characters to outBuffer. The code page was set by [[UniCreateUnconvObject]] call in the [[UconvObject]]. | ||
If the outBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. outBuffer is updated truncating the point of failure to the end and updating the outBufferLen to indicate the number of successfully converted bytes. | If the outBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. outBuffer is updated truncating the point of failure to the end and updating the outBufferLen to indicate the number of successfully converted bytes. | ||
If | If '''UniStrFromUcs''' contains a code sequence in ucsString that is legal with no corresponding character in the target codepage this function will replace it with a predefined substituted character. | ||
=== OS Version Introduced === | === OS Version Introduced === | ||
OS/2 Warp | *OS/2 Warp | ||
[[Category: | [[Category:Uni]] | ||
Revision as of 04:46, 17 November 2016
UniStrFromUcs
- UniStrFromUcs(uconvObj, outBuffer, ucsString, outBufferLen)
- Convert a UCS string to a code page string.
Parameters
- uconvObj - UconvObject - input
- The conversion object created from UniCreateUconvObject.
- outBuffer - CHAR - output
- The output buffer to hold code page.
- ucsString - UniChar - input
- Null terminated Unicode string.
- outBufferLen - (int) - input/output
- The output buffer's length, in bytes.
Constants
None
Returns
An integer with values of:
Calling conversion
Example Code
character in = "C:\SOMEPATH\FILE.TXT"; size_t unicodeBuffLen = 12; ULONG codePage; ULONG cpLen; // length set by DosQueryCp UniChar unicodeBuff, // length of unicodeBuffLen ucsString; // length of CCHMAXPATH UconvObject uconv; character outBuffer; // allocate to CCHMAXPATH integer rc;
rc = DosQueryCp(size of ULONG, codePage, cpLen);
/* determine string for the conversion of codePage */ rc = UniMapCpToUcsCp(codePage, unicodeBuff, unicodeBuffLen); rc = UniCreateUconvObject(unicodeBuff, uconvObj); rc = UniStrToUcs(uconvObj, ucsString, 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, outBuffer, ucsString, CCHMAXPATH); rc = UniFreeUconvObject(uconvObj);
/* use outBuffer - don't forget to de-allocate outBuffer when finished with it. */ /* error checking left out for brevity */
Related Functions
UniconvFromUcs UniconvToUcs UniStrToUcs
Notes
The sequence of code elements in ucsString is converted into a sequence of code page characters to outBuffer. The code page was set by UniCreateUnconvObject call in the UconvObject.
If the outBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. outBuffer is updated truncating the point of failure to the end and updating the outBufferLen to indicate the number of successfully converted bytes.
If UniStrFromUcs contains a code sequence in ucsString that is legal with no corresponding character in the target codepage this function will replace it with a predefined substituted character.
OS Version Introduced
- OS/2 Warp