Vidalia  0.3.1
CrashReporter.h
Go to the documentation of this file.
1 /*
2 ** This file is part of Vidalia, and is subject to the license terms in the
3 ** LICENSE file, found in the top level directory of this distribution. If you
4 ** did not receive the LICENSE file with this file, you may obtain it from the
5 ** Vidalia source package distributed by the Vidalia Project at
6 ** http://www.torproject.org/projects/vidalia.html. No part of Vidalia,
7 ** including this file, may be copied, modified, propagated, or distributed
8 ** except according to the terms described in the LICENSE file.
9 */
10 
11 /*
12 ** \file CrashReporter.h
13 ** \brief General routines to install a Breakpad-based exception handler and
14 ** set options related to launching the crash reporting application.
15 */
16 
17 #ifndef _CRASHREPORTER_H
18 #define _CRASHREPORTER_H
19 
20 class QString;
21 class QStringList;
22 
23 
24 namespace CrashReporter
25 {
26  /** Defines the maximum length of the absolute path plus filename of the
27  * crash reporting executable displayed when the exception handler is
28  * called.
29  */
30 #if defined(Q_OS_WIN32)
31  static const int MAX_PATH_LEN = 260;
32 #else
33  static const int MAX_PATH_LEN = 4096; /* Is there a better value for this? */
34 #endif
35 
36  /** Defines the maximum length of the command line arguments used to restart
37  * the crashed application by the crash reporter. The maximum command line
38  * length is based on Windows' 32K character command line limit, according
39  * to the MSDN documents.
40  */
41  static const int MAX_CMD_LEN = 32768;
42 
43  /** Defines the maximum length of a build version string that can be set
44  * by set_build_version().
45  * \sa set_build_version()
46  */
47  static const int MAX_VERSION_LEN = 64;
48 
49  /** Installs the Breakpad exception handler and sets the static global
50  * variables used by the exception handler to launch the crash reporting
51  * application. Minidumps will be writen to <b>dumpPath</b>, which will
52  * be created if it doesn't already exist.
53  * \sa remove_exception_handler()
54  */
55  bool install_exception_handler(const QString &dumpPath);
56 
57  /** Removes the application's exception handler previously created by
58  * install_exception_handler(). If no exception handler was previously created,
59  * no action will be taken.
60  * \sa install_exception_handler()
61  */
62  void remove_exception_handler(void);
63 
64  /** Sets <b>crashReporter</b> as the executable that gets called when the
65  * exception handler catches a crash. If <b>crashReporter</b> contains one
66  * or more spaces, the given path will be wrapped in quotes. The caller is
67  * responsible for ensuring that <b>crashReporter</b> is no greater than
68  * CrashReporter::MAX_PATH_LEN (including added quotes). Returns true if
69  * the crash reporting application was set successfully, or false if
70  * <b>crashReporter</b> was too long.
71  */
72  bool set_crash_reporter(const QString &crashReporter);
73 
74  /** Sets the <b>executable</b> and <b>args</b> that will be passed to the
75  * crash reporting application, so it can restart the crashed application
76  * with the same arguments as before it crashed. If the <b>executable</b>
77  * path or any of <b>args</b> contains a space, they will be quoted before
78  * being passed to the crash reporting application. The path to the
79  * generated minidump, crash reporting application, executable to restart
80  * and any arguments must fit within MAX_CMD_LEN, including any added
81  * quotes.
82  * \sa set_crash_reporter()
83  */
84  bool set_restart_options(const QString &executable,
85  const QStringList &arguments);
86 
87  /** Sets <b>version</b> as the build version identifier written to the
88  * extra information file alongside a minidump. The version string must
89  * be no longer than CrashReporter::MAX_VERSION_LEN.
90  */
91  bool set_build_version(const QString &version);
92 }
93 
94 #endif
95