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 <s> the exception name followed by
  58   //! the error message.
  59   //! Level: Advanced
  60   //! Warning:
  61   //! The operator "OStream& operator<< (Standard_OStream&,
  62   //! Handle(Standard_Failure)&)"
  63   //! is implemented. (This operator uses the method Print)
  64   Standard_EXPORT void Print (Standard_OStream& s) const;
  65
  66   //! Returns error message
  67   Standard_EXPORT virtual Standard_CString GetMessageString() const;
  68
  69   //! Sets error message
  70   Standard_EXPORT virtual void SetMessageString (const Standard_CString aMessage);
  71
  72   Standard_EXPORT void Reraise();
  73
  74   Standard_EXPORT void Reraise (const Standard_CString aMessage);
  75
  76   //! Reraises a caught exception and changes its error message.
  77   Standard_EXPORT void Reraise (const Standard_SStream& aReason);
  78
  79   //! Raises an exception of type "Failure" and associates
  80   //! an error message to it. The message can be printed
  81   //! in an exception handler.
  82   Standard_EXPORT static void Raise (const Standard_CString aMessage = "");
  83
  84   //! Raises an exception of type "Failure" and associates
  85   //! an error message to it. The message can be constructed
  86   //! at run-time.
  87   Standard_EXPORT static void Raise (const Standard_SStream& aReason);
  88
  89   //! Used to construct an instance of the exception object
  90   //! as a handle. Shall be used to protect against possible
  91   //! construction of exception object in C stack -- that is
  92   //! dangerous since some of methods require that object
  93   //! was allocated dynamically.
  94   Standard_EXPORT static Handle(Standard_Failure) NewInstance (const Standard_CString aMessage);
  95
  96   //! Used to throw CASCADE exception from C signal handler.
  97   //! On platforms that do not allow throwing C++ exceptions
  98   //! from this handler (e.g. Linux), uses longjump to get to
  99   //! the current active signal handler, and only then is
 100   //! converted to C++ exception.
 101   Standard_EXPORT void Jump();
 102
 103   //! Returns the last caught exception.
 104   //! Needed when exceptions are emulated by C longjumps,
 105   //! in other cases is also provided for compatibility.
 106   Standard_DEPRECATED("This method is deprecated (not thread-safe), use standard C++ mechanism instead")
 107   Standard_EXPORT static Handle(Standard_Failure) Caught();
 108
 109
 110
 111   DEFINE_STANDARD_RTTIEXT(Standard_Failure,Standard_Transient)
 112
 113 protected:
 114
 115
 116   //! Used only if standard C++ exceptions are used.
 117   //! Throws exception of the same type as this by C++ throw,
 118   //! and stores current object as last thrown exception,
 119   //! to be accessible by method Caught()
 120   Standard_EXPORT virtual void Throw() const;
 121
 122
 123
 124 private:
 125
 126
 127   Standard_CString myMessage;
 128
 129
 130 };
 131
 132 inline Standard_OStream& operator << (Standard_OStream& AStream,
 133                                       const Handle(Standard_Failure)& AFailure)
 134 {
 135   AFailure->Print(AStream);
 136   return AStream;
 137 }
 138
 139 inline Standard_OStream& operator << (Standard_OStream& AStream,
 140                                       const Standard_Failure& AFailure)
 141 {
 142   AFailure.Print(AStream);
 143   return AStream;
 144 }
 145
 146 #endif // _Standard_Failure_HeaderFile