Compartilhar via


Função GetModuleHandleA (libloaderapi.h)

Recupera um identificador de módulo para o módulo especificado. O módulo deve ter sido carregado pelo processo de chamada.

Para evitar as condições de corrida descritas na seção Comentários, use a função GetModuleHandleEx .

Sintaxe

HMODULE GetModuleHandleA(
  [in, optional] LPCSTR lpModuleName
);

Parâmetros

[in, optional] lpModuleName

O nome do módulo carregado (um arquivo de .dll ou .exe). Se a extensão de nome de arquivo for omitida, a extensão de biblioteca padrão .dll será acrescentada. A cadeia de caracteres de nome de arquivo pode incluir um caractere de ponto à direita (.) para indicar que o nome do módulo não tem extensão. A cadeia de caracteres não precisa especificar um caminho. Ao especificar um caminho, use barras invertidas (\), não barras (/). O nome é comparado (caso independente) com os nomes dos módulos atualmente mapeados para o espaço de endereço do processo de chamada.

Se esse parâmetro for NULL, GetModuleHandle retornará um identificador para o arquivo usado para criar o processo de chamada (.exe arquivo).

A função GetModuleHandle não recupera identificadores para módulos que foram carregados usando o sinalizador LOAD_LIBRARY_AS_DATAFILE . Para obter mais informações, consulte LoadLibraryEx.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador para o módulo especificado.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O identificador retornado não é global ou herdável. Ele não pode ser duplicado ou usado por outro processo.

Se lpModuleName não incluir um caminho e houver mais de um módulo carregado com o mesmo nome base e extensão, você não poderá prever qual identificador de módulo será retornado. Para contornar esse problema, você pode especificar um caminho, usar assemblies lado a lado ou usar GetModuleHandleEx para especificar um local de memória em vez de um nome de DLL.

A função GetModuleHandle retorna um identificador para um módulo mapeado sem incrementar sua contagem de referência. No entanto, se esse identificador for passado para a função FreeLibrary , a contagem de referência do módulo mapeado será decrementada. Portanto, não passe um identificador retornado por GetModuleHandle para a função FreeLibrary . Isso pode fazer com que um módulo de DLL seja não mapeado prematuramente.

Essa função deve ser usada cuidadosamente em um aplicativo multithread. Não há nenhuma garantia de que o identificador do módulo permaneça válido entre o tempo em que essa função retorna o identificador e o tempo em que é usada. Por exemplo, suponha que um thread recupere um identificador de módulo, mas antes de usar o identificador, um segundo thread libera o módulo. Se o sistema carregar outro módulo, ele poderá reutilizar o identificador do módulo que foi liberado recentemente. Portanto, o primeiro thread teria um identificador para um módulo diferente do pretendido.

Exemplos

Para obter um exemplo, consulte Usando pincéis.

Observação

O cabeçalho libloaderapi.h define GetModuleHandle 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

   
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho libloaderapi.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Funções de biblioteca de link dinâmico

FreeLibrary

GetModuleFileName

GetModuleHandleEx

LoadLibrary

LoadLibraryEx