CNV_ByteEncoding

CryptoSys PKI Pro Manual

CNV_ByteEncoding

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

VBA/VB6 Syntax


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

nLen = CNV_ByteEncoding(lpOutput(0), nOutBytes, lpInput(0), nBytes, nOptions) ' Note the "(0)" after the byte array parameters

C/C++ Syntax


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

Parameters

lpOutput: [out] array suitably dimensioned to receive output..
nOutBytes: [in] specifying the maximum number of bytes to be received.
lpInput: [in] array containing input data.
nBytes: [in] number of bytes in input array.
nOptions: [in] 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

Returns (VBA/C)

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.

VBA Wrapper Syntax

Public Function cnvByteEncoding (lpInput() As Byte, nOptions As Long) As Byte()

.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.

Example (VBA core function)

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(0, 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)

Example (VBA wrapper function)

Dim lpLatin1() As Byte
Dim lpUTF8() As Byte
' 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
lpLatin1 = cnvBytesFromHexStr("61E9F162")
Debug.Print "Latin-1=" & cnvHexStrFromBytes(lpLatin1) & " (" & cnvBytesLen(lpLatin1) & " bytes)"
lpUTF8 = cnvByteEncoding(lpLatin1, PKI_CNV_UTF8_FROM_LATIN1)
Debug.Print "UTF-8  =" & cnvHexStrFromBytes(lpUTF8) & " (" & cnvBytesLen(lpUTF8) & " bytes)"
' And back again the other way...
lpLatin1 = cnvByteEncoding(lpUTF8, PKI_CNV_LATIN1_FROM_UTF8)
Debug.Print "Latin-1=" & cnvHexStrFromBytes(lpLatin1) & " (" & cnvBytesLen(lpLatin1) & " bytes)"