Função MiniDumpWriteDump (minidumpapiset.h)

Artigo
03/05/2024

Grava informações de minidespejo no modo de usuário no arquivo especificado.

Sintaxe

BOOL MiniDumpWriteDump(
  [in] HANDLE                            hProcess,
  [in] DWORD                             ProcessId,
  [in] HANDLE                            hFile,
  [in] MINIDUMP_TYPE                     DumpType,
  [in] PMINIDUMP_EXCEPTION_INFORMATION   ExceptionParam,
  [in] PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,
  [in] PMINIDUMP_CALLBACK_INFORMATION    CallbackParam
);

Parâmetros

[in] hProcess

Um identificador para o processo para o qual as informações devem ser geradas.

Esse identificador deve ter acesso PROCESS_QUERY_INFORMATION e PROCESS_VM_READ ao processo. Se as informações do identificador devem ser coletadas , PROCESS_DUP_HANDLE acesso também será necessário. Para obter mais informações, consulte Direitos de acesso e segurança do processo. O chamador também deve ser capaz de obter acesso THREAD_ALL_ACCESS aos threads no processo. Para obter mais informações, consulte Segurança de thread e direitos de acesso.

[in] ProcessId

O identificador do processo para o qual as informações devem ser geradas.

[in] hFile

Um identificador para o arquivo no qual as informações devem ser gravadas.

[in] DumpType

O tipo de informação a ser gerada. Esse parâmetro pode ser um ou mais dos valores da enumeração MINIDUMP_TYPE .

[in] ExceptionParam

Um ponteiro para uma estrutura de MINIDUMP_EXCEPTION_INFORMATION que descreve a exceção do cliente que fez com que o minidump fosse gerado. Se o valor desse parâmetro for NULL, nenhuma informação de exceção será incluída no arquivo de minidespejo.

[in] UserStreamParam

Um ponteiro para uma estrutura MINIDUMP_USER_STREAM_INFORMATION . Se o valor desse parâmetro for NULL, nenhuma informação definida pelo usuário será incluída no arquivo de minidespejo.

[in] CallbackParam

Um ponteiro para uma estrutura MINIDUMP_CALLBACK_INFORMATION que especifica uma rotina de retorno de chamada que deve receber informações estendidas de minidespejo. Se o valor desse parâmetro for NULL, nenhum retorno de chamada será executado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE; caso contrário, o valor retornado será FALSE. Para recuperar informações de erro estendidas, chame GetLastError. Observe que o último erro será um valor HRESULT .

Se a operação for cancelada, o último código de erro será HRESULT_FROM_WIN32(ERROR_CANCELLED).

Comentários

A função MiniDumpCallback recebe informações estendidas de minidespejo de MiniDumpWriteDump. Ele também fornece uma maneira de o chamador determinar a granularidade das informações gravadas no arquivo de minidespejo, pois a função de retorno de chamada pode filtrar as informações padrão.

MiniDumpWriteDump deve ser chamado de um processo separado, se possível, em vez de dentro do processo de destino que está sendo despejado. Isso é especialmente verdadeiro quando o processo de destino já não está estável. Por exemplo, se ele acabou de falhar. Um deadlock do carregador é um dos muitos efeitos colaterais potenciais de chamar MiniDumpWriteDump de dentro do processo de destino. Se não for possível chamar MiniDumpWriteDump de um processo separado, é aconselhável ter um thread dedicado cuja única finalidade é chamar MiniDumpWriteDump. Isso pode ajudar a garantir que a pilha ainda não esteja esgotada antes da chamada para MiniDumpWriteDump.

MiniDumpWriteDump pode não produzir um rastreamento de pilha válido para o thread de chamada. Para contornar esse problema, você deve capturar o estado do thread de chamada antes de chamar MiniDumpWriteDump e usá-lo como o parâmetro ExceptionParam . Uma maneira de fazer isso é forçar uma exceção dentro de um bloco __try/__except e usar as informações de EXCEPTION_POINTERS fornecidas por GetExceptionInformation. Como alternativa, você pode chamar a função de um novo thread de trabalho e filtrar esse thread de trabalho do despejo.

Todas as funções DbgHelp, como esta, são threaded único. Portanto, chamadas de mais de um thread para essa função provavelmente resultarão em comportamento inesperado ou corrupção de memória. Para evitar isso, você deve sincronizar todas as chamadas simultâneas de mais de um thread para essa função.

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	minidumpapiset.h (inclua Dbghelp.h)
Biblioteca	Dbghelp.lib
DLL	Dbghelp.dll; Dbgcore.dll
Redistribuível	DbgHelp.dll e Dbgcore.dll