UniUconvFromUcs: Difference between revisions
m removed INCL_ as it appears to be not used |
mNo edit summary |
||
| (10 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
Convert a UCS string to code page characters. | Convert a UCS string to code page characters. | ||
===Syntax=== | |||
UniUconvFromUcs(uconvObj, ucsBuffer, ucsBufferLen, outBuff, outBuffLen, nonIdenticalConv); | |||
=== Parameters === | === Parameters === | ||
; uconvObj - [[ | ; uconvObj - [[UconvObject]] - input : The conversion object created from [[UniCreateUconvObject]]. | ||
The conversion object created from [[ | ; ucsBuffer - [[UniChar]] - input : The input buffer. | ||
; ucsBuffer - [[ | ; ucsBufferLen - (size_t *) - input/output : The input buffer's length, in bytes. | ||
The input buffer. | ; outBuff - (void **) - output : The output buffer. | ||
; ucsBufferLen - (size_t *) - input/output : | ; outBuffLen - (size_t *) - output : Number of code page character elements in the outBuff. | ||
The input buffer's length, in bytes. | ; nonIdenticalConv - (size_t *) - output : Number of non-identical conversions. | ||
; outBuff - (void **) - output : | |||
The output buffer. | |||
; outBuffLen - (size_t *) - output : | |||
Number of code page character elements in the outBuff. | |||
; nonIdenticalConv - (size_t *) - output : | |||
Number of non-identical conversions. | |||
=== Returns === | === Returns === | ||
An integer with values of: | An integer with values of: | ||
* [[ | <!-- | ||
* [[ | * [[Unicode Errors#UCONV_E2BIG|UCONV_E2BIG]] | ||
* [[ | * [[Unicode Errors#UCONV_EBADF|UCONV_EBADF]] | ||
* [[ | * [[Unicode Errors#UCONV_EILSEQ|UCONV_EILSEQ]] | ||
* [[ | * [[Unicode Errors#UCONV_EINVALID|UCONV_EINVALID]] | ||
--> | |||
* [[Unicode Errors#ULS_BUFFERFULL|ULS_BUFFERFULL]] | |||
* [[Unicode Errors#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]] | |||
* [[Unicode Errors#ULS_INVALID|ULS_INVALID]] | |||
* [[Unicode Errors#ULS_SUCCESS|ULS_SUCCESS]] | |||
'''UniUconvFromUcs''' updates the variables pointed to by the arguments to reflect the extent of the conversion and returns, in nonidentical, the number of substitution (nonidentical conversions) performed. If the entire string in the input buffer is converted, the value pointed to by ucsBufferLen will be 0. If the input conversion is stopped due to any condition mentioned above, the value pointed to by ucsBufferLen will be nonzero. If any error occurs, [[UniUconvToUcs]] returns a nonzero value. | |||
=== Calling Convention === | |||
=== Calling | |||
[[Cdecl32]] | [[Cdecl32]] | ||
=== Example Code === | === Example Code === | ||
UconvObject uconvObj; | |||
UniChar ucsBuffer; | |||
size_t* ucsBufferLen; | size_t* ucsBufferLen; | ||
void** outBuff; | void** outBuff; | ||
| Line 48: | Line 41: | ||
rc = UniUconvFromUcs(uconvObj, ucsBuffer, ucsBufferLen, outBuff, outBuffLen, nonIdenticalConv); | rc = UniUconvFromUcs(uconvObj, ucsBuffer, ucsBufferLen, outBuff, outBuffLen, nonIdenticalConv); | ||
... | ... | ||
=== Notes === | === Notes === | ||
The sequence of the code page characters in ucsBuffer is converted into a sequence of Unicode characters in outBuff. | The sequence of the code page characters in ucsBuffer is converted into a sequence of Unicode characters in outBuff. The code page was set by [[UniCreateUconvObject]] call in the [[UconvObject]]. | ||
Conversion is only on bytes that convert. | Conversion is only on bytes that convert. The process stops converting on the first non-valid byte. If the outBuff isn't large enough, conversion ends on the UniChar previous to any buffer overflow. outBuff is updated truncating the point of failure to the end and updating the outBuffLen to indicate the number of successfully converted elements. | ||
=== OS Version Introduced === | === OS Version Introduced === | ||
OS/2 Warp | OS/2 Warp | ||
==Related Functions== | |||
*UniConvToUcs | |||
*[[UniStrFromUcs]] | |||
*[[UniStrToUcs]] | |||
[[Category:Uni]] | |||
Latest revision as of 18:04, 4 December 2019
Convert a UCS string to code page characters.
Syntax
UniUconvFromUcs(uconvObj, ucsBuffer, ucsBufferLen, outBuff, outBuffLen, nonIdenticalConv);
Parameters
- uconvObj - UconvObject - input
- The conversion object created from UniCreateUconvObject.
- ucsBuffer - UniChar - input
- The input buffer.
- ucsBufferLen - (size_t *) - input/output
- The input buffer's length, in bytes.
- outBuff - (void **) - output
- The output buffer.
- outBuffLen - (size_t *) - output
- Number of code page character elements in the outBuff.
- nonIdenticalConv - (size_t *) - output
- Number of non-identical conversions.
Returns
An integer with values of:
UniUconvFromUcs updates the variables pointed to by the arguments to reflect the extent of the conversion and returns, in nonidentical, the number of substitution (nonidentical conversions) performed. If the entire string in the input buffer is converted, the value pointed to by ucsBufferLen will be 0. If the input conversion is stopped due to any condition mentioned above, the value pointed to by ucsBufferLen will be nonzero. If any error occurs, UniUconvToUcs returns a nonzero value.
Calling Convention
Example Code
UconvObject uconvObj; UniChar ucsBuffer; size_t* ucsBufferLen; void** outBuff; size_t* outBuffLen; size_t* nonIdenticalConv; integer rc; ... rc = UniUconvFromUcs(uconvObj, ucsBuffer, ucsBufferLen, outBuff, outBuffLen, nonIdenticalConv); ...
Notes
The sequence of the code page characters in ucsBuffer is converted into a sequence of Unicode characters in outBuff. 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 outBuff isn't large enough, conversion ends on the UniChar previous to any buffer overflow. outBuff is updated truncating the point of failure to the end and updating the outBuffLen to indicate the number of successfully converted elements.
OS Version Introduced
OS/2 Warp
Related Functions
- UniConvToUcs
- UniStrFromUcs
- UniStrToUcs