.. oe:namespace:: OESystem



.. meta::
   :keywords: OEErrorHandler, ErrorHandler


.. _OESystem_OEErrorHandler:

.. oe:class:: OEErrorHandler

   .. oe:api::

      class OEErrorHandler

   This class represents `OEErrorHandler`.

   The :ref:`OEErrorHandler <OESystem_OEErrorHandler>` class is used to define the behavior of the
   :oe:constns:`OESystem::OEThrow` error handler. All diagnostic output, including
   error, warning and informational messages, generated by the *OpenEye*
   libraries are emitted via :oe:constns:`OESystem::OEThrow`.
   The :ref:`OEErrorHandler <OESystem_OEErrorHandler>` class defines
   how these messages are emitted, but also how the user can redirect
   and/or intercept these messages.

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEErrorHandler()

      .. oe:language:: python

         .. oe:api:: python

            OEErrorHandler() -> OEErrorHandler

      Default constructor that creates an
      :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` that it owns and writes output to stderr.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEErrorHandler(OEErrorHandler& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEErrorHandler(rhs: OEErrorHandler) -> OEErrorHandler

      Copy constructor.

      .. note::

         :oe:meth:`OESystem::OEErrorHandlerImplBase::CreateCopy` will
         only be called by the copy constructor if the right-hand-side
         owns the :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>`. This is
         why the right-hand-side argument is non-const.

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEErrorHandler &operator=(OEErrorHandler &rhs)

      Assignment operator.

      .. note::

         :oe:meth:`OESystem::OEErrorHandlerImplBase::CreateCopy` will
         only be called by ``operator=`` if the right-hand-side
         owns the :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>`. This is
         why the right-hand-side argument is non-const.

   .. oe:method:: Clear

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Reset all the counts returned by
      :oe:meth:`OESystem::OEErrorHandler::Count` to zero.

   .. oe:method:: Count

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int Count(unsigned int level = 0) const

      .. oe:language:: python

         .. oe:api:: python

            Count(level: int = 0) -> int

      Returns the number of messages already written at the given
      ``level``. The constant ``level`` should be drawn from the
      :oe:constns:`OESystem::OEErrorLevel` namespace. If ``level`` is
      zero, the default, the sum of all error level counts is returned.

   .. oe:method:: Debug

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Debug(const std::string &)
            void Debug(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Debug(arg2: str) -> None

      Writes debugging messages to the
      :ref:`OEErrorHandler <OESystem_OEErrorHandler>`. By default, these message
      will not appear, :oe:meth:`OESystem::OEErrorHandler::SetLevel`
      should be set to :oe:const:`OESystem::OEErrorLevel::Debug` or
      below to make them appear.

   .. oe:method:: Error

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Error(const std::string &)
            void Error(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Error(arg2: str) -> None

      Writes error messages to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.
      Depending upon the value of the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`'s
      'strict' property (see :oe:meth:`OESystem::OEErrorHandler::GetStrict` and
      :oe:meth:`OESystem::OEErrorHandler::SetStrict`), these diagnostics
      are forwarded to either the :oe:meth:`OESystem::OEErrorHandler::Fatal` or
      :oe:meth:`OESystem::OEErrorHandler::Warning` methods.

   .. oe:method:: Fatal

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Fatal(const std::string &)
            void Fatal(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Fatal(arg2: str) -> None

      Writes fatal error messages to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.

   .. oe:method:: GetHandlerImpl

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEErrorHandlerImplBase* GetHandlerImpl()

      .. oe:language:: python

         .. oe:api:: python

            GetHandlerImpl() -> OEErrorHandlerImplBase

      Returns the :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` error handler that
      is used to handle messages. The default error handler writes output to stderr.
      The error handler can be changed by calling the :oe:meth:`OESystem::OEErrorHandler::SetHandlerImpl` method.

   .. oe:method:: GetLevel

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetLevel() const

      .. oe:language:: python

         .. oe:api:: python

            GetLevel() -> int

      Returns a constant from the :oe:constns:`OESystem::OEErrorLevel`
      namespace indicating the current level of messages that should
      make it to the output stream. The default is
      :oe:const:`OESystem::OEErrorLevel::Default`, that will output messages of
      :oe:meth:`OESystem::OEErrorHandler::Info` or higher.

      .. warning::

         All threads, including the main thread, will start out at the
         :oe:const:`OESystem::OEErrorLevel::Default`
         level. :oe:meth:`OESystem::OEErrorHandler::SetLevel` will
         only change the level for the current thread.

   .. oe:method:: GetStrict

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool GetStrict() const

      .. oe:language:: python

         .. oe:api:: python

            GetStrict() -> bool

      Returns the 'strict' property of the
      :ref:`OEErrorHandler <OESystem_OEErrorHandler>`. When the :ref:`OEErrorHandler <OESystem_OEErrorHandler>` is
      strict, all error messages written via the
      :oe:meth:`OESystem::OEErrorHandler::Error` methods are treated as fatal,
      and handled like those passed to :oe:meth:`OESystem::OEErrorHandler::Fatal`.
      When the :ref:`OEErrorHandler <OESystem_OEErrorHandler>` is  not strict, error messages
      written via :oe:meth:`OESystem::OEErrorHandler::Error` are treated like
      those to :oe:meth:`OESystem::OEErrorHandler::Warning`.
      The strict property of an :ref:`OEErrorHandler <OESystem_OEErrorHandler>` can
      be set using the :oe:meth:`OESystem::OEErrorHandler::SetStrict` method.


   .. oe:method:: Info

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Info(const std::string &)
            void Info(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Info(arg2: str) -> None

      Writes an informational messages to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.


   .. oe:method:: Msg

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Msg(unsigned int level, const std::string &)
            void Msg(unsigned int level, const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Msg(level: int, arg3: str) -> None

      Write a message at any ``level``. The ``level`` constant should
      be drawn from the :oe:constns:`OESystem::OEErrorLevel` namespace.

   .. oe:method:: SetHandlerImpl

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetHandlerImpl(OEErrorHandlerImplBase* ptr, bool owned)

      .. oe:language:: python

         .. oe:api:: python

            SetHandlerImpl(ptr: OEErrorHandlerImplBase, owned: bool) -> None

      Use a different implementation of
      :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` to handle error
      messages. The ownership is determined by the ``owned`` flag,
      which is always ``false`` in any other language but C++.

      This method allows a user to completely redefine how the **OpenEye
      toolkits** handle error messages by declaring a new subclass of
      :ref:`OEErrorHandlerImplBase <OESystem_OEErrorHandlerImplBase>` and defining the
      :oe:meth:`OESystem::OEErrorHandlerImplBase::Msg` to have the
      desired behavior.

   .. oe:method:: SetLevel

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetLevel(unsigned int errLevel)

      .. oe:language:: python

         .. oe:api:: python

            SetLevel(errLevel: int) -> None

      Controls whether a message passed to the error handler will make
      it to the output stream. Values greater than ``errLevel`` from
      the :oe:constns:`OESystem::OEErrorLevel` namespace will be sent
      to the output stream.

      .. warning::

         This method will only change the error level for the current
         thread. Child threads will not inherit the parent thread
         error level.

   .. oe:method:: SetOutputStream

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetOutputStream(OEPlatform::oeostream& ofs)

      .. oe:language:: python

         .. oe:api:: python

            SetOutputStream(ofs: oeostream) -> None

      Sets the output stream (:ref:`oeostream <OEPlatform_oeostream>`)
      that diagnostic messages are written to when no custom
      error handler has been specified. By default, all messages are
      written to :oe:const:`OEPlatform::OEPlatform::oeerr`. This function can be used to
      redirect this output to either a file stream (:ref:`oeofstream <OEPlatform_oeofstream>`)
      or a string stream (:ref:`oeosstream <OEPlatform_oeosstream>`).

   .. oe:method:: SetStrict

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetStrict(bool strict)

      .. oe:language:: python

         .. oe:api:: python

            SetStrict(strict: bool) -> None

      Sets the 'strict' property of the
      :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.
      When the :ref:`OEErrorHandler <OESystem_OEErrorHandler>` is strict, all error
      messages written via the :oe:meth:`OESystem::OEErrorHandler::Error`
      methods are treated as fatal, and
      handled like those passed to :oe:meth:`OESystem::OEErrorHandler::Fatal`.
      When the :ref:`OEErrorHandler <OESystem_OEErrorHandler>` is
      not strict, error messages written via :oe:meth:`OESystem::OEErrorHandler::Error`
      are treated like those to :oe:meth:`OESystem::OEErrorHandler::Warning`.
      The strict property of an :ref:`OEErrorHandler <OESystem_OEErrorHandler>` can
      be retrieved by using the :oe:meth:`OESystem::OEErrorHandler::GetStrict`
      method.

   .. oe:method:: Usage

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Usage(const std::string &)
            void Usage(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Usage(arg2: str) -> None

      Writes usage (warning) messages to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.


   .. oe:method:: Verbose

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Verbose(const std::string &)
            void Verbose(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Verbose(arg2: str) -> None

      Writes messages with the
      :oe:const:`OESystem::OEErrorLevel::Verbose` error message level
      to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`. By default, these
      messages will not appear.


   .. oe:method:: Warning

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Warning(const std::string &)
            void Warning(const char* format, ...)

      .. oe:language:: python

         .. oe:api:: python

            Warning(arg2: str) -> None

      Writes warning messages to the :ref:`OEErrorHandler <OESystem_OEErrorHandler>`.

