CNV_BytesFromHexStr

CryptoSys PKI Pro Manual

CNV_BytesFromHexStr

Decodes a hexadecimal-encoded string into an array of Bytes.

VBA/VB6 Syntax


Public Declare Function CNV_BytesFromHexStr Lib "diCrPKI.dll" 
    (ByRef lpData As Byte, ByVal nDataLen As Long, ByVal strHex As String) As Long

nLen = CNV_BytesFromHexStr(lpData(0), nDataLen, strHex)

C/C++ Syntax


long __stdcall CNV_BytesFromHexStr(unsigned char *lpOutput, long nOutBytes, const char *szInput);

Parameters

lpOutput: [out] array suitably dimensioned to receive output.
nOutBytes: [in] specifying the length of the byte array.
szInput: [in] of hexadecimal data to be decoded.

Returns (VBA/C)

If successful, the return value is the number of bytes in the decoded array; otherwise it returns a negative error code.

VBA Wrapper Syntax

Public Function cnvBytesFromHexStr (szHex As String) As Byte()
Public Function cnvFromHex (strHex As String) As Byte()
Public Function cnvStringFromHexStr (ByVal szHex As String) As String

.NET Equivalent

Cnv.FromHex Method

C++ (STL) Equivalent

static bvec_t dipki::Cnv::FromHex (const std::string &s)

Python Equivalent

static Cnv.fromhex(s)

Remarks

Call the function with a null lpOutput array or zero nOutBytes to find the required length.

@warning [Changed in v11.1] This function now returns an error if it finds an illegal character in the input string (previously any non-hex character was just ignored). Whitespace characters and ASCII punctuation characters are still allowed and ignored (so "DE:AD:BE:EF" is OK) but characters like those in the range [G-Zg-z] that are obviously non-hex will cause an error.

Example (VBA core function)

The following wrapper function will return the decoded bytes directly, with a default return value that won't cause a run-time error in the calling code.

Public Function cnvBytesFromHexStr(strHex As String) As Byte()
' Returns byte array decoded from a hex string
    Dim abData() As Byte
    Dim nDataLen As Long
    
    ' Set default return value that won't cause a run-time error
    cnvBytesFromHexStr = vbNullString
    nDataLen = CNV_BytesFromHexStr(0, 0, strHex)
    If nDataLen <= 0 Then
        Exit Function
    End If
    ReDim abData(nDataLen - 1)
    nDataLen = CNV_BytesFromHexStr(abData(0), nDataLen, strHex)
    If nDataLen <= 0 Then
        Exit Function
    End If
    ReDim Preserve abData(nDataLen - 1)
    cnvBytesFromHexStr = abData
End Function

New stricter behaviour in [v11.1]

Old behaviour in the VBA immediate window:

? cnvHexStrFromBytes(cnvBytesFromHexStr("DEAGBEEF"))
DEABEE

Result is 3 bytes long. Invalid letter 'G' is silently ignored. Then the final odd letter 'F' is stripped.

New behaviour:

? cnvHexStrFromBytes(cnvBytesFromHexStr("DEAGBEEF"))

? PKI_ErrorCode()
8

Result is 0 bytes long. Error code 8 (INVALID_DATA_ERROR) is set.