(v13) Character transcoding functions
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
The PFI provides the following character transcoding functions:
Convert a PlgFwTextString into Unicode
This function converts a PlgFwTextString
of given length into Unicode and writes it into a pre‐allocated Unicode string. Any zero PlgFwTextByte
in the input causes premature termination of the input string.
The caller must ensure that the pre‐allocated buffer is large enough to receive the output; it should have room for as many 16‐bit Unicode characters as there are bytes (not characters) in the input string, plus one for the Unicode terminator. The function has the following parameters:
ptb
: a pointer to the input string.cbInLength
: the number of bytes (not characters) in the input string.puc
: a pointer to the pre‐allocated buffer for the output Unicode string.cucAllocSize
: the size of the output buffer in 16‐bit Unicode characters.fAllowInvalid
: determines the behavior when an invalid encoding is encountered. IfFALSE
, an invalid encoding is considered an error and zero returned. IfTRUE
, the Unicode “Unknown Character” (0xFFFD
) is substituted for each invalid character.
The function returns the number of Unicode characters written to puc
, not including the zero terminator.
uint32 PlgFwUniFromNTextStringToBuffer(
int32 fAllowInvalid, PlgFwTextByte * ptb, uint32 cbInLength, PlgFwUniChar * puc, uint32 cucAllocSize);
Convert a Unicode string into a PlgFwStrRecord
This function converts a UTF‐16 string (puc)
of given length (cucInLength
, specified in Unicode char‐ acters) into a PlgFwStrRecord (pRecord)
. The function returns the number of bytes inserted.
Any zero Unicode character will cause premature termination of the input.
uint32 PlgFwStrNPutUnicode(
PlgFwStrRecord * pRecord, PlgFwUniChar * puc, uint32 cucInLength )
Convert a PlgFwTextString string into an unterminated UTF-8 buffer
This function converts a PlgFwTextString
pointed to by ptb
into UTF‐8 format and writes it to a non-zero terminated UTF‐8 buffer (putf8
), the length of which is specified, in bytes, by cbAllocLength
.
The function returns the number of bytes written to the output buffer.
Note:
In the current implementation, fAllowInvalid
is ignored instead the function fails, returning
0
, if an invalid encoding is encountered.
uint32 PlgFwStrToUTF8Buffer(
int32 fAllowInvalid, PlgFwTextByte * ptb, uint32 cbInLength, PlgFwUTF8Char * putf8, uint32 cbAllocLength);
Convert a UTF-8 string of given length (in bytes) into a PlgFwStrRecord.
This function converts a given length of a UTF‐8 string (pointed to by putf8
) and copies it into a PlgFwStrRecord (pRecord)
, allowing for a BOM (Byte order mark) at the start of the UTF‐8 string. Since the length to convert (cbInLength)
is specified in bytes, not characters, be careful not to supply a length which would terminate it in the middle of an of a UTF‐8 encoded character: this could corrupt a message and possibly lead to other, undesirable, behavior.
Any zero character in putf8
will cause premature termination of the input. The function returns the number of bytes inserted into pRecord
.
uint32 PlgFwStrNPutUTF8(
PlgFwStrRecord * pRecord, PlgFwUTF8Char * putf8, uint32 cbInLength);
Convert a UTF-16 buffer to a non-zero terminated UTF-8 buffer.
This function converts a given length of a UTF‐16 buffer (pointed to by puc
) into a non-zero terminated UTF‐8 buffer (putf8
). cbAllocLength
specifies the length, in bytes, of the destination buffer.
The function returns the number of bytes written to the output buffer.
uint32 PlgFwUniToUTF8Buffer(
PlgFwUniChar * puc, uint32 cucInLength, PlgFwUTF8Char * putf8, uint32 cbAllocLength);
Convert a UTF-8 buffer into an UTF-16 buffer
This function converts a given length of a UTF‐8 buffer (putf8
) to a UTF‐16 buffer (puc)
, allowing for a Byte Order Mark (BOM) at the start of the UTF‐8 string. cucAllocSize
specifies the length, in Uni‐ code chars, of the destination buffer.
The function returns the number of Unicode chars written to the output buffer.
uint32 PlgFwUniFromNUTF8ToBuffer(
PlgFwUTF8Char * putf8, uint32 cbInLength, PlgFwUniChar * puc, uint32 cucAllocSize);