CNV_ByteEncoding

CryptoSys PKI Toolkit Manual

CNV_ByteEncoding

Converts encoding of byte array between UTF-8 and Latin-1.

VB6/VBA Syntax


Public Declare Function CNV_ByteEncoding Lib "diCrPKI.dll" (ByRef abOutput As Byte, ByVal nOutBytes As Long, ByRef abInput As Byte, ByVal nBytes As Long, ByVal nOptions As Long) As Long

nLen = CNV_ByteEncoding(abOutput(0), nOutBytes, abInput(0), nBytes, nOptions)

Parameters

abOutput: [out] Byte array suitably dimensioned to receive output..
nOutBytes: [in] Long specifying the maximum number of bytes to be received.
abInput: [in] Byte array containing input data.
nBytes: [in] Long number of bytes in input array.
nOptions: [in] Long Option flags. Select one of:
PKI_CNV_UTF8_FROM_LATIN1 (1) to convert from UTF-8 encoding to Latin-1
PKI_CNV_LATIN1_FROM_UTF8 (2) to convert from Latin-1 encoding to UTF-8

C/C++ Syntax


long _stdcall CNV_ByteEncoding(unsigned char *lpOutput, long nOutBytes, const unsigned char *lpInput, long nBytes, long nOptions);

Returns (VB6/C)

Long: If successful, the return value is a positive number indicating the number of bytes in the output array, or number of bytes required if nOutBytes is set to zero; otherwise it returns a negative error code.

.NET Equivalent

Cnv.ByteEncoding Method

Remarks

Converting UTF-8 from Latin-1 assumes the input is from the 8-bit Latin-1 character set and so will always produce output that is valid UTF-8. However, for Latin-1 from UTF-8, the input must contain a valid sequence of UTF-8-encoded bytes and this must be convertible to a single-byte character set, or an error will be returned.

VB6/VBA users: Note the '(0)' in abOutput(0) and abInput(0).

Example

Dim abLatin1() As Byte
Dim abUTF8() As Byte
Dim nLatBytes As Long
Dim nUtfBytes As Long
' Set up a byte array with the following 4 characters encoded in Latin-1
'  U+0061 LATIN SMALL LETTER A
'  U+00E9 LATIN SMALL LETTER E WITH ACUTE
'  U+00F1 LATIN SMALL LETTER N WITH TILDE
'  U+0062 LATIN SMALL LETTER B
nLatBytes = 4
ReDim abLatin1(nLatBytes - 1)  ' NB required size minus 1
abLatin1(0) = Asc("a")
abLatin1(1) = &HE9
abLatin1(2) = &HF1
abLatin1(3) = Asc("b")
' Display in hex format
Debug.Print "Latin-1=" & cnvHexStrFromBytes(abLatin1) & " (" & nLatBytes & " bytes)"
' Convert encoding to UTF-8
' First find new length and pre-dimension array
nUtfBytes = CNV_ByteEncoding(vbNull, 0, abLatin1(0), nLatBytes, PKI_CNV_UTF8_FROM_LATIN1)
If nUtfBytes <= 0 Then Exit Sub 'ERROR
ReDim abUTF8(nUtfBytes - 1)
nUtfBytes = CNV_ByteEncoding(abUTF8(0), nUtfBytes, abLatin1(0), nLatBytes, PKI_CNV_UTF8_FROM_LATIN1)
' Display in hex format
Debug.Print "UTF-8  =" & cnvHexStrFromBytes(abUTF8) & " (" & nUtfBytes & " bytes)"

This should result in output as follows:

Latin-1=61E9F162 (4 bytes)
UTF-8  =61C3A9C3B162 (6 bytes)