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