kdeui/util/kcrash.h

   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 class handles segmentation-faults.
  31  * By default it displays a  message-box saying the application crashed.
  32  * This default can be overridden by setting a custom crash handler with
  33  * setCrashHandler().
  34  * If a function is specified with setEmergencySaveFunction() it will
  35  * be called by the default crash handler, giving the application a chance
  36  * to save its data.
  37  */
  38 namespace KCrash
  39 {
  40   /**
  41    * The default crash handler.
  42    * @param signal the signal number
  43    */
  44   KDEUI_EXPORT void defaultCrashHandler (int signal);
  45
  46   /**
  47    * This function type is a pointer to a crash handler function.
  48    * The function's argument is the number of the signal.
  49    */
  50   typedef void (*HandlerType)(int);
  51
  52   /**
  53    * Install a function to be called in case a SIGSEGV is caught.
  54    * @param handler HandlerType handler can be one of
  55    * @li null in which case signal-catching is disabled
  56    *  (by calling signal(SIGSEGV, SIG_DFL))
  57    * @li if handler is omitted the default crash handler is installed.
  58    * @li an user defined function in the form:
  59    * static (if in a class) void myCrashHandler(int);
  60    * @param handler the crash handler
  61    */
  62
  63   KDEUI_EXPORT void setCrashHandler (HandlerType handler = defaultCrashHandler);
  64
  65   /**
  66    * Returns the installed crash handler.
  67    * @return the crash handler
  68    */
  69   KDEUI_EXPORT HandlerType crashHandler();
  70
  71   /**
  72    * Installs a function which should try to save the applications data.
  73    * It is the crash handler's responsibility to call this function.
  74    * Therefore, if no crash handler is set, the default crash handler
  75    * is installed to ensure the save function is called.
  76    * @param saveFunction the handler to install
  77    */
  78   KDEUI_EXPORT void setEmergencySaveFunction (HandlerType saveFunction = 0);
  79
  80   /**
  81    * Return the currently set emergency save function.
  82    * @return the emergency save function
  83    */
  84   KDEUI_EXPORT HandlerType emergencySaveFunction();
  85
  86   /**
  87    * Options to determine how KCrash should behave while firing up DrKonqi.
  88    */
  89   enum CrashFlag {
  90     KeepFDs = 1,          ///< don't close all file descriptors immediately
  91     SaferDialog = 2,      ///< start DrKonqi without arbitrary disk access
  92     AlwaysDirectly = 4,   ///< never try to to start DrKonqi via kdeinit
  93     AutoRestart = 8       ///< autorestart this application. Only sensible for KUniqueApplications. @since 4.1.
  94   };
  95   Q_DECLARE_FLAGS(CrashFlags, CrashFlag)
  96
  97   /**
  98    * Set DrKonqi fire-up options.
  99    * @param flags ORed together CrashFlags
 100    */
 101   KDEUI_EXPORT void setFlags( CrashFlags flags );
 102
 103   /**
 104    * Sets the application @p path which should be passed to
 105    * Dr. Konqi, our nice crash display application.
 106    * @param path the application path.
 107    */
 108   KDEUI_EXPORT void setApplicationPath (const QString &path);
 109
 110   /**
 111    * Sets the application name @p name which should be passed to
 112    * Dr. Konqi, our nice crash display application.
 113    * @param name the name of the application, as shown in Dr. Konqi
 114    */
 115   KDEUI_EXPORT void setApplicationName (const QString &name);
 116 }
 117
 118 Q_DECLARE_OPERATORS_FOR_FLAGS(KCrash::CrashFlags)
 119
 120 #endif
 121