Funções de codificação de texto da ATL

Essas funções dão suporte à codificação e à decodificação de texto.

Função	Descrição
AtlGetHexValue	Chame essa função para obter o valor numérico de um dígito hexadecimal.
AtlGetVersion	Chame essa função para obter a versão da biblioteca da ATL que você está usando.
AtlHexDecode	Decodifica uma cadeia de caracteres de dados que foi codificada como texto hexadecimal, como por uma chamada anterior a AtlHexEncode.
AtlHexDecodeGetRequiredLength	Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação hexadecimal do comprimento especificado.
AtlHexEncode	Chame essa função para codificar alguns dados como uma cadeia de caracteres de texto hexadecimal.
AtlHexEncodeGetRequiredLength	Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.
AtlHexValue	Chame essa função para obter o valor numérico de um dígito hexadecimal.
AtlUnicodeToUTF8	Chame essa função para converter uma cadeia de caracteres Unicode em UTF-8.
Código BEncode	Chame essa função para converter alguns dados usando a codificação “B”.
BEncodeGetRequiredLength	Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.
Escape XML	Chame essa função para converter os caracteres que não são seguros para uso em XML em seus equivalentes seguros.
GetExtendedChars	Chame essa função para obter o número de caracteres estendidos em uma cadeia de caracteres.
ÉExtendedChar	Chame essa função para descobrir se um caractere fornecido é um caractere estendido (menor que 32, maior que 126, e não uma guia, um avanço de linha ou retorno de carro)
QEncode	Chame essa função para converter alguns dados usando a codificação “Q”.
QEncodeGetRequiredLength	Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.
QPDecode	Decodifica uma cadeia de caracteres de dados que foi codificada no formato entre aspas imprimível, como por uma chamada anterior a QPEncode.
QPDecodeGetRequiredLength	Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação entre aspas imprimível do comprimento especificado.
QPEncode	Chame essa função para codificar alguns dados no formato entre aspas imprimível.
QPEncodeGetRequiredLength	Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.
UUDecode	Decodifica uma cadeia de caracteres de dados que foi codificada em UU, como por uma chamada anterior a UUEncode.
UUDecodeGetRequiredLength	Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação UU do comprimento especificado.
UUEncode	Chame essa função para codificar alguns dados em UU.
UUEncodeGetRequiredLength	Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

Requisitos

Cabeçalho: atlenc.h

AtlGetHexValue

Chame essa função para obter o valor numérico de um dígito hexadecimal.

inline char AtlGetHexValue(char chIn) throw();

Parâmetros

chIn
O caractere hexadecimal '0'-'9', 'A'-'F' ou 'a'-'f'.

Valor de retorno

O valor numérico do caractere de entrada interpretado como um dígito hexadecimal. Por exemplo, uma entrada de '0' retorna um valor de 0 e uma entrada de 'A' retorna um valor de 10. Se o caractere de entrada não for um dígito hexadecimal, essa função retornará -1.

AtlGetVersion

Chame essa função para obter a versão da biblioteca da ATL que você está usando.

ATLAPI_(DWORD) AtlGetVersion(void* pReserved);

Parâmetros

pReserved
Um ponteiro reservado.

Valor de retorno

Retorna um valor inteiro DWORD da versão da biblioteca da ATL que você está compilando ou executando.

Exemplo

A função deve ser chamada da seguinte maneira.

DWORD ver;
ver = AtlGetVersion(NULL);   

Requisitos

Cabeçalho: atlbase.h

AtlHexDecode

Decodifica uma cadeia de caracteres de dados que foi codificada como texto hexadecimal, como por uma chamada anterior a AtlHexEncode.

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

Parâmetros

pSrcData
A cadeia de caracteres que contém os dados a serem decodificados.

nSrcLen
O tamanho em caracteres de pSrcData.

pbDest
Buffer alocado por chamador para receber os dados decodificados.

pnDestLen
Ponteiro para uma variável que contém o tamanho em bytes de pbDest. Se a função for bem-sucedida, a variável receberá o número de bytes gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

AtlHexDecodeGetRequiredLength

Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação hexadecimal do comprimento especificado.

inline int AtlHexDecodeGetRequiredLength(int nSrcLen) throw();

Parâmetros

nSrcLen
O número de caracteres na cadeia de caracteres codificada.

Valor de retorno

O número de bytes necessários para um buffer que poderia conter uma cadeia de caracteres decodificada de caracteres nSrcLen.

AtlHexEncode

Chame essa função para codificar alguns dados como uma cadeia de caracteres de texto hexadecimal.

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

Parâmetros

pbSrcData
O buffer que contém os dados a serem codificados.

nSrcLen
O tamanho em bytes dos dados a serem codificados.

szDest
O buffer alocado por chamador para receber os dados decodificados.

pnDestLen
O ponteiro para uma variável que contém o comprimento em caracteres de szDest. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Cada byte de dados de origem é codificado como dois caracteres hexadecimais.

AtlHexEncodeGetRequiredLength

Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

inline int AtlHexEncodeGetRequiredLength(int nSrcLen) throw();

Parâmetros

nSrcLen
O número de bytes de dados a serem codificados.

Valor de retorno

O número de caracteres necessários para um buffer que poderia conter dados codificados de bytes nSrcLen.

AtlHexValue

Chame essa função para obter o valor numérico de um dígito hexadecimal.

inline short AtlHexValue(char chIn) throw();

Parâmetros

chIn
O caractere hexadecimal '0'-'9', 'A'-'F' ou 'a'-'f'.

Valor de retorno

O valor numérico do caractere de entrada interpretado como um dígito hexadecimal. Por exemplo, uma entrada de '0' retorna um valor de 0 e uma entrada de 'A' retorna um valor de 10. Se o caractere de entrada não for um dígito hexadecimal, essa função retornará -1.

AtlUnicodeToUTF8

Chame essa função para converter uma cadeia de caracteres Unicode em UTF-8.

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

Parâmetros

wszSrc
A cadeia de caracteres Unicode a ser convertida

nSrc
O tamanho em caracteres da cadeia de caracteres Unicode.

szDest
O buffer alocado pelo chamador para receber a cadeia de caracteres convertida.

nDest
O tamanho em bytes do buffer.

Valor de retorno

Retorna o número de caracteres na cadeia de caracteres convertida.

Comentários

Para determinar o tamanho do buffer necessário para a cadeia de caracteres convertida, chame essa função passando 0 para szDest e nDest.

Código BEncode

Chame essa função para converter alguns dados usando a codificação “B”.

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

Parâmetros

pbSrcData
O buffer que contém os dados a serem codificados.

nSrcLen
O tamanho em bytes dos dados a serem codificados.

szDest
O buffer alocado por chamador para receber os dados decodificados.

pnDestLen
O ponteiro para uma variável que contém o comprimento em caracteres de szDest. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

pszCharSet
O conjunto de caracteres a ser usado para a conversão.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O esquema de codificação "B" é descrito no RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

BEncodeGetRequiredLength

Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

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

Parâmetros

nSrcLen
O número de bytes de dados a serem codificados.

nCharsetLen
O tamanho em caracteres do conjunto de caracteres a ser usado para a conversão.

Valor de retorno

O número de caracteres necessários para um buffer que poderia conter dados codificados de bytes nSrcLen.

Comentários

O esquema de codificação "B" é descrito no RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

Escape XML

Chame essa função para converter os caracteres que não são seguros para uso em XML em seus equivalentes seguros.

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

Parâmetros

szIn
A cadeia de caracteres a ser convertida.

nSrclen
O tamanho em caracteres da cadeia de caracteres a ser convertida.

szEsc
O buffer alocado pelo chamador para receber a cadeia de caracteres convertida.

nDestLen
O tamanho em caracteres do buffer alocado pelo chamador.

dwFlags
Os sinalizadores ATL_ESC que descrevem como a conversão deve ser executada.

• Comportamento padrão de ATL_ESC_FLAG_NONE. As aspas e apóstrofos não são convertidos.
• As aspas e apóstrofos ATL_ESC_FLAG_ATTR são convertidos em " e ' respectivamente.

Valor de retorno

O tamanho em caracteres da cadeia de caracteres a ser convertida.

Comentários

As conversões possíveis executadas por essa função são mostradas na tabela:

Origem	Destino
<	<
>	>
&	&
'	'
"	"

GetExtendedChars

Chame essa função para obter o número de caracteres estendidos em uma cadeia de caracteres.

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

Parâmetros

szSrc
A cadeia de caracteres a ser analisada.

nSrcLen
O tamanho da cadeia de caracteres em caracteres.

Valor de retorno

Retorna o número de caracteres estendidos encontrados na cadeia de caracteres, conforme determinado por IsExtendedChar.

ÉExtendedChar

Chame essa função para descobrir se um caractere fornecido é um caractere estendido (menor que 32, maior que 126, e não uma guia, um avanço de linha ou retorno de carro)

inline int IsExtendedChar(char ch) throw();

Parâmetros

Ch
O caractere a ser testado

Valor de retorno

TRUE se o caractere for estendido. Caso contrário, FALSE.

QEncode

Chame essa função para converter alguns dados usando a codificação “Q”.

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

Parâmetros

pbSrcData
O buffer que contém os dados a serem codificados.

nSrcLen
O tamanho em bytes dos dados a serem codificados.

szDest
O buffer alocado por chamador para receber os dados decodificados.

pnDestLen
O ponteiro para uma variável que contém o comprimento em caracteres de szDest. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

pszCharSet
O conjunto de caracteres a ser usado para a conversão.

pnNumEncoded
Um ponteiro para uma variável que contém, no retorno, o número de caracteres desprotegidos que precisaram ser convertidos.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O esquema de codificação "Q" é descrito no RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QEncodeGetRequiredLength

Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

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

Parâmetros

nSrcLen
O número de bytes de dados a serem codificados.

nCharsetLen
O tamanho em caracteres do conjunto de caracteres a ser usado para a conversão.

Valor de retorno

O número de caracteres necessários para um buffer que poderia conter dados codificados de bytes nSrcLen.

Comentários

O esquema de codificação "Q" é descrito no RFC 2047 (https://www.ietf.org/rfc/rfc2047.txt).

QPDecode

Decodifica uma cadeia de caracteres de dados que foi codificada no formato entre aspas imprimível, como por uma chamada anterior a QPEncode.

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

Parâmetros

pbSrcData
[in] O buffer que contém os dados a serem codificados.

nSrcLen
[in] O tamanho em bytes de pbSrcData.

szDest
[out] O buffer alocado pelo chamador para receber os dados decodificados.

pnDestLen
[out] O ponteiro para uma variável que contém o tamanho em bytes de szDest. Se a função for bem-sucedida, a variável receberá o número de bytes gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

dwFlags
[in] Os sinalizadores ATLSMTP_QPENCODE que descrevem como a conversão deve ser executada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O esquema de codificação de aspas imprimíveis é descrito em RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPDecodeGetRequiredLength

Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação entre aspas imprimível do comprimento especificado.

inline int QPDecodeGetRequiredLength(int nSrcLen) throw();

Parâmetros

nSrcLen
O número de caracteres na cadeia de caracteres codificada.

Valor de retorno

O número de bytes necessários para um buffer que poderia conter uma cadeia de caracteres decodificada de caracteres nSrcLen.

Comentários

O esquema de codificação de aspas imprimíveis é descrito em RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncode

Chame essa função para codificar alguns dados no formato entre aspas imprimível.

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

Parâmetros

pbSrcData
O buffer que contém os dados a serem codificados.

nSrcLen
O tamanho em bytes dos dados a serem codificados.

szDest
O buffer alocado por chamador para receber os dados decodificados.

pnDestLen
O ponteiro para uma variável que contém o comprimento em caracteres de szDest. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

dwFlags
Os sinalizadores ATLSMTP_QPENCODE que descrevem como a conversão deve ser executada.

• ATLSMTP_QPENCODE_DOT Se um ponto aparecer no início de uma linha, ele será adicionado à saída, bem como codificado.

• ATLSMTP_QPENCODE_TRAILING_SOFT Acrescenta =\r\n à cadeia de caracteres codificada.

O esquema de codificação de aspas imprimíveis é descrito em RFC 2045.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O esquema de codificação de aspas imprimíveis é descrito em RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

QPEncodeGetRequiredLength

Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

inline int QPEncodeGetRequiredLength(int nSrcLen) throw ();

Parâmetros

nSrcLen
O número de bytes de dados a serem codificados.

Valor de retorno

O número de caracteres necessários para um buffer que poderia conter dados codificados de bytes nSrcLen.

Comentários

O esquema de codificação de aspas imprimíveis é descrito em RFC 2045 (https://www.ietf.org/rfc/rfc2045.txt).

UUDecode

Decodifica uma cadeia de caracteres de dados que foi codificada em UU, como por uma chamada anterior a UUEncode.

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

Parâmetros

pbSrcData
A cadeia de caracteres que contém os dados a serem decodificados.

nSrcLen
O tamanho em bytes de pbSrcData.

pbDest
Buffer alocado por chamador para receber os dados decodificados.

pnDestLen
Ponteiro para uma variável que contém o tamanho em bytes de pbDest. Se a função for bem-sucedida, a variável receberá o número de bytes gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa implementação com codificação UU segue a especificação POSIX P1003.2b/D11.

UUDecodeGetRequiredLength

Chame essa função para obter o tamanho em bytes de um buffer que pode conter os dados decodificados de uma cadeia de caracteres com codificação UU do comprimento especificado.

inline int UUDecodeGetRequiredLength(int nSrcLen) throw ();

Parâmetros

nSrcLen
O número de caracteres na cadeia de caracteres codificada.

Valor de retorno

O número de bytes necessários para um buffer que poderia conter uma cadeia de caracteres decodificada de caracteres nSrcLen.

Comentários

Essa implementação com codificação UU segue a especificação POSIX P1003.2b/D11.

UUEncode

Chame essa função para codificar alguns dados em UU.

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

Parâmetros

pbSrcData
O buffer que contém os dados a serem codificados.

nSrcLen
O tamanho em bytes dos dados a serem codificados.

szDest
O buffer alocado por chamador para receber os dados decodificados.

pnDestLen
O ponteiro para uma variável que contém o comprimento em caracteres de szDest. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer. Se a função falhar, a variável receberá o tamanho necessário em bytes do buffer.

lpszFile
O arquivo a ser adicionado ao cabeçalho quando ATLSMTP_UUENCODE_HEADER é especificado em dwFlags.

dwFlags
Os sinalizadores que controlam o comportamento dessa função.

• ATLSMTP_UUENCODE_HEADE O cabeçalho será codificado.

• ATLSMTP_UUENCODE_END O fim será codificado.

• ATLSMTP_UUENCODE_DOT O preenchimento de dados será executado.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa implementação com codificação UU segue a especificação POSIX P1003.2b/D11.

UUEncodeGetRequiredLength

Chame essa função para obter o tamanho em caracteres de um buffer que pode conter de uma cadeia de caracteres codificada dos dados do tamanho especificado.

inline int UUEncodeGetRequiredLength(int nSrcLen) throw ();

Parâmetros

nSrcLen
O número de bytes de dados a serem codificados.

Valor de retorno

O número de caracteres necessários para um buffer que poderia conter dados codificados de bytes nSrcLen.

Comentários

Essa implementação com codificação UU segue a especificação POSIX P1003.2b/D11.

Confira também

Conceitos
Componentes de área de trabalho COM da ATL