UniStrToUcs: Difference between revisions
No edit summary |
mNo edit summary |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
== | Convert a code page string to a UCS string. | ||
===Syntax=== | |||
UniStrToUcs(uconvObj, ucsBuffer, inBuffer, ucsBufferLen); | |||
=== Parameters === | === Parameters === | ||
| Line 8: | Line 10: | ||
;ucsBufferLen - (integer) - input : Number of unicode character elements in the ucsBuffer. | ;ucsBufferLen - (integer) - input : Number of unicode character elements in the ucsBuffer. | ||
<!-- | <!-- | ||
; inBufferLen - (size_t *) - input/output : The input buffer's length, in bytes. | ;inBufferLen - (size_t *) - input/output : The input buffer's length, in bytes. | ||
; nonIdenticalConv - (size_t *) - output : Number of non-identical conversions. | ;nonIdenticalConv - (size_t *) - output : Number of non-identical conversions. | ||
--> | --> | ||
=== Returns === | === Returns === | ||
An integer with values of: | An integer with values of: | ||
* [[ | * [[Unicode Errors#ULS_BADOBJECT|ULS_BADOBJECT]] | ||
* [[ | * [[Unicode Errors#ULS_BUFFERFULL|ULS_BUFFERFULL]] | ||
* [[ | * [[Unicode Errors#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]] | ||
* [[ | * [[Unicode Errors#ULS_INVALID|ULS_INVALID]] | ||
* [[ | * [[Unicode Errors#ULS_SUCCESS|ULS_SUCCESS]] | ||
=== Calling Convention === | === Calling Convention === | ||
| Line 27: | Line 26: | ||
=== Example Code === | === Example Code === | ||
<code> | |||
character inBuffer = "C:\SOMEPATH\FILE.TXT"; | character inBuffer = "C:\SOMEPATH\FILE.TXT"; | ||
size_t unicodeBuffLen = 12; | size_t unicodeBuffLen = 12; | ||
ULONG codePage; | ULONG codePage; | ||
ULONG cpLen; // length set by [[ | ULONG cpLen; // length set by [[DosQueryCp]] | ||
UniChar unicodeBuff, // length of unicodeBuffLen | UniChar unicodeBuff, // length of unicodeBuffLen | ||
ucsBuffer; // length of CCHMAXPATH | ucsBuffer; // length of CCHMAXPATH | ||
| Line 37: | Line 37: | ||
character out; // allocate to CCHMAXPATH | character out; // allocate to CCHMAXPATH | ||
integer rc; | integer rc; | ||
rc = DosQueryCp(size of ULONG, codePage, cpLen); | rc = DosQueryCp(size of ULONG, codePage, cpLen); | ||
/* determine string for the conversion of codePage */ | /* determine string for the conversion of codePage */ | ||
rc = UniMapCpToUcsCp(codePage, unicodeBuff, unicodeBuffLen); | rc = UniMapCpToUcsCp(codePage, unicodeBuff, unicodeBuffLen); | ||
| Line 45: | Line 45: | ||
rc = UniStrToUcs(uconvObj, ucsBuffer, inBuffer, CCHMAXPATH); | rc = UniStrToUcs(uconvObj, ucsBuffer, inBuffer, CCHMAXPATH); | ||
rc = UniFreeUconvObject(uconvObj); | rc = UniFreeUconvObject(uconvObj); | ||
/* conversion for current codepage that can be used for paths */ | /* conversion for current codepage that can be used for paths */ | ||
rc = UniCreateUconvObject((UniChar pointer)L"@path=yes", uconvObj); | rc = UniCreateUconvObject((UniChar pointer)L"@path=yes", uconvObj); | ||
rc = UniStrFromUcs(uconvObj, out, ucsBuffer, CCHMAXPATH); | rc = UniStrFromUcs(uconvObj, out, ucsBuffer, CCHMAXPATH); | ||
rc = UniFreeUconvObject(uconvObj); | rc = UniFreeUconvObject(uconvObj); | ||
/* use out - don't forget to de-allocate out when finished with it. */ | /* use out - don't forget to de-allocate out when finished with it. */ | ||
/* error checking left out for brevity */ | /* error checking left out for brevity */ | ||
</code> | |||
=== Notes === | === Notes === | ||
The sequence of the code page characters in inBuffer is converted into a sequence of Unicode characters in ucsBuffer. The code page was set by [[ | The sequence of the code page characters in inBuffer is converted into a sequence of Unicode characters in ucsBuffer. The code page was set by [[UniCreateUconvObject]] call in the [[UconvObject]]. | ||
Conversion is only on bytes that convert. The process stops converting on the first non-valid byte. If the ucsBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. inBuffer is updated truncating the point of failure to the end and updating the ucsBufferLen to indicate the number of successfully converted elements. | Conversion is only on bytes that convert. The process stops converting on the first non-valid byte. If the ucsBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. inBuffer is updated truncating the point of failure to the end and updating the ucsBufferLen to indicate the number of successfully converted elements. | ||
| Line 66: | Line 62: | ||
=== OS Version Introduced === | === OS Version Introduced === | ||
OS/2 Warp | OS/2 Warp | ||
== Related Functions == | |||
*[[UniUconvFromUcs]] | |||
*[[UniUconvToUcs]] | |||
*[[UniStrFromUcs]] | |||
[[Category:Uni]] | [[Category:Uni]] | ||
Latest revision as of 18:01, 4 December 2019
Convert a code page string to a UCS string.
Syntax
UniStrToUcs(uconvObj, ucsBuffer, inBuffer, ucsBufferLen);
Parameters
- uconvObj - UconvObject - input
- The conversion object created from UniCreateUconvObject.
- ucsBuffer - UniChar - output
- The ucs buffer.
- inBuffer - (character) - input
- The input buffer that is null terminated.
- ucsBufferLen - (integer) - input
- Number of unicode character elements in the ucsBuffer.
Returns
An integer with values of:
Calling Convention
Example Code
character inBuffer = "C:\SOMEPATH\FILE.TXT";
size_t unicodeBuffLen = 12;
ULONG codePage;
ULONG cpLen; // length set by DosQueryCp
UniChar unicodeBuff, // length of unicodeBuffLen
ucsBuffer; // 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, unicodeBuff, unicodeBuffLen);
rc = UniCreateUconvObject(unicodeBuff, uconvObj);
rc = UniStrToUcs(uconvObj, ucsBuffer, inBuffer, 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, ucsBuffer, CCHMAXPATH);
rc = UniFreeUconvObject(uconvObj);
/* use out - don't forget to de-allocate out when finished with it. */
/* error checking left out for brevity */
Notes
The sequence of the code page characters in inBuffer is converted into a sequence of Unicode characters in ucsBuffer. The code page was set by UniCreateUconvObject call in the UconvObject.
Conversion is only on bytes that convert. The process stops converting on the first non-valid byte. If the ucsBuffer isn't large enough, conversion ends on the byte previous to any buffer overflow. inBuffer is updated truncating the point of failure to the end and updating the ucsBufferLen to indicate the number of successfully converted elements.
OS Version Introduced
OS/2 Warp