Função LoadStringW (winuser.h)

Artigo
11/20/2024

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 encerramento 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 a receber a cadeia de caracteres (se cchBufferMax não for zero) ou um ponteiro somente leitura para o próprio recurso de cadeia de caracteres (se cchBufferMax for zero). Deve ter comprimento suficiente para segurar 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, lpBuffer receberá um ponteiro somente leitura para o próprio recurso de cadeia de caracteres.

Valor de retorno

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 não for zero), não incluindo o caractere nulo de terminação.
O número de caracteres no recurso de cadeia de caracteres que lpBuffer aponta para (se cchBufferMax for zero). O recurso de cadeia de caracteres não tem garantia de ser 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.

Observações

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 incorreto no parâmetro nBufferMax do . Por exemplo, se lpBuffer aponta para um buffer szBuffer que é declarado como TCHAR szBuffer[100], então sizeof(szBuffer) fornece 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

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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

Consulte também

Conceitual

formatMessage

LoadAccelerators

loadBitmap

LoadCursor

loadicon

LoadMenu

LoadMenuIndirect

outros recursos

de referência de

cadeias de caracteres

Compartilhar via