Função GetModuleBaseNameA (psapi.h)

Artigo
11/20/2024

Recupera o nome base do módulo especificado.

Sintaxe

DWORD GetModuleBaseNameA(
  [in]           HANDLE  hProcess,
  [in, optional] HMODULE hModule,
  [out]          LPSTR   lpBaseName,
  [in]           DWORD   nSize
);

Parâmetros

[in] hProcess

Um identificador para o processo que contém o módulo.

O identificador deve ter os direitos de acesso PROCESS_QUERY_INFORMATION e PROCESS_VM_READ. Para obter mais informações, consulte Process Security and Access Rights.

[in, optional] hModule

Um identificador para o módulo. Se esse parâmetro for NULL, essa função retornará o nome do arquivo usado para criar o processo de chamada.

[out] lpBaseName

Um ponteiro para o buffer que recebe o nome base do módulo. Se o nome base for maior que o número máximo de caracteres especificado pelo parâmetro nSize, o nome base será truncado.

[in] nSize

O tamanho do buffer lpBaseName , em caracteres.

Valor de retorno

Se a função for bem-sucedida, o valor retornado especifica o comprimento da cadeia de caracteres copiada para o buffer, em caracteres.

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

Observações

A função GetModuleBaseName foi projetada principalmente para uso por depuradores e aplicativos semelhantes que devem extrair informações do módulo de outro processo. Se a lista de módulos no processo de destino estiver corrompida ou ainda não estiver inicializada ou se a lista de módulos for alterada durante a chamada de função como resultado de DLLs sendo carregadas ou descarregadas, GetModuleBaseName poderá falhar ou retornar informações incorretas.

Para recuperar o nome base de um módulo no processo atual, use a função GetModuleFileName para recuperar o nome completo do módulo e, em seguida, usar uma chamada de função, como strrchr(szmodulename, '\'), para verificar até o início do nome base dentro da cadeia de caracteres de nome do módulo. Isso é mais eficiente e mais confiável do que chamar GetModuleBaseName com um identificador para o processo atual.

Para recuperar o nome base do módulo executável principal para um processo remoto, use a função GetProcessImageFileName ou queryFullProcessImageName para recuperar o nome do módulo e, em seguida, use a função conforme descrito no parágrafo anterior. Isso é mais eficiente e mais confiável do que chamar GetModuleBaseName com um identificador de módulo NULL.

A função GetModuleBaseName não recupera o nome base dos módulos que foram carregados com o sinalizador LOAD_LIBRARY_AS_DATAFILE. Para obter mais informações, consulte LoadLibraryEx.

Começando com o Windows 7 e o Windows Server 2008 R2, o Psapi.h estabelece números de versão para as funções PSAPI. O número de versão do PSAPI afeta o nome usado para chamar a função e a biblioteca que um programa deve carregar.

Se PSAPI_VERSION for 2 ou maior, essa função será definida como K32GetModuleBaseName no Psapi.h e exportada em Kernel32.lib e Kernel32.dll. Se PSAPI_VERSION for 1, essa função será definida como GetModuleBaseName no Psapi.h e exportada em Psapi.lib e Psapi.dll como um wrapper que chama K32GetModuleBaseName.

Programas que devem ser executados em versões anteriores do Windows, bem como no Windows 7 e versões posteriores, sempre devem chamar essa função como GetModuleBaseName. Para garantir a resolução correta de símbolos, adicione Psapi.lib à macro TARGETLIBS e compile o programa com -DPSAPI_VERSION=1. Para usar a vinculação dinâmica em tempo de execução, carregue Psapi.dll.

Exemplos

Para obter um exemplo, consulte Enumerando Todos os Processos.

Nota

O cabeçalho psapi.h define GetModuleBaseName 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. 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 [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	psapi.h
biblioteca	Kernel32.lib no Windows 7 e Windows Server 2008 R2; Psapi.lib (se PSAPI_VERSION=1) no Windows 7 e Windows Server 2008 R2; Psapi.lib no Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP
de DLL	Kernel32.dll no Windows 7 e no Windows Server 2008 R2; Psapi.dll (se PSAPI_VERSION=1) no Windows 7 e no Windows Server 2008 R2; Psapi.dll no Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP

Consulte também

EnumProcesses

GetModuleFileNameEx

de informações do módulo

Funções PSAPI

strrchr, wcsrchr, _mbsrchr, _mbsrchr_l

Compartilhar via