Função GetModuleHandleExA (libloaderapi.h)
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 |