1 | /* |
2 | * This file is part of the KDE Libraries |
3 | * Copyright (C) 2000 Timo Hummel <timo.hummel@sap.com> |
4 | * Tom Braun <braunt@fh-konstanz.de> |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Library General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Library General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Library General Public License |
16 | * along with this library; see the file COPYING.LIB. If not, write to |
17 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | * Boston, MA 02110-1301, USA. |
19 | * |
20 | */ |
21 | |
22 | #ifndef KCRASH_H |
23 | #define KCRASH_H |
24 | |
25 | #include <kdeui_export.h> |
26 | |
27 | class QString; |
28 | |
29 | /** |
30 | * This namespace contains functions to handle crashes. |
31 | * It allows you to set a crash handler function that will be called |
32 | * when your application crashes and also provides a default crash |
33 | * handler that implements the following functionality: |
34 | * @li Launches the KDE crash display application (DrKonqi) to let |
35 | * the user report the bug and/or debug it. |
36 | * @li Calls an emergency save function that you can set with |
37 | * setEmergencySaveFunction() to attempt to save the application's data. |
38 | * @li Autorestarts your application. |
39 | * |
40 | * @note All the above features are optional and you need to enable them |
41 | * explicitly. By default, the defaultCrashHandler() will not do anything. |
42 | * However, if you are using KApplication, it will by default enable launching |
43 | * DrKonqi on crashes, unless the --nocrashhandler argument was passed on |
44 | * the command line or the environment variable KDE_DEBUG is set to any value. |
45 | */ |
46 | namespace KCrash |
47 | { |
48 | /** |
49 | * The default crash handler. |
50 | * Do not call this function directly. Instead, use |
51 | * setCrashHandler() to set it as your application's crash handler. |
52 | * @param signal the signal number |
53 | * @note If you implement your own crash handler, you will have to |
54 | * call this function from your implementation if you want to use the |
55 | * features of this namespace. |
56 | */ |
57 | KDEUI_EXPORT void defaultCrashHandler (int signal); |
58 | |
59 | /** |
60 | * Typedef for a pointer to a crash handler function. |
61 | * The function's argument is the number of the signal. |
62 | */ |
63 | typedef void (*HandlerType)(int); |
64 | |
65 | /** |
66 | * Install a function to be called when a crash occurs. |
67 | * A crash occurs when one of the following signals is |
68 | * caught: SIGSEGV, SIGBUS, SIGFPE, SIGILL, SIGABRT. |
69 | * @param handler this can be one of: |
70 | * @li null, in which case signal catching is disabled |
71 | * (by setting the signal handler for the crash signals to SIG_DFL) |
72 | * @li a user defined function in the form: |
73 | * static (if in a class) void myCrashHandler(int); |
74 | * @li if handler is omitted, the default crash handler is installed |
75 | * @note If you use setDrKonqiEnabled(true), setEmergencySaveFunction(myfunc) |
76 | * or setFlags(AutoRestart), you do not need to call this function |
77 | * explicitly. The default crash handler is automatically installed by |
78 | * those functions if needed. However, if you set a custom crash handler, |
79 | * those functions will not change it. |
80 | */ |
81 | KDEUI_EXPORT void setCrashHandler (HandlerType handler = defaultCrashHandler); |
82 | |
83 | /** |
84 | * Returns the installed crash handler. |
85 | * @return the crash handler |
86 | */ |
87 | KDEUI_EXPORT HandlerType crashHandler(); |
88 | |
89 | /** |
90 | * Installs a function which should try to save the application's data. |
91 | * @note It is the crash handler's responsibility to call this function. |
92 | * Therefore, if no crash handler is set, the default crash handler |
93 | * is installed to ensure the save function will be called. |
94 | * @param saveFunction the handler to install |
95 | */ |
96 | KDEUI_EXPORT void setEmergencySaveFunction (HandlerType saveFunction = 0); |
97 | |
98 | /** |
99 | * Returns the currently set emergency save function. |
100 | * @return the emergency save function |
101 | */ |
102 | KDEUI_EXPORT HandlerType emergencySaveFunction(); |
103 | |
104 | /** |
105 | * Options to determine how the default crash handler should behave. |
106 | */ |
107 | enum CrashFlag { |
108 | KeepFDs = 1, ///< don't close all file descriptors immediately |
109 | SaferDialog = 2, ///< start DrKonqi without arbitrary disk access |
110 | AlwaysDirectly = 4, ///< never try to to start DrKonqi via kdeinit. Use fork() and exec() instead. |
111 | AutoRestart = 8 ///< autorestart this application. Only sensible for KUniqueApplications. @since 4.1. |
112 | }; |
113 | Q_DECLARE_FLAGS(CrashFlags, CrashFlag) |
114 | |
115 | /** |
116 | * Set options to determine how the default crash handler should behave. |
117 | * @param flags ORed together CrashFlags |
118 | */ |
119 | KDEUI_EXPORT void setFlags( CrashFlags flags ); |
120 | |
121 | /** |
122 | * Sets the application @p path which should be passed to |
123 | * DrKonqi, our nice crash display application. |
124 | * @param path the application path |
125 | */ |
126 | KDEUI_EXPORT void setApplicationPath (const QString &path); |
127 | |
128 | /** |
129 | * Sets the application @p name which should be passed to |
130 | * DrKonqi, our nice crash display application. |
131 | * @param name the name of the application, as shown in DrKonqi |
132 | */ |
133 | KDEUI_EXPORT void setApplicationName (const QString &name); |
134 | |
135 | /** |
136 | * Enables or disables launching DrKonqi from the crash handler. |
137 | * By default, launching DrKonqi is disabled. However, KApplication |
138 | * will enable it in its constructor, so you don't need to call this |
139 | * function if you are using KApplication. |
140 | * @note It is the crash handler's responsibility to launch DrKonqi. |
141 | * Therefore, if no crash handler is set, this method also installs |
142 | * the default crash handler to ensure that DrKonqi will be launched. |
143 | * @since 4.5 |
144 | */ |
145 | KDEUI_EXPORT void setDrKonqiEnabled(bool enabled); |
146 | |
147 | /** |
148 | * Returns true if DrKonqi is set to be launched from the crash handler or false otherwise. |
149 | * @since 4.5 |
150 | */ |
151 | KDEUI_EXPORT bool isDrKonqiEnabled(); |
152 | } |
153 | |
154 | Q_DECLARE_OPERATORS_FOR_FLAGS(KCrash::CrashFlags) |
155 | |
156 | #endif |
157 | |
158 | |