src/Standard/Standard_Failure.hxx

   1 // Created on: 1991-09-05
   2 // Created by: Philippe COICADAN
   3 // Copyright (c) 1991-1999 Matra Datavision
   4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 //
   6 // This file is part of Open CASCADE Technology software library.
   7 //
   8 // This library is free software; you can redistribute it and/or modify it under
   9 // the terms of the GNU Lesser General Public License version 2.1 as published
  10 // by the Free Software Foundation, with special exception defined in the file
  11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 // distribution for complete text of the license and disclaimer of any warranty.
  13 //
  14 // Alternatively, this file may be used under the terms of Open CASCADE
  15 // commercial license or contractual agreement.
  16
  17 #ifndef _Standard_Failure_HeaderFile
  18 #define _Standard_Failure_HeaderFile
  19
  20 #include <Standard.hxx>
  21 #include <Standard_Type.hxx>
  22
  23 #include <Standard_CString.hxx>
  24 #include <Standard_Transient.hxx>
  25 #include <Standard_OStream.hxx>
  26 #include <Standard_SStream.hxx>
  27 class Standard_NoSuchObject;
  28
  29
  30 class Standard_Failure;
  31 DEFINE_STANDARD_HANDLE(Standard_Failure, Standard_Transient)
  32
  33
  34 //! Forms the root of the entire exception hierarchy.
  35 class Standard_Failure : public Standard_Transient
  36 {
  37
  38 public:
  39
  40
  41
  42   //! Creates a status object of type "Failure".
  43   Standard_EXPORT Standard_Failure();
  44
  45   //! Copy constructor
  46   Standard_EXPORT Standard_Failure (const Standard_Failure& f);
  47
  48   //! Creates a status object of type "Failure".
  49   Standard_EXPORT Standard_Failure(const Standard_CString aString);
  50
  51   //! Assignment operator
  52   Standard_EXPORT Standard_Failure& operator= (const Standard_Failure& f);
  53
  54   //! Destructor
  55   Standard_EXPORT ~Standard_Failure();
  56
  57   //! Prints on the stream @p theStream the exception name followed by the error message.
  58   //!
  59   //! Note: there is a short-cut @c operator<< (Standard_OStream&, Handle(Standard_Failure)&)
  60   Standard_EXPORT void Print (Standard_OStream& theStream) const;
  61
  62   //! Returns error message
  63   Standard_EXPORT virtual Standard_CString GetMessageString() const;
  64
  65   //! Sets error message
  66   Standard_EXPORT virtual void SetMessageString (const Standard_CString aMessage);
  67
  68   Standard_EXPORT void Reraise();
  69
  70   Standard_EXPORT void Reraise (const Standard_CString aMessage);
  71
  72   //! Reraises a caught exception and changes its error message.
  73   Standard_EXPORT void Reraise (const Standard_SStream& aReason);
  74
  75   //! Raises an exception of type "Failure" and associates
  76   //! an error message to it. The message can be printed
  77   //! in an exception handler.
  78   Standard_EXPORT static void Raise (const Standard_CString aMessage = "");
  79
  80   //! Raises an exception of type "Failure" and associates
  81   //! an error message to it. The message can be constructed
  82   //! at run-time.
  83   Standard_EXPORT static void Raise (const Standard_SStream& aReason);
  84
  85   //! Used to construct an instance of the exception object
  86   //! as a handle. Shall be used to protect against possible
  87   //! construction of exception object in C stack -- that is
  88   //! dangerous since some of methods require that object
  89   //! was allocated dynamically.
  90   Standard_EXPORT static Handle(Standard_Failure) NewInstance (const Standard_CString aMessage);
  91
  92   //! Used to throw CASCADE exception from C signal handler.
  93   //! On platforms that do not allow throwing C++ exceptions
  94   //! from this handler (e.g. Linux), uses longjump to get to
  95   //! the current active signal handler, and only then is
  96   //! converted to C++ exception.
  97   Standard_EXPORT void Jump();
  98
  99   //! Returns the last caught exception.
 100   //! Needed when exceptions are emulated by C longjumps,
 101   //! in other cases is also provided for compatibility.
 102   Standard_DEPRECATED("This method is deprecated (not thread-safe), use standard C++ mechanism instead")
 103   Standard_EXPORT static Handle(Standard_Failure) Caught();
 104
 105
 106
 107   DEFINE_STANDARD_RTTIEXT(Standard_Failure,Standard_Transient)
 108
 109 protected:
 110
 111
 112   //! Used only if standard C++ exceptions are used.
 113   //! Throws exception of the same type as this by C++ throw,
 114   //! and stores current object as last thrown exception,
 115   //! to be accessible by method Caught()
 116   Standard_EXPORT virtual void Throw() const;
 117
 118
 119
 120 private:
 121
 122
 123   Standard_CString myMessage;
 124
 125
 126 };
 127
 128 inline Standard_OStream& operator << (Standard_OStream& AStream,
 129                                       const Handle(Standard_Failure)& AFailure)
 130 {
 131   AFailure->Print(AStream);
 132   return AStream;
 133 }
 134
 135 inline Standard_OStream& operator << (Standard_OStream& AStream,
 136                                       const Standard_Failure& AFailure)
 137 {
 138   AFailure.Print(AStream);
 139   return AStream;
 140 }
 141
 142 #endif // _Standard_Failure_HeaderFile