The Tor Browser / file revision

 // Copyright (c) 2006, Google Inc.

 // All rights reserved.

 //

 // Redistribution and use in source and binary forms, with or without

 // modification, are permitted provided that the following conditions are

 // met:

 //

 //     * Redistributions of source code must retain the above copyright

 // notice, this list of conditions and the following disclaimer.

 //     * Redistributions in binary form must reproduce the above

 // copyright notice, this list of conditions and the following disclaimer

 // in the documentation and/or other materials provided with the

 // distribution.

 //     * Neither the name of Google Inc. nor the names of its

 // contributors may be used to endorse or promote products derived from

 // this software without specific prior written permission.

 //

 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 // ExceptionHandler can write a minidump file when an exception occurs,

 // or when WriteMinidump() is called explicitly by your program.

 //

 // To have the exception handler write minidumps when an uncaught exception

 // (crash) occurs, you should create an instance early in the execution

 // of your program, and keep it around for the entire time you want to

 // have crash handling active (typically, until shutdown).

 //

 // If you want to write minidumps without installing the exception handler,

 // you can create an ExceptionHandler with install_handler set to false,

 // then call WriteMinidump.  You can also use this technique if you want to

 // use different minidump callbacks for different call sites.

 //

 // In either case, a callback function is called when a minidump is written,

 // which receives the unqiue id of the minidump.  The caller can use this

 // id to collect and write additional application state, and to launch an

 // external crash-reporting application.

 //

 // It is important that creation and destruction of ExceptionHandler objects

 // be nested cleanly, when using install_handler = true.

 // Avoid the following pattern:

 //   ExceptionHandler *e = new ExceptionHandler(...);

 //   ExceptionHandler *f = new ExceptionHandler(...);

 //   delete e;

 // This will put the exception filter stack into an inconsistent state.

 #ifndef CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__

 #define CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__

 #include <stdlib.h>

 #include <Windows.h>

 #include <DbgHelp.h>

 #include <rpc.h>

 #pragma warning( push )

 // Disable exception handler warnings.

 #pragma warning( disable : 4530 )

 #include <list>

 #include <string>

 #include <vector>

 #include "client/windows/common/ipc_protocol.h"

 #include "client/windows/crash_generation/crash_generation_client.h"

 #include "common/scoped_ptr.h"

 #include "google_breakpad/common/minidump_format.h"

 namespace google_breakpad {

 using std::vector;

 using std::wstring;

 // These entries store a list of memory regions that the client wants included

 // in the minidump.

 struct AppMemory {

   ULONG64 ptr;

   ULONG length;

   bool operator==(const struct AppMemory& other) const {

     return ptr == other.ptr;

   }

   bool operator==(const void* other) const {

     return ptr == reinterpret_cast<ULONG64>(other);

   }

 };

 typedef std::list<AppMemory> AppMemoryList;

 class ExceptionHandler {

  public:

   // A callback function to run before Breakpad performs any substantial

   // processing of an exception.  A FilterCallback is called before writing

   // a minidump.  context is the parameter supplied by the user as

   // callback_context when the handler was created.  exinfo points to the

   // exception record, if any; assertion points to assertion information,

   // if any.

   //

   // If a FilterCallback returns true, Breakpad will continue processing,

   // attempting to write a minidump.  If a FilterCallback returns false,

   // Breakpad will immediately report the exception as unhandled without

   // writing a minidump, allowing another handler the opportunity to handle it.

   typedef bool (*FilterCallback)(void* context, EXCEPTION_POINTERS* exinfo,

                                  MDRawAssertionInfo* assertion);

   // A callback function to run after the minidump has been written.

   // minidump_id is a unique id for the dump, so the minidump

   // file is <dump_path>\<minidump_id>.dmp.  context is the parameter supplied

   // by the user as callback_context when the handler was created.  exinfo

   // points to the exception record, or NULL if no exception occurred.

   // succeeded indicates whether a minidump file was successfully written.

   // assertion points to information about an assertion if the handler was

   // invoked by an assertion.

   //

   // If an exception occurred and the callback returns true, Breakpad will treat

   // the exception as fully-handled, suppressing any other handlers from being

   // notified of the exception.  If the callback returns false, Breakpad will

   // treat the exception as unhandled, and allow another handler to handle it.

   // If there are no other handlers, Breakpad will report the exception to the

   // system as unhandled, allowing a debugger or native crash dialog the

   // opportunity to handle the exception.  Most callback implementations

   // should normally return the value of |succeeded|, or when they wish to

   // not report an exception of handled, false.  Callbacks will rarely want to

   // return true directly (unless |succeeded| is true).

   //

   // For out-of-process dump generation, dump path and minidump ID will always

   // be NULL. In case of out-of-process dump generation, the dump path and

   // minidump id are controlled by the server process and are not communicated

   // back to the crashing process.

   typedef bool (*MinidumpCallback)(const wchar_t* dump_path,

                                    const wchar_t* minidump_id,

                                    void* context,

                                    EXCEPTION_POINTERS* exinfo,

                                    MDRawAssertionInfo* assertion,

                                    bool succeeded);

   // HandlerType specifies which types of handlers should be installed, if

   // any.  Use HANDLER_NONE for an ExceptionHandler that remains idle,

   // without catching any failures on its own.  This type of handler may

   // still be triggered by calling WriteMinidump.  Otherwise, use a

   // combination of the other HANDLER_ values, or HANDLER_ALL to install

   // all handlers.

   enum HandlerType {

     HANDLER_NONE = 0,

     HANDLER_EXCEPTION = 1 << 0,          // SetUnhandledExceptionFilter

     HANDLER_INVALID_PARAMETER = 1 << 1,  // _set_invalid_parameter_handler

     HANDLER_PURECALL = 1 << 2,           // _set_purecall_handler

     HANDLER_ALL = HANDLER_EXCEPTION |

                   HANDLER_INVALID_PARAMETER |

                   HANDLER_PURECALL

   };

   // Creates a new ExceptionHandler instance to handle writing minidumps.

   // Before writing a minidump, the optional filter callback will be called.

   // Its return value determines whether or not Breakpad should write a

   // minidump.  Minidump files will be written to dump_path, and the optional

   // callback is called after writing the dump file, as described above.

   // handler_types specifies the types of handlers that should be installed.

   ExceptionHandler(const wstring& dump_path,

                    FilterCallback filter,

                    MinidumpCallback callback,

                    void* callback_context,

                    int handler_types);

   // Creates a new ExceptionHandler instance that can attempt to perform

   // out-of-process dump generation if pipe_name is not NULL. If pipe_name is

   // NULL, or if out-of-process dump generation registration step fails,

   // in-process dump generation will be used. This also allows specifying

   // the dump type to generate.

   ExceptionHandler(const wstring& dump_path,

                    FilterCallback filter,

                    MinidumpCallback callback,

                    void* callback_context,

                    int handler_types,

                    MINIDUMP_TYPE dump_type,

                    const wchar_t* pipe_name,

                    const CustomClientInfo* custom_info);

   // As above, creates a new ExceptionHandler instance to perform

   // out-of-process dump generation if the given pipe_handle is not NULL.

   ExceptionHandler(const wstring& dump_path,

                    FilterCallback filter,

                    MinidumpCallback callback,

                    void* callback_context,

                    int handler_types,

                    MINIDUMP_TYPE dump_type,

                    HANDLE pipe_handle,

                    const CustomClientInfo* custom_info);

   ~ExceptionHandler();

   // Get and set the minidump path.

   wstring dump_path() const { return dump_path_; }

   void set_dump_path(const wstring &dump_path) {

     dump_path_ = dump_path;

     dump_path_c_ = dump_path_.c_str();

     UpdateNextID();  // Necessary to put dump_path_ in next_minidump_path_.

   }

   // Requests that a previously reported crash be uploaded.

   bool RequestUpload(DWORD crash_id);

   // Writes a minidump immediately.  This can be used to capture the

   // execution state independently of a crash.  Returns true on success.

   bool WriteMinidump();

   // Writes a minidump immediately, with the user-supplied exception

   // information.

   bool WriteMinidumpForException(EXCEPTION_POINTERS* exinfo);

   // Convenience form of WriteMinidump which does not require an

   // ExceptionHandler instance.

   static bool WriteMinidump(const wstring &dump_path,

                             MinidumpCallback callback, void* callback_context);

   // Write a minidump of |child| immediately.  This can be used to

   // capture the execution state of |child| independently of a crash.

   // Pass a meaningful |child_blamed_thread| to make that thread in

   // the child process the one from which a crash signature is

   // extracted.

   static bool WriteMinidumpForChild(HANDLE child,

                                     DWORD child_blamed_thread,

                                     const wstring& dump_path,

                                     MinidumpCallback callback,

                                     void* callback_context);

   // Get the thread ID of the thread requesting the dump (either the exception

   // thread or any other thread that called WriteMinidump directly).  This

   // may be useful if you want to include additional thread state in your

   // dumps.

   DWORD get_requesting_thread_id() const { return requesting_thread_id_; }

   // Controls behavior of EXCEPTION_BREAKPOINT and EXCEPTION_SINGLE_STEP.

   bool get_handle_debug_exceptions() const { return handle_debug_exceptions_; }

   void set_handle_debug_exceptions(bool handle_debug_exceptions) {

     handle_debug_exceptions_ = handle_debug_exceptions;

   }

   // Returns whether out-of-process dump generation is used or not.

   bool IsOutOfProcess() const { return crash_generation_client_.get() != NULL; }

   // Calling RegisterAppMemory(p, len) causes len bytes starting

   // at address p to be copied to the minidump when a crash happens.

   void RegisterAppMemory(void* ptr, size_t length);

   void UnregisterAppMemory(void* ptr);

  private:

   friend class AutoExceptionHandler;

   // Initializes the instance with given values.

   void Initialize(const wstring& dump_path,

                   FilterCallback filter,

                   MinidumpCallback callback,

                   void* callback_context,

                   int handler_types,

                   MINIDUMP_TYPE dump_type,

                   const wchar_t* pipe_name,

                   HANDLE pipe_handle,

                   const CustomClientInfo* custom_info);

   // Function pointer type for MiniDumpWriteDump, which is looked up

   // dynamically.

   typedef BOOL (WINAPI *MiniDumpWriteDump_type)(

       HANDLE hProcess,

       DWORD dwPid,

       HANDLE hFile,

       MINIDUMP_TYPE DumpType,

       CONST PMINIDUMP_EXCEPTION_INFORMATION ExceptionParam,

       CONST PMINIDUMP_USER_STREAM_INFORMATION UserStreamParam,

       CONST PMINIDUMP_CALLBACK_INFORMATION CallbackParam);

   // Function pointer type for UuidCreate, which is looked up dynamically.

   typedef RPC_STATUS (RPC_ENTRY *UuidCreate_type)(UUID* Uuid);

   // Runs the main loop for the exception handler thread.

   static DWORD WINAPI ExceptionHandlerThreadMain(void* lpParameter);

   // Called on the exception thread when an unhandled exception occurs.

   // Signals the exception handler thread to handle the exception.

   static LONG WINAPI HandleException(EXCEPTION_POINTERS* exinfo);

 #if _MSC_VER >= 1400  // MSVC 2005/8

   // This function will be called by some CRT functions when they detect

   // that they were passed an invalid parameter.  Note that in _DEBUG builds,

   // the CRT may display an assertion dialog before calling this function,

   // and the function will not be called unless the assertion dialog is

   // dismissed by clicking "Ignore."

   static void HandleInvalidParameter(const wchar_t* expression,

                                      const wchar_t* function,

                                      const wchar_t* file,

                                      unsigned int line,

                                      uintptr_t reserved);

 #endif  // _MSC_VER >= 1400

   // This function will be called by the CRT when a pure virtual

   // function is called.

   static void HandlePureVirtualCall();

   // This is called on the exception thread or on another thread that

   // the user wishes to produce a dump from.  It calls

   // WriteMinidumpWithException on the handler thread, avoiding stack

   // overflows and inconsistent dumps due to writing the dump from

   // the exception thread.  If the dump is requested as a result of an

   // exception, exinfo contains exception information, otherwise, it

   // is NULL.  If the dump is requested as a result of an assertion

   // (such as an invalid parameter being passed to a CRT function),

   // assertion contains data about the assertion, otherwise, it is NULL.

   bool WriteMinidumpOnHandlerThread(EXCEPTION_POINTERS* exinfo,

                                     MDRawAssertionInfo* assertion);

   // This function is called on the handler thread.  It calls into

   // WriteMinidumpWithExceptionForProcess() with a handle to the

   // current process.  requesting_thread_id is the ID of the thread

   // that requested the dump.  If the dump is requested as a result of

   // an exception, exinfo contains exception information, otherwise,

   // it is NULL.

   bool WriteMinidumpWithException(DWORD requesting_thread_id,

                                   EXCEPTION_POINTERS* exinfo,

                                   MDRawAssertionInfo* assertion);

   // This function is used as a callback when calling MinidumpWriteDump,

   // in order to add additional memory regions to the dump.

   static BOOL CALLBACK MinidumpWriteDumpCallback(

       PVOID context,

       const PMINIDUMP_CALLBACK_INPUT callback_input,

       PMINIDUMP_CALLBACK_OUTPUT callback_output);

   // This function does the actual writing of a minidump.  It is

   // called on the handler thread.  requesting_thread_id is the ID of

   // the thread that requested the dump, if that information is

   // meaningful.  If the dump is requested as a result of an

   // exception, exinfo contains exception information, otherwise, it

   // is NULL.  process is the one that will be dumped.  If

   // requesting_thread_id is meaningful and should be added to the

   // minidump, write_requester_stream is |true|.

   bool WriteMinidumpWithExceptionForProcess(DWORD requesting_thread_id,

                                             EXCEPTION_POINTERS* exinfo,

                                             MDRawAssertionInfo* assertion,

                                             HANDLE process,

                                             bool write_requester_stream);

   // Generates a new ID and stores it in next_minidump_id_, and stores the

   // path of the next minidump to be written in next_minidump_path_.

   void UpdateNextID();

   FilterCallback filter_;

   MinidumpCallback callback_;

   void* callback_context_;

   scoped_ptr<CrashGenerationClient> crash_generation_client_;

   // The directory in which a minidump will be written, set by the dump_path

   // argument to the constructor, or set_dump_path.

   wstring dump_path_;

   // The basename of the next minidump to be written, without the extension.

   wstring next_minidump_id_;

   // The full pathname of the next minidump to be written, including the file

   // extension.

   wstring next_minidump_path_;

   // Pointers to C-string representations of the above.  These are set when

   // the above wstring versions are set in order to avoid calling c_str during

   // an exception, as c_str may attempt to allocate heap memory.  These

   // pointers are not owned by the ExceptionHandler object, but their lifetimes

   // should be equivalent to the lifetimes of the associated wstring, provided

   // that the wstrings are not altered.

   const wchar_t* dump_path_c_;

   const wchar_t* next_minidump_id_c_;

   const wchar_t* next_minidump_path_c_;

   HMODULE dbghelp_module_;

   MiniDumpWriteDump_type minidump_write_dump_;

   MINIDUMP_TYPE dump_type_;

   HMODULE rpcrt4_module_;

   UuidCreate_type uuid_create_;

   // Tracks the handler types that were installed according to the

   // handler_types constructor argument.

   int handler_types_;

   // When installed_handler_ is true, previous_filter_ is the unhandled

   // exception filter that was set prior to installing ExceptionHandler as

   // the unhandled exception filter and pointing it to |this|.  NULL indicates

   // that there is no previous unhandled exception filter.

   LPTOP_LEVEL_EXCEPTION_FILTER previous_filter_;

 #if _MSC_VER >= 1400  // MSVC 2005/8

   // Beginning in VC 8, the CRT provides an invalid parameter handler that will

   // be called when some CRT functions are passed invalid parameters.  In

   // earlier CRTs, the same conditions would cause unexpected behavior or

   // crashes.

   _invalid_parameter_handler previous_iph_;

 #endif  // _MSC_VER >= 1400

   // The CRT allows you to override the default handler for pure

   // virtual function calls.

   _purecall_handler previous_pch_;

   // The exception handler thread.

   HANDLE handler_thread_;

   // True if the exception handler is being destroyed.

   // Starting with MSVC 2005, Visual C has stronger guarantees on volatile vars.

   // It has release semantics on write and acquire semantics on reads.

   // See the msdn documentation.

   volatile bool is_shutdown_;

   // The critical section enforcing the requirement that only one exception be

   // handled by a handler at a time.

   CRITICAL_SECTION handler_critical_section_;

   // Semaphores used to move exception handling between the exception thread

   // and the handler thread.  handler_start_semaphore_ is signalled by the

   // exception thread to wake up the handler thread when an exception occurs.

   // handler_finish_semaphore_ is signalled by the handler thread to wake up

   // the exception thread when handling is complete.

   HANDLE handler_start_semaphore_;

   HANDLE handler_finish_semaphore_;

   // The next 2 fields contain data passed from the requesting thread to

   // the handler thread.

   // The thread ID of the thread requesting the dump (either the exception

   // thread or any other thread that called WriteMinidump directly).

   DWORD requesting_thread_id_;

   // The exception info passed to the exception handler on the exception

   // thread, if an exception occurred.  NULL for user-requested dumps.

   EXCEPTION_POINTERS* exception_info_;

   // If the handler is invoked due to an assertion, this will contain a

   // pointer to the assertion information.  It is NULL at other times.

   MDRawAssertionInfo* assertion_;

   // The return value of the handler, passed from the handler thread back to

   // the requesting thread.

   bool handler_return_value_;

   // If true, the handler will intercept EXCEPTION_BREAKPOINT and

   // EXCEPTION_SINGLE_STEP exceptions.  Leave this false (the default)

   // to not interfere with debuggers.

   bool handle_debug_exceptions_;

   // Callers can request additional memory regions to be included in

   // the dump.

   AppMemoryList app_memory_info_;

   // A stack of ExceptionHandler objects that have installed unhandled

   // exception filters.  This vector is used by HandleException to determine

   // which ExceptionHandler object to route an exception to.  When an

   // ExceptionHandler is created with install_handler true, it will append

   // itself to this list.

   static vector<ExceptionHandler*>* handler_stack_;

   // The index of the ExceptionHandler in handler_stack_ that will handle the

   // next exception.  Note that 0 means the last entry in handler_stack_, 1

   // means the next-to-last entry, and so on.  This is used by HandleException

   // to support multiple stacked Breakpad handlers.

   static LONG handler_stack_index_;

   // handler_stack_critical_section_ guards operations on handler_stack_ and

   // handler_stack_index_. The critical section is initialized by the

   // first instance of the class and destroyed by the last instance of it.

   static CRITICAL_SECTION handler_stack_critical_section_;

   // The number of instances of this class.

   volatile static LONG instance_count_;

   // disallow copy ctor and operator=

   explicit ExceptionHandler(const ExceptionHandler &);

   void operator=(const ExceptionHandler &);

 };

 }  // namespace google_breakpad

 #pragma warning( pop )

 #endif  // CLIENT_WINDOWS_HANDLER_EXCEPTION_HANDLER_H__