Edit

ATL Text Encoding Functions

  • Article

These functions support text encoding and decoding.

Function Description
AtlGetHexValue Call this function to get the numeric value of a hexadecimal digit.
AtlGetVersion Call this function to get the version of the ATL library that you are using.
AtlHexDecode Decodes a string of data that has been encoded as hexadecimal text such as by a previous call to AtlHexEncode.
AtlHexDecodeGetRequiredLength Call this function to get the size in bytes of a buffer that could contain data decoded from a hex-encoded string of the specified length.
AtlHexEncode Call this function to encode some data as a string of hexadecimal text.
AtlHexEncodeGetRequiredLength Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.
AtlHexValue Call this function to get the numeric value of a hexadecimal digit.
AtlUnicodeToUTF8 Call this function to convert a Unicode string to UTF-8.
BEncode Call this function to convert some data using the "B" encoding.
BEncodeGetRequiredLength Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.
EscapeXML Call this function to convert characters that are unsafe for use in XML to their safe equivalents.
GetExtendedChars Call this function to get the number of extended characters in a string.
IsExtendedChar Call this function to find out if a given character is an extended character (less than 32, greater than 126, and not a tab, line feed or carriage return)
QEncode Call this function to convert some data using the "Q" encoding.
QEncodeGetRequiredLength Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.
QPDecode Decodes a string of data that has been encoded in quoted-printable format such as by a previous call to QPEncode.
QPDecodeGetRequiredLength Call this function to get the size in bytes of a buffer that could contain data decoded from quoted-printable-encoded string of the specified length.
QPEncode Call this function to encode some data in quoted-printable format.
QPEncodeGetRequiredLength Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.
UUDecode Decodes a string of data that has been uuencoded such as by a previous call to UUEncode.
UUDecodeGetRequiredLength Call this function to get the size in bytes of a buffer that could contain data decoded from a uuencoded string of the specified length.
UUEncode Call this function to uuencode some data.
UUEncodeGetRequiredLength Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

Requirements

Header: atlenc.h

AtlGetHexValue

Call this function to get the numeric value of a hexadecimal digit.

inline char AtlGetHexValue(char chIn) throw();

Parameters

chIn
The hexadecimal character '0'-'9', 'A'-'F', or 'a'-'f'.

Return Value

The numeric value of the input character interpreted as a hexadecimal digit. For example, an input of '0' returns a value of 0 and an input of 'A' returns a value of 10. If the input character is not a hexadecimal digit, this function returns -1.

AtlGetVersion

Call this function to get the version of the ATL library that you are using.

ATLAPI_(DWORD) AtlGetVersion(void* pReserved);

Parameters

pReserved
A reserved pointer.

Return Value

Returns a DWORD integer value of the version of the ATL library that you are compiling or running.

Example

The function should be called as follows.

DWORD ver;
ver = AtlGetVersion(NULL);

Requirements

Header: atlbase.h

AtlHexDecode

Decodes a string of data that has been encoded as hexadecimal text such as by a previous call to AtlHexEncode.

inline BOOL AtlHexDecode(
   LPCSTR pSrcData,
   int nSrcLen,
   LPBYTE pbDest,
   int* pnDestLen) throw();

Parameters

pSrcData
The string containing the data to be decoded.

nSrcLen
The length in characters of pSrcData.

pbDest
Caller-allocated buffer to receive the decoded data.

pnDestLen
Pointer to a variable that contains the length in bytes of pbDest. If the function succeeds, the variable receives the number of bytes written to the buffer. If the function fails, the variable receives the required length in bytes of the buffer.

Return Value

Returns TRUE on success, FALSE on failure.

AtlHexDecodeGetRequiredLength

Call this function to get the size in bytes of a buffer that could contain data decoded from a hex-encoded string of the specified length.

inline int AtlHexDecodeGetRequiredLength(int nSrcLen) throw();

Parameters

nSrcLen
The number of characters in the encoded string.

Return Value

The number of bytes required for a buffer that could hold a decoded string of nSrcLen characters.

AtlHexEncode

Call this function to encode some data as a string of hexadecimal text.

inline BOOL AtlHexEncode(
   const BYTE * pbSrcData,
   int nSrcLen,
   LPSTR szDest,
int * pnDestLen) throw();

Parameters

pbSrcData
The buffer containing the data to be encoded.

nSrcLen
The length in bytes of the data to be encoded.

szDest
Caller-allocated buffer to receive the encoded data.

pnDestLen
Pointer to a variable that contains the length in characters of szDest. If the function succeeds, the variable receives the number of characters written to the buffer. If the function fails, the variable receives the required length in characters of the buffer.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Each byte of source data is encoded as 2 hexadecimal characters.

AtlHexEncodeGetRequiredLength

Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

inline int AtlHexEncodeGetRequiredLength(int nSrcLen) throw();

Parameters

nSrcLen
The number of bytes of data to be encoded.

Return Value

The number of characters required for a buffer that could hold encoded data of nSrcLen bytes.

AtlHexValue

Call this function to get the numeric value of a hexadecimal digit.

inline short AtlHexValue(char chIn) throw();

Parameters

chIn
The hexadecimal character '0'-'9', 'A'-'F', or 'a'-'f'.

Return Value

The numeric value of the input character interpreted as a hexadecimal digit. For example, an input of '0' returns a value of 0 and an input of 'A' returns a value of 10. If the input character is not a hexadecimal digit, this function returns -1.

AtlUnicodeToUTF8

Call this function to convert a Unicode string to UTF-8.

ATL_NOINLINE inline int AtlUnicodeToUTF8(
   LPCWSTR wszSrc,
   int nSrc,
   LPSTR szDest,
   int nDest) throw();

Parameters

wszSrc
The Unicode string to be converted

nSrc
The length in characters of the Unicode string.

szDest
Caller-allocated buffer to receive the converted string.

nDest
The length in bytes of the buffer.

Return Value

Returns the number of characters for the converted string.

Remarks

To determine the size of the buffer required for the converted string, call this function passing 0 for szDest and nDest.

BEncode

Call this function to convert some data using the "B" encoding.

inline BOOL BEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCSTR pszCharSet) throw();

Parameters

pbSrcData
The buffer containing the data to be encoded.

nSrcLen
The length in bytes of the data to be encoded.

szDest
Caller-allocated buffer to receive the encoded data.

pnDestLen
Pointer to a variable that contains the length in characters of szDest. If the function succeeds, the variable receives the number of characters written to the buffer. If the function fails, the variable receives the required length in characters of the buffer.

pszCharSet
The character set to use for the conversion.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The "B" encoding scheme is described in RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

BEncodeGetRequiredLength

Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

inline int BEncodeGetRequiredLength(int nSrcLen, int nCharsetLen) throw();

Parameters

nSrcLen
The number of bytes of data to be encoded.

nCharsetLen
The length in characters of the character set to use for the conversion.

Return Value

The number of characters required for a buffer that could hold encoded data of nSrcLen bytes.

Remarks

The "B" encoding scheme is described in RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

EscapeXML

Call this function to convert characters that are unsafe for use in XML to their safe equivalents.

inline int EscapeXML(
   const wchar_t * szIn,
   int nSrcLen,
   wchar_t * szEsc,
   int nDestLen,
   DWORD dwFlags = ATL_ESC_FLAG_NONE) throw();

Parameters

szIn
The string to be converted.

nSrclen
The length in characters of the string to be converted.

szEsc
Caller-allocated buffer to receive the converted string.

nDestLen
The length in characters of the caller-allocated buffer.

dwFlags
ATL_ESC Flags describing how the conversion is to be performed.

  • ATL_ESC_FLAG_NONE Default behavior. Quote marks and apostrophes are not converted.
  • ATL_ESC_FLAG_ATTR Quote marks and apostrophes are converted to " and ' respectively.

Return Value

The length in characters of the converted string.

Remarks

Possible conversions performed by this function are shown in the table:

Source Destination
< &lt;
> &gt;
& &amp;
' &apos;
" &quot;

GetExtendedChars

Call this function to get the number of extended characters in a string.

inline int GetExtendedChars(LPCSTR szSrc, int nSrcLen) throw();

Parameters

szSrc
The string to be analyzed.

nSrcLen
The length of the string in characters.

Return Value

Returns the number of extended characters found within the string as determined by IsExtendedChar.

IsExtendedChar

Call this function to find out if a given character is an extended character (less than 32, greater than 126, and not a tab, line feed or carriage return)

inline int IsExtendedChar(char ch) throw();

Parameters

ch
The character to be tested

Return Value

TRUE if the character is extended, FALSE otherwise.

QEncode

Call this function to convert some data using the "Q" encoding.

inline BOOL QEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCSTR pszCharSet,
   int* pnNumEncoded = NULL) throw();

Parameters

pbSrcData
The buffer containing the data to be encoded.

nSrcLen
The length in bytes of the data to be encoded.

szDest
Caller-allocated buffer to receive the encoded data.

pnDestLen
Pointer to a variable that contains the length in characters of szDest. If the function succeeds, the variable receives the number of characters written to the buffer. If the function fails, the variable receives the required length in characters of the buffer.

pszCharSet
The character set to use for the conversion.

pnNumEncoded
A pointer to a variable that on return contains the number of unsafe characters that had to be converted.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The "Q" encoding scheme is described in RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QEncodeGetRequiredLength

Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

inline int QEncodeGetRequiredLength(int nSrcLen, int nCharsetLen) throw();

Parameters

nSrcLen
The number of bytes of data to be encoded.

nCharsetLen
The length in characters of the character set to use for the conversion.

Return Value

The number of characters required for a buffer that could hold encoded data of nSrcLen bytes.

Remarks

The "Q" encoding scheme is described in RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QPDecode

Decodes a string of data that has been encoded in quoted-printable format such as by a previous call to QPEncode.

inline BOOL QPDecode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   DWORD dwFlags = 0) throw();

Parameters

pbSrcData
[in] The buffer containing the data to be decoded.

nSrcLen
[in] The length in bytes of pbSrcData.

szDest
[out] Caller-allocated buffer to receive the decoded data.

pnDestLen
[out] Pointer to a variable that contains the length in bytes of szDest. If the function succeeds, the variable receives the number of bytes written to the buffer. If the function fails, the variable receives the required length in bytes of the buffer.

dwFlags
[in] ATLSMTP_QPENCODE flags describing how the conversion is to be performed.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The quoted-printable encoding scheme is described in RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPDecodeGetRequiredLength

Call this function to get the size in bytes of a buffer that could contain data decoded from quoted-printable-encoded string of the specified length.

inline int QPDecodeGetRequiredLength(int nSrcLen) throw();

Parameters

nSrcLen
The number of characters in the encoded string.

Return Value

The number of bytes required for a buffer that could hold a decoded string of nSrcLen characters.

Remarks

The quoted-printable encoding scheme is described in RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncode

Call this function to encode some data in quoted-printable format.

inline BOOL QPEncode(
   BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   DWORD dwFlags = 0) throw ();

Parameters

pbSrcData
The buffer containing the data to be encoded.

nSrcLen
The length in bytes of the data to be encoded.

szDest
Caller-allocated buffer to receive the encoded data.

pnDestLen
Pointer to a variable that contains the length in characters of szDest. If the function succeeds, the variable receives the number of characters written to the buffer. If the function fails, the variable receives the required length in characters of the buffer.

dwFlags
ATLSMTP_QPENCODE flags describing how the conversion is to be performed.

  • ATLSMTP_QPENCODE_DOT If a period appears at the start of a line, it is added to the output as well as encoded.

  • ATLSMTP_QPENCODE_TRAILING_SOFT Appends =\r\n to the encoded string.

The quoted-printable encoding scheme is described in RFC 2045.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

The quoted-printable encoding scheme is described in RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncodeGetRequiredLength

Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

inline int QPEncodeGetRequiredLength(int nSrcLen) throw ();

Parameters

nSrcLen
The number of bytes of data to be encoded.

Return Value

The number of characters required for a buffer that could hold encoded data of nSrcLen bytes.

Remarks

The quoted-printable encoding scheme is described in RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

UUDecode

Decodes a string of data that has been uuencoded such as by a previous call to UUEncode.

inline BOOL UUDecode(
   BYTE* pbSrcData,
   int nSrcLen,
   BYTE* pbDest,
   int* pnDestLen) throw ();

Parameters

pbSrcData
The string containing the data to be decoded.

nSrcLen
The length in bytes of pbSrcData.

pbDest
Caller-allocated buffer to receive the decoded data.

pnDestLen
Pointer to a variable that contains the length in bytes of pbDest. If the function succeeds, the variable receives the number of bytes written to the buffer. If the function fails, the variable receives the required length in bytes of the buffer.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This uuencoding implementation follows the POSIX P1003.2b/D11 specification.

UUDecodeGetRequiredLength

Call this function to get the size in bytes of a buffer that could contain data decoded from a uuencoded string of the specified length.

inline int UUDecodeGetRequiredLength(int nSrcLen) throw ();

Parameters

nSrcLen
The number of characters in the encoded string.

Return Value

The number of bytes required for a buffer that could hold a decoded string of nSrcLen characters.

Remarks

This uuencoding implementation follows the POSIX P1003.2b/D11 specification.

UUEncode

Call this function to uuencode some data.

inline BOOL UUEncode(
   const BYTE* pbSrcData,
   int nSrcLen,
   LPSTR szDest,
   int* pnDestLen,
   LPCTSTR lpszFile = _T("file"),
   DWORD dwFlags = 0) throw ();

Parameters

pbSrcData
The buffer containing the data to be encoded.

nSrcLen
The length in bytes of the data to be encoded.

szDest
Caller-allocated buffer to receive the encoded data.

pnDestLen
Pointer to a variable that contains the length in characters of szDest. If the function succeeds, the variable receives the number of characters written to the buffer. If the function fails, the variable receives the required length in characters of the buffer.

lpszFile
The file to be added to the header when ATLSMTP_UUENCODE_HEADER is specified in dwFlags.

dwFlags
Flags controlling the behavior of this function.

  • ATLSMTP_UUENCODE_HEADE The header will be encoded.

  • ATLSMTP_UUENCODE_END The end will be encoded.

  • ATLSMTP_UUENCODE_DOT Data stuffing will be performed.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This uuencoding implementation follows the POSIX P1003.2b/D11 specification.

UUEncodeGetRequiredLength

Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.

inline int UUEncodeGetRequiredLength(int nSrcLen) throw ();

Parameters

nSrcLen
The number of bytes of data to be encoded.

Return Value

The number of characters required for a buffer that could hold encoded data of nSrcLen bytes.

Remarks

This uuencoding implementation follows the POSIX P1003.2b/D11 specification.

See also

Concepts
ATL COM Desktop Components