Função LoadStringW (winuser.h)

Artigo
08/27/2023

Carrega um recurso de cadeia de caracteres do arquivo executável associado a um módulo especificado e copia a cadeia de caracteres em um buffer com um caractere nulo de terminação ou retorna um ponteiro somente leitura para o próprio recurso de cadeia de caracteres.

Sintaxe

int LoadStringW(
  [in, optional] HINSTANCE hInstance,
  [in]           UINT      uID,
  [out]          LPWSTR    lpBuffer,
  [in]           int       cchBufferMax
);

Parâmetros

[in, optional] hInstance

Tipo: HINSTANCE

Um identificador para uma instância do módulo cujo arquivo executável contém o recurso de cadeia de caracteres. Para obter o identificador para o próprio aplicativo, chame a função GetModuleHandle com NULL.

[in] uID

Tipo: UINT

O identificador da cadeia de caracteres a ser carregada.

[out] lpBuffer

Tipo: LPTSTR

O buffer para receber a cadeia de caracteres (se cchBufferMax for diferente de zero) ou um ponteiro somente leitura para o próprio recurso de cadeia de caracteres (se cchBufferMax for zero). Deve ter comprimento suficiente para manter um ponteiro (8 bytes).

[in] cchBufferMax

Tipo: int

O tamanho do buffer, em caracteres. A cadeia de caracteres será truncada e terminada em nulo se for maior que o número de caracteres especificado. Se esse parâmetro for 0, o lpBuffer receberá um ponteiro somente leitura para o próprio recurso de cadeia de caracteres.

Retornar valor

Tipo: int

Se a função for bem-sucedida, o valor retornado será um dos seguintes:

O número de caracteres copiados para o buffer (se cchBufferMax for diferente de zero), não incluindo o caractere nulo de terminação.
O número de caracteres no recurso de cadeia de caracteres para o qual lpBuffer aponta (se cchBufferMax for zero). Não há garantia de que o recurso de cadeia de caracteres seja encerrado em nulo na tabela de recursos do módulo e você pode usar esse valor para determinar onde o recurso de cadeia de caracteres termina.
Zero se o recurso de cadeia de caracteres não existir.

Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se você passar 0 para cchBufferMax para retornar um ponteiro somente leitura para o recurso de cadeia de caracteres no parâmetro lpBuffer , use o número de caracteres no valor retornado para determinar o comprimento do recurso de cadeia de caracteres. Não há garantia de que os recursos de cadeia de caracteres sejam encerrados em nulo na tabela de recursos do módulo. No entanto, as tabelas de recursos podem conter caracteres nulos. Os recursos de cadeia de caracteres são armazenados em blocos de 16 cadeias de caracteres e todos os slots vazios em um bloco são indicados por caracteres nulos.

Comentários de segurança

Usar essa função incorretamente pode comprometer a segurança do aplicativo. O uso incorreto inclui especificar o tamanho errado no parâmetro nBufferMax . Por exemplo, se lpBuffer apontar para um buffer szBuffer que é declarado como TCHAR szBuffer[100], sizeof(szBuffer) fornecerá o tamanho do buffer em bytes, o que pode levar a um estouro de buffer para a versão Unicode da função. Situações de estouro de buffer são a causa de muitos problemas de segurança em aplicativos. Nesse caso, usar sizeof(szBuffer)/sizeof(TCHAR) ou sizeof(szBuffer)/sizeof(szBuffer[0]) daria o tamanho adequado do buffer.

Exemplos

Para obter um exemplo, consulte Criando uma janela filho

Observação

O cabeçalho winuser.h define LoadString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll