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 |