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

  • Artigo

O SDK do Windows fornece protótipos de função em versões genéricas, de código do Windows e unicode . Os protótipos podem ser compilados para produzir protótipos de página de código do 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 do 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. Em seguida, o arquivo de cabeçalho fornece dois protótipos específicos, um para páginas de código do Windows 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 Tipos de Dados do Windows para Cadeias de Caracteres, o protótipo de função genérica usa o tipo de dados LPCTSTR para o parâmetro text. 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 do Windows devem usar Unicode para evitar inconsistências de páginas de código variadas e para facilitar a localização. Eles devem ser escritos 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 caracteres de 8 bits, ele pode fazer uso explícito das funções para páginas de código do Windows.

 

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 por sistemas operacionais com suporte. Se uma linha que começa com "Unicode" for incluída, a função terá versões separadas de 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 versões de página de código do Windows da função ou palavras de 16 bits para versões Unicode. No entanto, as funções que exigem ou retornam ponteiros para blocos de memória não tipado, 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 sizeof (TCHAR). Para obter informações adicionais, consulte Usando tipos de dados genéricos.

 

Unicode na API do Windows