Convenções para protótipos de função

O SDK Windows fornece protótipos de função em versões genéricas, Windows código e Unicode. Os protótipos podem ser compilados para produzir protótipos de página de código Windows ou protótipos Unicode. Todos os três protótipos são discutidos neste tópico e são ilustrados por exemplos de código para a função SetWindowText .

A seguir está um exemplo de um protótipo genérico.

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

O arquivo de cabeçalho fornece o nome genérico da função implementada como uma macro.

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

O pré-processador expande a macro para a página de código Windows ou o nome da função Unicode. A letra "A" (ANSI) ou "W" (Unicode) é adicionada no final do nome da função genérica, conforme apropriado. O arquivo de cabeçalho fornece dois protótipos específicos, um para Windows páginas de código e outro para Unicode, conforme mostrado nos exemplos a seguir.

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);
BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

Conforme explicado em Windows Tipos de Dados para Cadeias de Caracteres, o protótipo de função genérica usa o tipo de dados LPCTSTR para o parâmetro de texto. No entanto, o protótipo de página do código do Windows usa o tipo LPCSTR e o protótipo Unicode usa LPCWSTR.

Para todas as funções com argumentos de texto, os aplicativos devem normalmente usar os protótipos genéricos de função. Se um aplicativo definir "UNICODE" antes das instruções #include para os arquivos de cabeçalho ou durante a compilação, as instruções serão compiladas em funções Unicode.

Observação

Novos aplicativos Windows devem usar o Unicode para evitar inconsistências de páginas de código variadas e para facilitar a localização. Elas devem ser gravadas com funções genéricas e devem definir UNICODE para compilar as funções em funções Unicode. Nos poucos locais em que um aplicativo deve trabalhar com dados de caractere de 8 bits, ele pode fazer uso explícito das funções para Windows páginas de código.

 

Seu aplicativo sempre deve usar um protótipo genérico da função com a cadeia de caracteres e os tipos de caracteres genéricos. Todos os nomes de função que terminam com “W” maiúscula usam Unicode, ou seja, caracteres e parâmetros largos. Algumas funções existem apenas em versões Unicode e só podem ser usadas com os tipos de dados apropriados. Por exemplo, LCIDToLocaleName e LocaleNameToLCID têm apenas versões Unicode.

A seção Requisitos na documentação de referência para cada função Unicode e conjunto de caracteres fornece informações sobre as versões de função implementadas pelos sistemas operacionais com suporte. Se uma linha que começa com "Unicode" for incluída, a função terá versões separadas da página de código Unicode e Windows.

Observação

Quando uma função tem um parâmetro de comprimento para uma cadeia de caracteres, o comprimento deve ser documentado como uma contagem de valores TCHAR na cadeia de caracteres. Esse tipo de dados refere-se a bytes para Windows versões de página de código da função ou palavras de 16 bits para versões Unicode. No entanto, funções que exigem ou retornam ponteiros para blocos de memória não tipados, como a função GlobalAlloc , geralmente assumem um tamanho em bytes, independentemente do protótipo usado. Se a alocação de memória não tipada for para uma cadeia de caracteres, o aplicativo deverá multiplicar o número de caracteres por tamanho(TCHAR). Para obter informações adicionais, consulte Usando tipos de dados genéricos.

 

Unicode na API do Windows