Jump to content

UniStrToUcs: Difference between revisions

From EDM2
← Older edit
No edit summary
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== UniStrToUcs ==
Convert a code page string to a UCS string.
; UniStrToUcs(uconvObj, ucsBuffer, inBuffer, ucsBufferLen) : Convert a code page string to a UCS string.
 
===Syntax===
UniStrToUcs(uconvObj, ucsBuffer, inBuffer, ucsBufferLen);


=== Parameters ===
=== Parameters ===
; uconvObj - [[OS2 API:DataType:UconvObject|UconvObject]] - input : The conversion object created from [[OS2_API:UniCreateUconvObject|UniCreateUconvObject]].
;uconvObj - [[UconvObject]] - input : The conversion object created from [[UniCreateUconvObject]].
; ucsBuffer - [[OS2 API:DataType:UniChar|UniChar]] - output : The ucs buffer.
;ucsBuffer - [[UniChar]] - output : The ucs buffer.
; inBuffer - (character) - input : The input buffer that is null terminated.
;inBuffer - (character) - input : The input buffer that is null terminated.
; 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.
-->
-->
=== Constants ===
None


=== Returns ===
=== Returns ===
An integer with values of:
An integer with values of:
* [[OS2 API:Unicode:error#ULS_BADOBJECT|ULS_BADOBJECT]]
* [[Unicode Errors#ULS_BADOBJECT|ULS_BADOBJECT]]
* [[OS2 API:Unicode:error#ULS_BUFFERFULL|ULS_BUFFERFULL]]
* [[Unicode Errors#ULS_BUFFERFULL|ULS_BUFFERFULL]]
* [[OS2 API:Unicode:error#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]]
* [[Unicode Errors#ULS_ILLEGALSEQUENCE|ULS_ILLEGALSEQUENCE]]
* [[OS2 API:Unicode:error#ULS_INVALID|ULS_INVALID]]
* [[Unicode Errors#ULS_INVALID|ULS_INVALID]]
* [[OS2 API:Unicode:error#ULS_SUCCESS|ULS_SUCCESS]]
* [[Unicode Errors#ULS_SUCCESS|ULS_SUCCESS]]
 
=== Module ===
 
=== Define (C/C++) ===
 
=== Export name/Ordinal ===


=== Calling conversion ===
=== Calling Convention ===
[[Cdecl32]]
[[Cdecl32]]


=== 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;
  [[OS2 API:DataType:ULONG|ULONG]]       codePage;
  ULONG      codePage;
  [[OS2 API:DataType:ULONG|ULONG]]       cpLen;      // length set by [[OS2 API:DosQueryCp|DosQueryCp]]
  ULONG      cpLen;      // length set by [[DosQueryCp]]
  [[OS2 API:DataType:UniChar|UniChar]]     unicodeBuff, // length of unicodeBuffLen
  UniChar    unicodeBuff, // length of unicodeBuffLen
             ucsBuffer;  // length of CCHMAXPATH
             ucsBuffer;  // length of CCHMAXPATH
  [[OS2 API:DataType:UconvObject|UconvObject]] uconvObj;
  UconvObject uconvObj;
  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 51: 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>
=== Related Functions ===
[[OS2 API:UniUconvFromUcs|UniUconvFromUcs]]
[[OS2 API:UniUconvToUcs|UniUconvToUcs]]
[[OS2 API:UniStrFromUcs|UniStrFromUcs]]


=== 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 [[OS2_API:UniCreateUconvObject|UniCreateUnconvObject]] call in the [[OS2_API:DataType:UconvObject|UconvObject]].
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.


=== OS Version Introduced ===
=== OS Version Introduced ===
OS/2 Warp
OS/2 Warp


[[OS2_API | Back to OS/2 API]]
== Related Functions ==
 
*[[UniUconvFromUcs]]
*[[UniUconvToUcs]]
*[[UniStrFromUcs]]


[[Category:The OS/2 API Project]]
[[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

Cdecl32

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

Related Functions

Retrieved from "https://www.edm2.com/index.php?title=UniStrToUcs&oldid=67213"