exception.hpp

一个gps小工具包

#pragma ident "$Id: Exception.hpp 462 2007-04-09 14:23:14Z btolman $"

//============================================================================
//
//  This file is part of GPSTk, the GPS Toolkit.
//
//  The GPSTk is free software; you can redistribute it and/or modify
//  it under the terms of the GNU Lesser General Public License as published
//  by the Free Software Foundation; either version 2.1 of the License, or
//  any later version.
//
//  The GPSTk is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU Lesser General Public License for more details.
//
//  You should have received a copy of the GNU Lesser General Public
//  License along with GPSTk; if not, write to the Free Software Foundation,
//  Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//  
//  Copyright 2004, The University of Texas at Austin
//
//============================================================================

//============================================================================
//
//This software developed by Applied Research Laboratories at the University of
//Texas at Austin, under contract to an agency or agencies within the U.S. 
//Department of Defense. The U.S. Government retains all rights to use,
//duplicate, distribute, disclose, or release this software. 
//
//Pursuant to DoD Directive 523024 
//
// DISTRIBUTION STATEMENT A: This software has been approved for public 
//                           release, distribution is unlimited.
//
//=============================================================================

/**
 * @file Exception.hpp
 * Exceptions for all of GPSTK, including location information
 */

// The unusual include macro below is done this way because xerces
// #defines EXCEPTION_HPP in their own exception class header file.
#ifndef GPSTK_EXCEPTION_HPP
#define GPSTK_EXCEPTION_HPP

#include <iostream>
#include <vector>
#include <string>

namespace gpstk
{
      /**
       * @defgroup exceptiongroup Exception Classes
       * These classes are the exceptions that can be thrown in
       * the library code. Use these in your catch() blocks
       * and you'll be able to get more information
       * than what std::exception provides.  Use GPSTK_THROW()
       * and GPSTK_RETHROW() to throw or rethrow these exceptions
       * to automatically add line and file information to your
       * exceptions..
       */

      /// A class for recording locations (in the source code) of
      /// exceptions being thrown.
   class ExceptionLocation
   {
   public:
         /**
          * Constructor for location information.
          * @param filename name of source file where exception occurred.
          * @param funcName name of function where exception occurred.
          * @param lineNum line of source file where exception occurred.
          */
      ExceptionLocation(const std::string& filename = std::string(),
                        const std::string& funcName = std::string(),
                        const unsigned long& lineNum = 0)
         throw()
            : fileName(filename), functionName(funcName),
              lineNumber(lineNum)
      { }

         /**
          * Destructor.
          */
      ~ExceptionLocation() throw() {}

         /// Accessor for name of source file where exception occurred.
      std::string getFileName() const 
         throw() 
      { return fileName; }
         /// Accessor for name of function where exception occurred.
      std::string getFunctionName() const 
         throw() 
      { return functionName; }
         /// Accessor for line of source file where exception occurred.
      unsigned long getLineNumber() const 
         throw()
      { return lineNumber; }

         /**
          * Debug output function.
          * @param s stream to output debugging information for this class to.
          */
      void dump(std::ostream& s) const throw();

         /// Dump to a string
      std::string what() const throw();

         /**
          * Output stream operator for ::ExceptionLocation.
          * This is intended just to dump all the data in the
          * ::ExceptionLocation to the indicated stream.  \warning Warning: It
          * will _not_ preserve the state of the stream.
          * @param s stream to send ::ExceptionLocation information to.
          * @param e ::ExceptionLocation to "dump".
          * @return a reference to the stream \c s.
          */
      friend std::ostream& operator<<( std::ostream& s,
                                       const ExceptionLocation& e )
         throw();

   private:
         /// Name of source file where exception occurred.
      std::string fileName;
         /// Name of function where exception occurred.
      std::string functionName;
         /// Line in source file where exception occurred.
      unsigned long lineNumber;
   }; // class ExceptionLocation
   
      /**
       * The Exception class is the base class from which all
       * exception objects thrown in the library are derived. None of
       * the functions in this class throws exceptions because an
       * exception has probably already been thrown or is about to be
       * thrown.  Each exception object contains the following:
       * -  A stack of exception message text strings (descriptions).
       * -  An error ID.
       * -  A severity code.
       * -  An error code group.
       * -  Information about where the exception was thrown.
       *
       * Exception provides all of the functions required for it and
       * its derived classes, including functions that operate on the
       * text strings in the stack.
       *
       * @sa exceptiontest.cpp for some examples of how to use this class.
       *
       * @ingroup exceptiongroup
       */
   class Exception
   {
   public:
         /// Exception severity classes.
      enum Severity
      {
         unrecoverable, /**< program can not recover from this exception */
         recoverable    /**< program can recover from this exception */
      };

         /**
          * Default constructor.
          * Does nothing.
          */
      Exception() throw();

         /**
          * Full constructor for exception.
          * @param errorText text message detailing exception.
          * @param errorId error code related to exception e.g. MQ result
          * code.
          * @param severity severity of error.
          */
      Exception(const std::string& errorText, 
                const unsigned long& errorId = 0,
                const Severity& severity = unrecoverable)
         throw();
         /// Copy constructor.
      Exception(const Exception& exception) 
         throw();
         /// Destructor.
      ~Exception() 
         throw() 
      {};

         /// Assignment operator.
      Exception& operator=(const Exception& e)
         throw();

         /**
          * Ends the application. Normally, the library only intends
          * this function to be used internally by the library's
          * exception-handling macros when the compiler you are using
          * does not support C++ exception handling. This only occurs
          * if you define the NO_EXCEPTIONS_SUPPORT macro.
          */
      void terminate()
         throw()
      { exit(1); };

         /// Returns the error ID of the exception. 
      unsigned long getErrorId() const 
         throw()
      { return errorId; };

         /**
          * Sets the error ID to the specified value. 
          * @param errId The identifier you want to associate with
          * this error.
          */
      Exception& setErrorId(const unsigned long& errId)
         throw()
      { errorId = errId; return *this; };

         /**
          * Adds the location information to the exception object. The
          * library captures this information when an exception is
          * thrown or rethrown. An array of ExceptionLocation objects
          * is stored in the exception object.
          *
          * @param location An IExceptionLocation object containing
          * the following:
          * \li          Function name 
          * \li          File name 
          * \li          Line number where the function is called 
          */
      Exception& addLocation(const ExceptionLocation& location) 
         throw();

         /**
          * Returns the ExceptionLocation object at the specified index. 
          * @param index If the index is not valid, a 0
          * pointer is returned. (well, not really since someone
          * changed all this bah)
          */
      const ExceptionLocation getLocation(const size_t& index=0) const
         throw();