Função GetModuleHandleExW (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 GetModuleHandleExW(
[in] DWORD dwFlags,
[in, optional] LPCWSTR 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 seja 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
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 mapeados no momento 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 carregados usando o sinalizador LOAD_LIBRARY_AS_DATAFILE. Para obter mais informações, consulte LoadLibraryEx.
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, consulte GetLastError.
Observações
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 ladoou 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. Fazer isso pode fazer com que um módulo DLL seja não mapeado prematuramente.
Se dwFlags contiver GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, essa função deverá ser usada com cuidado 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 ela é 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 do 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.
Nota
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 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 XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | libloaderapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
Funções da biblioteca Dynamic-Link