Vidalia 0.2.10

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