Vidalia 0.2.12

CrashReporter.h

Go to the documentation of this file.
00001 /*
00002 **  This file is part of Vidalia, and is subject to the license terms in the
00003 **  LICENSE file, found in the top level directory of this distribution. If you
00004 **  did not receive the LICENSE file with this file, you may obtain it from the
00005 **  Vidalia source package distributed by the Vidalia Project at
00006 **  http://www.vidalia-project.net/. No part of Vidalia, including this file,
00007 **  may be copied, modified, propagated, or distributed except according to the
00008 **  terms described in the LICENSE file.
00009 */
00010 
00011 /*
00012 ** \file CrashReporter.h
00013 ** \brief General routines to install a Breakpad-based exception handler and
00014 ** set options related to launching the crash reporting application.
00015 */
00016 
00017 #ifndef _CRASHREPORTER_H
00018 #define _CRASHREPORTER_H
00019 
00020 class QString;
00021 class QStringList;
00022 
00023 
00024 namespace CrashReporter
00025 {
00026   /** Defines the maximum length of the absolute path plus filename of the
00027    * crash reporting executable displayed when the exception handler is
00028    * called.
00029    */
00030 #if defined(Q_OS_WIN32)
00031   static const int MAX_PATH_LEN = 260;
00032 #else
00033   static const int MAX_PATH_LEN = 4096; /* Is there a better value for this? */
00034 #endif
00035 
00036   /** Defines the maximum length of the command line arguments used to restart
00037    * the crashed application by the crash reporter. The maximum command line
00038    * length is based on Windows' 32K character command line limit, according
00039    * to the MSDN documents.
00040    */
00041   static const int MAX_CMD_LEN = 32768;
00042 
00043   /** Defines the maximum length of a build version string that can be set
00044    * by set_build_version().
00045    * \sa set_build_version()
00046    */
00047   static const int MAX_VERSION_LEN = 64;
00048 
00049   /** Installs the Breakpad exception handler and sets the static global
00050    * variables used by the exception handler to launch the crash reporting
00051    * application. Minidumps will be writen to <b>dumpPath</b>, which will
00052    * be created if it doesn't already exist.
00053    * \sa remove_exception_handler()
00054    */
00055   bool install_exception_handler(const QString &dumpPath);
00056 
00057   /** Removes the application's exception handler previously created by
00058    * install_exception_handler(). If no exception handler was previously created,
00059    * no action will be taken.
00060    * \sa install_exception_handler()
00061    */
00062   void remove_exception_handler(void);
00063 
00064   /** Sets <b>crashReporter</b> as the executable that gets called when the
00065    * exception handler catches a crash. If <b>crashReporter</b> contains one
00066    * or more spaces, the given path will be wrapped in quotes. The caller is
00067    * responsible for ensuring that <b>crashReporter</b> is no greater than
00068    * CrashReporter::MAX_PATH_LEN (including added quotes). Returns true if
00069    * the crash reporting application was set successfully, or false if
00070    * <b>crashReporter</b> was too long.
00071    */
00072   bool set_crash_reporter(const QString &crashReporter);
00073 
00074   /** Sets the <b>executable</b> and <b>args</b> that will be passed to the
00075    * crash reporting application, so it can restart the crashed application
00076    * with the same arguments as before it crashed. If the <b>executable</b>
00077    * path or any of <b>args</b> contains a space, they will be quoted before
00078    * being passed to the crash reporting application. The path to the
00079    * generated minidump, crash reporting application, executable to restart
00080    * and any arguments must fit within MAX_CMD_LEN, including any added
00081    * quotes.
00082    * \sa set_crash_reporter()
00083    */
00084   bool set_restart_options(const QString &executable,
00085                            const QStringList &arguments);
00086 
00087   /** Sets <b>version</b> as the build version identifier written to the
00088    * extra information file alongside a minidump. The version string must
00089    * be no longer than CrashReporter::MAX_VERSION_LEN.
00090    */
00091   bool set_build_version(const QString &version);
00092 }
00093 
00094 #endif
00095