Функции кодировки текста ATL

Эти функции поддерживают кодировку текста и декодирование.

Function	Description
AtlGetHexValue	Вызывайте эту функцию для получения числового значения шестнадцатеричной цифры.
AtlGetVersion	Вызовите эту функцию, чтобы получить версию используемой библиотеки ATL.
AtlHexDecode	Декодирует строку данных, закодированных как шестнадцатеричный текст, например при предыдущем вызове AtlHexEncode.
AtlHexDecodeGetRequiredLength	Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из шестнадцатеричной кодированной строки указанной длины.
AtlHexEncode	Вызывайте эту функции для кодирования некоторых данных в виде строки шестнадцатеричного текста.
AtlHexEncodeGetRequiredLength	Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.
AtlHexValue	Вызывайте эту функцию для получения числового значения шестнадцатеричной цифры.
AtlUnicodeToUTF8	Вызывайте эту функцию для преобразования строки Юникода в UTF-8.
BEncode	Вызывайте эту функцию для преобразования некоторых данных с использованием кодировки "B".
BEncodeGetRequiredLength	Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.
EscapeXML	Вызывайте эту функцию для преобразования символов, небезопасных для использования в XML, в их безопасные эквиваленты.
GetExtendedChars	Вызывайте эту функцию для получения количества символов национального алфавита в строке.
IsExtendedChar	Вызовите эту функцию, чтобы узнать, является ли заданный символ расширенным символом (менее 32, больше 126, а не табуляции, строковый канал или возврат каретки).
QEncode	Вызывайте эту функцию для преобразования некоторых данных с использованием кодировки "Q".
QEncodeGetRequiredLength	Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.
QPDecode	Декодирует строку данных, закодированных в формате с кавычками, например при предыдущем вызове QPEncode.
QPDecodeGetRequiredLength	Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из строки указанной длины, закодированной в печатаемом формате с кавычками (quoted-printable).
QPEncode	Вызывайте эту функцию для кодирования некоторых данных в печатаемом формате с кавычками (quoted-printable).
QPEncodeGetRequiredLength	Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.
UUDecode	Декодирует строку данных, которая была uuencoded, например предыдущим вызовом UUEncode.
UUDecodeGetRequiredLength	Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из строки указанной длины в кодировке UUEncode.
UUEncode	Вызывайте эту функцию для кодирования данных в кодировке UUEncode.
UUEncodeGetRequiredLength	Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

Требования

Заголовок: atlenc.h

AtlGetHexValue

Вызывайте эту функцию для получения числового значения шестнадцатеричной цифры.

inline char AtlGetHexValue(char chIn) throw();

Параметры

подбородок
Шестнадцатеричный символ "0"-'9", "A"-"F" или "a"-'f".

Возвращаемое значение

Числовое значение входного символа, интерпретированного как шестнадцатеричная цифра. Например, входные данные "0" возвращают значение 0, а входные данные "A" возвращают значение 10. Если входной символ не является шестнадцатеричной цифрой, эта функция возвращает -1.

AtlGetVersion

Вызовите эту функцию, чтобы получить версию используемой библиотеки ATL.

ATLAPI_(DWORD) AtlGetVersion(void* pReserved);

Параметры

консервированный
Зарезервированный указатель.

Возвращаемое значение

Возвращает целочисленное значение DWORD версии библиотеки ATL, скомпилированной или запущенной.

Пример

Функция должна вызываться следующим образом.

DWORD ver;
ver = AtlGetVersion(NULL);   

Требования

Заголовок: atlbase.h

AtlHexDecode

Декодирует строку данных, закодированных как шестнадцатеричный текст, например при предыдущем вызове AtlHexEncode.

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

Параметры

pSrcData
Строка, содержащая данные, которые необходимо декодировать.

nSrcLen
Длина символов pSrcData.

pbDest
Выделенный вызывающим буфером для получения декодированных данных.

pnDestLen
Указатель на переменную, содержащую длину в байтах pbDest. Если функция выполнена успешно, переменная получает количество байтов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в байтах буфера.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

AtlHexDecodeGetRequiredLength

Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из шестнадцатеричной кодированной строки указанной длины.

inline int AtlHexDecodeGetRequiredLength(int nSrcLen) throw();

Параметры

nSrcLen
Число символов в закодированной строке.

Возвращаемое значение

Количество байтов, необходимых для буфера, который может содержать декодированную строку символов nSrcLen .

AtlHexEncode

Вызывайте эту функции для кодирования некоторых данных в виде строки шестнадцатеричного текста.

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

Параметры

pbSrcData
Буфер, содержащий данные, которые необходимо закодировать.

nSrcLen
Длина в байтах данных, закодированных.

szDest
Выделенный вызывающим буфером для получения закодированных данных.

pnDestLen
Указатель на переменную, содержащую длину символов szDest. Если функция выполнена успешно, переменная получает количество символов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в символах буфера.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Каждый байт исходных данных закодирован как 2 шестнадцатеричные символы.

AtlHexEncodeGetRequiredLength

Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

inline int AtlHexEncodeGetRequiredLength(int nSrcLen) throw();

Параметры

nSrcLen
Количество байтов данных, закодированных.

Возвращаемое значение

Количество символов, необходимых для буфера, который может содержать закодированные данные nSrcLen байтов.

AtlHexValue

Вызывайте эту функцию для получения числового значения шестнадцатеричной цифры.

inline short AtlHexValue(char chIn) throw();

Параметры

подбородок
Шестнадцатеричный символ "0"-'9", "A"-"F" или "a"-'f".

Возвращаемое значение

Числовое значение входного символа, интерпретированного как шестнадцатеричная цифра. Например, входные данные "0" возвращают значение 0, а входные данные "A" возвращают значение 10. Если входной символ не является шестнадцатеричной цифрой, эта функция возвращает -1.

AtlUnicodeToUTF8

Вызывайте эту функцию для преобразования строки Юникода в UTF-8.

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

Параметры

wszSrc
Строка Юникода для преобразования

nSrc
Длина символов строки Юникода.

szDest
Выделенный вызывающим буфером для получения преобразованной строки.

nDest
Длина буфера в байтах.

Возвращаемое значение

Возвращает количество символов для преобразованной строки.

Замечания

Чтобы определить размер буфера, необходимого для преобразованной строки, вызовите эту функцию, передаваемую 0 для szDest и nDest.

BEncode

Вызывайте эту функцию для преобразования некоторых данных с использованием кодировки "B".

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

Параметры

pbSrcData
Буфер, содержащий данные, которые необходимо закодировать.

nSrcLen
Длина в байтах данных, закодированных.

szDest
Выделенный вызывающим буфером для получения закодированных данных.

pnDestLen
Указатель на переменную, содержащую длину символов szDest. Если функция выполнена успешно, переменная получает количество символов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в символах буфера.

pszCharSet
Набор символов, используемый для преобразования.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Схема кодирования "B" описана в RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

BEncodeGetRequiredLength

Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

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

Параметры

nSrcLen
Количество байтов данных, закодированных.

nCharsetLen
Длина в символах набора символов, используемых для преобразования.

Возвращаемое значение

Количество символов, необходимых для буфера, который может содержать закодированные данные nSrcLen байтов.

Замечания

Схема кодирования "B" описана в RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

EscapeXML

Вызывайте эту функцию для преобразования символов, небезопасных для использования в XML, в их безопасные эквиваленты.

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

Параметры

szIn
Строка для преобразования.

nSrclen
Длина в символах строки, которая будет преобразована.

szEsc
Выделенный вызывающим буфером для получения преобразованной строки.

nDestLen
Длина в символах выделенного вызывающего буфера.

dwFlags
ATL_ESC Флаги, описывающие способ выполнения преобразования.

• ATL_ESC_FLAG_NONE по умолчанию. Кавычки и апострофы не преобразуются.
• ATL_ESC_FLAG_ATTR кавычки и апострофы преобразуются в " и ' соответственно.

Возвращаемое значение

Длина в символах преобразованной строки.

Замечания

Возможные преобразования, выполняемые этой функцией, отображаются в таблице:

Источник	Назначение
<	<
>	>
&	&
'	'
"	"

GetExtendedChars

Вызывайте эту функцию для получения количества символов национального алфавита в строке.

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

Параметры

szSrc
Строка для анализа.

nSrcLen
Длина строки в символах.

Возвращаемое значение

Возвращает число расширенных символов, найденных в строке, как определено IsExtendedChar.

IsExtendedChar

Вызовите эту функцию, чтобы узнать, является ли заданный символ расширенным символом (менее 32, больше 126, а не табуляции, строковый канал или возврат каретки).

inline int IsExtendedChar(char ch) throw();

Параметры

ch
Проверяемый символ

Возвращаемое значение

ЗНАЧЕНИЕ TRUE, если символ расширен, значение FALSE в противном случае.

QEncode

Вызывайте эту функцию для преобразования некоторых данных с использованием кодировки "Q".

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

Параметры

pbSrcData
Буфер, содержащий данные, которые необходимо закодировать.

nSrcLen
Длина в байтах данных, закодированных.

szDest
Выделенный вызывающим буфером для получения закодированных данных.

pnDestLen
Указатель на переменную, содержащую длину символов szDest. Если функция выполнена успешно, переменная получает количество символов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в символах буфера.

pszCharSet
Набор символов, используемый для преобразования.

pnNumEncoded
Указатель на переменную, которая при возврате содержит количество небезопасных символов, которые должны быть преобразованы.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Схема кодирования "Q" описана в RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QEncodeGetRequiredLength

Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

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

Параметры

nSrcLen
Количество байтов данных, закодированных.

nCharsetLen
Длина в символах набора символов, используемых для преобразования.

Возвращаемое значение

Количество символов, необходимых для буфера, который может содержать закодированные данные nSrcLen байтов.

Замечания

Схема кодирования "Q" описана в RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QPDecode

Декодирует строку данных, закодированных в формате с кавычками, например при предыдущем вызове QPEncode.

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

Параметры

pbSrcData
[in] Буфер, содержащий данные, которые необходимо декодировать.

nSrcLen
[in] Длина в байтах pbSrcData.

szDest
[out] Выделенный вызывающим буфером для получения декодированных данных.

pnDestLen
[out] Указатель на переменную, содержащую длину в байтах szDest. Если функция выполнена успешно, переменная получает количество байтов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в байтах буфера.

dwFlags
[in] ATLSMTP_QPENCODE флаги, описывающие способ выполнения преобразования.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Схема кодирования с кавычками описана в RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPDecodeGetRequiredLength

Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из строки указанной длины, закодированной в печатаемом формате с кавычками (quoted-printable).

inline int QPDecodeGetRequiredLength(int nSrcLen) throw();

Параметры

nSrcLen
Число символов в закодированной строке.

Возвращаемое значение

Количество байтов, необходимых для буфера, который может содержать декодированную строку символов nSrcLen .

Замечания

Схема кодирования с кавычками описана в RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncode

Вызывайте эту функцию для кодирования некоторых данных в печатаемом формате с кавычками (quoted-printable).

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

Параметры

pbSrcData
Буфер, содержащий данные, которые необходимо закодировать.

nSrcLen
Длина в байтах данных, закодированных.

szDest
Выделенный вызывающим буфером для получения закодированных данных.

pnDestLen
Указатель на переменную, содержащую длину символов szDest. Если функция выполнена успешно, переменная получает количество символов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в символах буфера.

dwFlags
ATLSMTP_QPENCODE флаги, описывающие способ выполнения преобразования.

• ATLSMTP_QPENCODE_DOT Если период отображается в начале строки, он добавляется в выходные данные, а также кодируется.

• ATLSMTP_QPENCODE_TRAILING_SOFT добавляется =\r\n в закодированную строку.

Схема кодирования, допускаемая для печати, описана в RFC 2045.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Схема кодирования с кавычками описана в RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncodeGetRequiredLength

Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

inline int QPEncodeGetRequiredLength(int nSrcLen) throw ();

Параметры

nSrcLen
Количество байтов данных, закодированных.

Возвращаемое значение

Количество символов, необходимых для буфера, который может содержать закодированные данные nSrcLen байтов.

Замечания

Схема кодирования с кавычками описана в RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

UUDecode

Декодирует строку данных, которая была uuencoded, например предыдущим вызовом UUEncode.

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

Параметры

pbSrcData
Строка, содержащая данные, которые необходимо декодировать.

nSrcLen
Длина в байтах pbSrcData.

pbDest
Выделенный вызывающим буфером для получения декодированных данных.

pnDestLen
Указатель на переменную, содержащую длину в байтах pbDest. Если функция выполнена успешно, переменная получает количество байтов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в байтах буфера.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Эта реализация uuencoding следует спецификации POSIX P1003.2b/D11.

UUDecodeGetRequiredLength

Вызывайте эту функцию для получения размера (в байтах) буфера, который может содержать декодированные данные из строки указанной длины в кодировке UUEncode.

inline int UUDecodeGetRequiredLength(int nSrcLen) throw ();

Параметры

nSrcLen
Число символов в закодированной строке.

Возвращаемое значение

Количество байтов, необходимых для буфера, который может содержать декодированную строку символов nSrcLen .

Замечания

Эта реализация uuencoding следует спецификации POSIX P1003.2b/D11.

UUEncode

Вызывайте эту функцию для кодирования данных в кодировке UUEncode.

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

Параметры

pbSrcData
Буфер, содержащий данные, которые необходимо закодировать.

nSrcLen
Длина в байтах данных, закодированных.

szDest
Выделенный вызывающим буфером для получения закодированных данных.

pnDestLen
Указатель на переменную, содержащую длину символов szDest. Если функция выполнена успешно, переменная получает количество символов, записанных в буфер. Если функция завершается ошибкой, переменная получает необходимую длину в символах буфера.

lpszFile
Файл, добавляемый в заголовок, при указании ATLSMTP_UUENCODE_HEADER в dwFlags.

dwFlags
Флаги, управляющие поведением этой функции.

• ATLSMTP_UUENCODE_HEADE заголовок будет закодирован.

• ATLSMTP_UUENCODE_END конец будет закодирован.

• ATLSMTP_UUENCODE_DOT будут выполняться материалы данных.

Возвращаемое значение

Возвращает значение TRUE при успешном выполнении, false при сбое.

Замечания

Эта реализация uuencoding следует спецификации POSIX P1003.2b/D11.

UUEncodeGetRequiredLength

Вызывайте эту функцию для получения размера (в символах) буфера, который может содержать строку, закодированную из данных указанного размера.

inline int UUEncodeGetRequiredLength(int nSrcLen) throw ();

Параметры

nSrcLen
Количество байтов данных, закодированных.

Возвращаемое значение

Количество символов, необходимых для буфера, который может содержать закодированные данные nSrcLen байтов.

Замечания

Эта реализация uuencoding следует спецификации POSIX P1003.2b/D11.

См. также

Основные понятия
Компоненты ATL COM Desktop