Função GetModuleHandleExA (libloaderapi.h)

Artigo
08/24/2023

Recupera um identificador de módulo para o módulo especificado e incrementa a contagem de referência do módulo, a menos que GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT seja especificado. O módulo deve ter sido carregado pelo processo de chamada.

Sintaxe

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  lpModuleName,
  [out]          HMODULE *phModule
);

Parâmetros

[in] dwFlags

Esse parâmetro pode ser zero ou um ou mais dos valores a seguir. Se a contagem de referência do módulo for incrementada, o chamador deverá usar a função FreeLibrary para diminuir a contagem de referência quando o identificador do módulo não for mais necessário.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

O parâmetro lpModuleName é um endereço no módulo.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

O módulo permanece carregado até que o processo seja encerrado, independentemente de quantas vezes FreeLibrary for chamado.

Essa opção não pode ser usada com GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

A contagem de referência para o módulo não é incrementada. Essa opção é equivalente ao comportamento de GetModuleHandle. Não passe o identificador de módulo recuperado para a função FreeLibrary ; Fazer isso pode fazer com que a DLL seja não mapeada prematuramente. Para obter mais informações, consulte Comentários.

Essa opção não pode ser usada com GET_MODULE_HANDLE_EX_FLAG_PIN.

[in, optional] lpModuleName

O nome do módulo carregado (um arquivo .dll ou .exe) ou um endereço no módulo (se dwFlags for GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

Para um nome de módulo, 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 independentemente) 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, a função retornará um identificador para o arquivo usado para criar o processo de chamada (.exe arquivo).

[out] phModule

Um identificador para o módulo especificado. Se a função falhar, esse parâmetro será NULL.

A função GetModuleHandleEx 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á diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, consulte 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 especificar um local de memória em vez de um nome DLL no parâmetro lpModuleName .

Se dwFlags contiver GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, a função GetModuleHandleEx retornará 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 GetModuleHandleEx com GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT para a função FreeLibrary . Isso pode fazer com que um módulo de DLL seja não mapeado prematuramente.

Se dwFlags contiver GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, essa função deverá 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 momento em que essa função retorna o identificador e a hora em que é usada. Por exemplo, um thread recupera 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 de módulo que foi liberado recentemente. Portanto, o primeiro thread teria um identificador para um módulo diferente do pretendido.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0501 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Observação

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