/thirdparty/breakpad/client/windows/crash_generation/crash_generation_client.h

  1// Copyright (c) 2008, Google Inc.
  2// All rights reserved.
  3//
  4// Redistribution and use in source and binary forms, with or without
  5// modification, are permitted provided that the following conditions are
  6// met:
  7//
  8//     * Redistributions of source code must retain the above copyright
  9// notice, this list of conditions and the following disclaimer.
 10//     * Redistributions in binary form must reproduce the above
 11// copyright notice, this list of conditions and the following disclaimer
 12// in the documentation and/or other materials provided with the
 13// distribution.
 14//     * Neither the name of Google Inc. nor the names of its
 15// contributors may be used to endorse or promote products derived from
 16// this software without specific prior written permission.
 17//
 18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 29
 30#ifndef CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_CLIENT_H_
 31#define CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_CLIENT_H_
 32
 33#include <windows.h>
 34#include <dbghelp.h>
 35#include <string>
 36#include <utility>
 37#include "client/windows/common/ipc_protocol.h"
 38#include "processor/scoped_ptr.h"
 39
 40namespace google_breakpad {
 41
 42struct CustomClientInfo;
 43
 44// Abstraction of client-side implementation of out of process
 45// crash generation.
 46//
 47// The process that desires to have out-of-process crash dump
 48// generation service can use this class in the following way:
 49//
 50// * Create an instance.
 51// * Call Register method so that the client tries to register
 52//   with the server process and check the return value. If
 53//   registration is not successful, out-of-process crash dump
 54//   generation will not be available
 55// * Request dump generation by calling either of the two
 56//   overloaded RequestDump methods - one in case of exceptions
 57//   and the other in case of assertion failures
 58//
 59// Note that it is the responsibility of the client code of
 60// this class to set the unhandled exception filter with the
 61// system by calling the SetUnhandledExceptionFilter function
 62// and the client code should explicitly request dump generation.
 63class CrashGenerationClient {
 64 public:
 65  CrashGenerationClient(const wchar_t* pipe_name,
 66                        MINIDUMP_TYPE dump_type,
 67                        const CustomClientInfo* custom_info);
 68
 69  ~CrashGenerationClient();
 70
 71  // Registers the client process with the crash server.
 72  //
 73  // Returns true if the registration is successful; false otherwise.
 74  bool Register();
 75
 76  // Requests the crash server to upload a previous dump with the
 77  // given crash id.
 78  bool RequestUpload(DWORD crash_id);
 79
 80  bool RequestDump(EXCEPTION_POINTERS* ex_info,
 81                   MDRawAssertionInfo* assert_info);
 82
 83  // Requests the crash server to generate a dump with the given
 84  // exception information.
 85  //
 86  // Returns true if the dump was successful; false otherwise. Note that
 87  // if the registration step was not performed or it was not successful,
 88  // false will be returned.
 89  bool RequestDump(EXCEPTION_POINTERS* ex_info);
 90
 91  // Requests the crash server to generate a dump with the given
 92  // assertion information.
 93  //
 94  // Returns true if the dump was successful; false otherwise. Note that
 95  // if the registration step was not performed or it was not successful,
 96  // false will be returned.
 97  bool RequestDump(MDRawAssertionInfo* assert_info);
 98
 99 private:
100  // Connects to the appropriate pipe and sets the pipe handle state.
101  //
102  // Returns the pipe handle if everything goes well; otherwise Returns NULL.
103  HANDLE ConnectToServer();
104
105  // Performs a handshake with the server over the given pipe which should be
106  // already connected to the server.
107  //
108  // Returns true if handshake with the server was successful; false otherwise.
109  bool RegisterClient(HANDLE pipe);
110
111  // Validates the given server response.
112  bool ValidateResponse(const ProtocolMessage& msg) const;
113
114  // Returns true if the registration step succeeded; false otherwise.
115  bool IsRegistered() const;
116
117  // Connects to the given named pipe with given parameters.
118  //
119  // Returns true if the connection is successful; false otherwise.
120  HANDLE ConnectToPipe(const wchar_t* pipe_name,
121                       DWORD pipe_access,
122                       DWORD flags_attrs);
123
124  // Signals the crash event and wait for the server to generate crash.
125  bool SignalCrashEventAndWait();
126
127  // Pipe name to use to talk to server.
128  std::wstring pipe_name_;
129
130  // Custom client information
131  CustomClientInfo custom_info_;
132
133  // Type of dump to generate.
134  MINIDUMP_TYPE dump_type_;
135
136  // Event to signal in case of a crash.
137  HANDLE crash_event_;
138
139  // Handle to wait on after signaling a crash for the server
140  // to finish generating crash dump.
141  HANDLE crash_generated_;
142
143  // Handle to a mutex that will become signaled with WAIT_ABANDONED
144  // if the server process goes down.
145  HANDLE server_alive_;
146
147  // Server process id.
148  DWORD server_process_id_;
149
150  // Id of the thread that caused the crash.
151  DWORD thread_id_;
152
153  // Exception pointers for an exception crash.
154  EXCEPTION_POINTERS* exception_pointers_;
155
156  // Assertion info for an invalid parameter or pure call crash.
157  MDRawAssertionInfo assert_info_;
158
159  // Disable copy ctor and operator=.
160  CrashGenerationClient(const CrashGenerationClient& crash_client);
161  CrashGenerationClient& operator=(const CrashGenerationClient& crash_client);
162};
163
164}  // namespace google_breakpad
165
166#endif  // CLIENT_WINDOWS_CRASH_GENERATION_CRASH_GENERATION_CLIENT_H_