simgear/structure/exception.hxx

   1 /**
   2  * \file exception.hxx
   3  * Interface definition for SimGear base exceptions.
   4  * Started Spring 2001 by David Megginson, david@megginson.com
   5  * This code is released into the Public Domain.
   6  *
   7  * $Id$
   8  */
   9
  10 #ifndef __SIMGEAR_MISC_EXCEPTION_HXX
  11 #define __SIMGEAR_MISC_EXCEPTION_HXX 1
  12
  13 #include <exception>
  14 #include <simgear/compiler.h>
  15 #include <string>
  16
  17 using std::string;
  18
  19 /**
  20  * Information encapsulating a single location in an external resource
  21  *
  22  * A position in the resource my optionally be provided, either by
  23  * line number, line number and column number, or byte offset from the
  24  * beginning of the resource.
  25  */
  26 class sg_location
  27 {
  28 public:
  29   enum {max_path = 1024};
  30   sg_location ();
  31   sg_location(const std::string& path, int line = -1, int column = -1);
  32   explicit sg_location(const char* path, int line = -1, int column = -1);
  33   virtual ~sg_location() throw ();
  34   virtual const char* getPath() const;
  35   virtual void setPath (const char* path);
  36   virtual int getLine () const;
  37   virtual void setLine (int line);
  38   virtual int getColumn () const;
  39   virtual void setColumn (int column);
  40   virtual int getByte () const;
  41   virtual void setByte (int byte);
  42   virtual std::string asString () const;
  43 private:
  44   char _path[max_path];
  45   int _line;
  46   int _column;
  47   int _byte;
  48 };
  49
  50
  51 /**
  52  * Abstract base class for all throwables.
  53  */
  54 class sg_throwable : public std::exception
  55 {
  56 public:
  57   enum {MAX_TEXT_LEN = 1024};
  58   sg_throwable ();
  59   sg_throwable (const char* message, const char* origin = 0);
  60   virtual ~sg_throwable () throw ();
  61   virtual const char* getMessage () const;
  62   virtual const std::string getFormattedMessage () const;
  63   virtual void setMessage (const char* message);
  64   virtual const char* getOrigin () const;
  65   virtual void setOrigin (const char *origin);
  66   virtual const char* what() const throw();
  67 private:
  68   char _message[MAX_TEXT_LEN];
  69   char _origin[MAX_TEXT_LEN];
  70 };
  71
  72
  73
  74 /**
  75  * An unexpected fatal error.
  76  *
  77  * Methods and functions show throw this exception when something
  78  * very bad has happened (such as memory corruption or
  79  * a totally unexpected internal value).  Applications should catch
  80  * this exception only at the top level if at all, and should
  81  * normally terminate execution soon afterwards.
  82  */
  83 class sg_error : public sg_throwable
  84 {
  85 public:
  86   sg_error ();
  87   sg_error (const char* message, const char* origin = 0);
  88   sg_error (const std::string& message, const std::string& origin = "");
  89   virtual ~sg_error () throw ();
  90 };
  91
  92
  93 /**
  94  * Base class for all SimGear exceptions.
  95  *
  96  * SimGear-based code should throw this exception only when no
  97  * more specific exception applies.  It may not be caught until
  98  * higher up in the application, where it is not possible to
  99  * resume normal operations if desired.
 100  *
 101  * A caller can catch sg_exception by default to ensure that
 102  * all exceptions are caught.  Every SimGear exception can contain
 103  * a human-readable error message and a human-readable string
 104  * indicating the part of the application causing the exception
 105  * (as an aid to debugging, only).
 106  */
 107 class sg_exception : public sg_throwable
 108 {
 109 public:
 110   sg_exception ();
 111   sg_exception (const char* message, const char* origin = 0);
 112   sg_exception (const std::string& message, const std::string& = "");
 113   virtual ~sg_exception () throw ();
 114 };
 115
 116
 117 /**
 118  * An I/O-related SimGear exception.
 119  *
 120  * SimGear-based code should throw this exception when it fails
 121  * to read from or write to an external resource, such as a file,
 122  * socket, URL, or database.
 123  *
 124  * In addition to the functionality of sg_exception, an
 125  * sg_io_exception may contain location information, such as the name
 126  * of a file or URL, and possible also a location in that file or URL.
 127  */
 128 class sg_io_exception : public sg_exception
 129 {
 130 public:
 131   sg_io_exception ();
 132   sg_io_exception (const char* message, const char* origin = 0);
 133   sg_io_exception (const char* message, const sg_location &location,
 134                    const char* origin = 0);
 135   sg_io_exception (const std::string &message, const std::string &origin = "");
 136   sg_io_exception (const std::string &message, const sg_location &location,
 137     const std::string &origin = "");
 138
 139   virtual ~sg_io_exception () throw ();
 140   virtual const std::string getFormattedMessage () const;
 141   virtual const sg_location &getLocation () const;
 142   virtual void setLocation (const sg_location &location);
 143 private:
 144   sg_location _location;
 145 };
 146
 147
 148 /**
 149  * A format-related SimGear exception.
 150  *
 151  * SimGear-based code should throw this exception when a string
 152  * does not appear in the expected format (for example, a date
 153  * string does not conform to ISO 8601).
 154  *
 155  * In addition to the functionality of sg_exception, an
 156  * sg_format_exception can contain a copy of the original malformated
 157  * text.
 158  */
 159 class sg_format_exception : public sg_exception
 160 {
 161 public:
 162   sg_format_exception ();
 163   sg_format_exception (const char* message, const char* text,
 164                        const char* origin = 0);
 165   sg_format_exception (const std::string& message, const std::string& text,
 166                        const std::string& origin = "");
 167   virtual ~sg_format_exception () throw ();
 168   virtual const char* getText () const;
 169   virtual void setText (const char* text);
 170 private:
 171   char _text[MAX_TEXT_LEN];
 172 };
 173
 174
 175 /**
 176  * A range-related SimGear exception.
 177  *
 178  * SimGear-based code should throw this exception when a value falls
 179  * outside the range where it can reasonably be handled; examples
 180  * include longitude outside the range -180:180, unrealistically high
 181  * forces or velocities, an illegal airport code, etc.  A range
 182  * exception usually means that something has gone wrong internally.
 183  */
 184 class sg_range_exception : public sg_exception
 185 {
 186 public:
 187   sg_range_exception ();
 188   sg_range_exception (const char* message,
 189                       const char* origin = 0);
 190   sg_range_exception (const std::string& message,
 191                       const std::string& origin = "");
 192   virtual ~sg_range_exception () throw ();
 193 };
 194
 195 #endif
 196
 197 // end of exception.hxx