Função LoadStringA (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 LoadStringA(
  [in, optional] HINSTANCE hInstance,
  [in]           UINT      uID,
  [out]          LPSTR     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. Deve ter pelo menos cchBufferMax caracteres de tamanho.

[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. Esse parâmetro pode não ser zero.

Valor de retorno

Tipo: int

Se a função for bem-sucedida, o valor retornado será o número de caracteres copiados para o buffer, não incluindo o caractere nulo de encerramento.

Se o recurso de cadeia de caracteres não existir, o valor retornado será zero.

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

Observações

Ao contrário da função LoadStringW, a função LoadStringA não dá suporte à passagem de um valor zero para cchBufferMax. Fazer isso corromperá a memória.

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 cchBufferMax. 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