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   virtual ~sg_io_exception () throw ();
 137   virtual const std::string getFormattedMessage () const;
 138   virtual const sg_location &getLocation () const;
 139   virtual void setLocation (const sg_location &location);
 140 private:
 141   sg_location _location;
 142 };
 143
 144
 145 /**
 146  * A format-related SimGear exception.
 147  *
 148  * SimGear-based code should throw this exception when a string
 149  * does not appear in the expected format (for example, a date
 150  * string does not conform to ISO 8601).
 151  *
 152  * In addition to the functionality of sg_exception, an
 153  * sg_format_exception can contain a copy of the original malformated
 154  * text.
 155  */
 156 class sg_format_exception : public sg_exception
 157 {
 158 public:
 159   sg_format_exception ();
 160   sg_format_exception (const char* message, const char* text,
 161                        const char* origin = 0);
 162   sg_format_exception (const std::string& message, const std::string& text,
 163                        const std::string& origin = "");
 164   virtual ~sg_format_exception () throw ();
 165   virtual const char* getText () const;
 166   virtual void setText (const char* text);
 167 private:
 168   char _text[MAX_TEXT_LEN];
 169 };
 170
 171
 172 /**
 173  * A range-related SimGear exception.
 174  *
 175  * SimGear-based code should throw this exception when a value falls
 176  * outside the range where it can reasonably be handled; examples
 177  * include longitude outside the range -180:180, unrealistically high
 178  * forces or velocities, an illegal airport code, etc.  A range
 179  * exception usually means that something has gone wrong internally.
 180  */
 181 class sg_range_exception : public sg_exception
 182 {
 183 public:
 184   sg_range_exception ();
 185   sg_range_exception (const char* message,
 186                       const char* origin = 0);
 187   sg_range_exception (const std::string& message,
 188                       const std::string& origin = "");
 189   virtual ~sg_range_exception () throw ();
 190 };
 191
 192 #endif
 193
 194 // end of exception.hxx