libxml++/exceptions/exception.h

   1 /* exception.h
   2  *
   3  * Copyright (C) 2002 The libxml++ development team
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the Free
  17  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19
  20 #ifndef __LIBXMLPP_EXCEPTION_H
  21 #define __LIBXMLPP_EXCEPTION_H
  22
  23 #include <exception>
  24 #include <cstdarg> // va_list
  25 #include <glibmm/ustring.h>
  26
  27 #include <libxml++config.h>
  28
  29 extern "C" {
  30   struct _xmlError;
  31   struct _xmlParserCtxt;
  32 }
  33
  34 namespace xmlpp
  35 {
  36
  37 /** Base class for all xmlpp exceptions.
  38  */
  39 class LIBXMLPP_API exception : public std::exception
  40 {
  41 public:
  42   explicit exception(const Glib::ustring& message);
  43   ~exception() noexcept override;
  44
  45   const char* what() const noexcept override;
  46
  47   virtual void raise() const;
  48   virtual exception* clone() const;
  49
  50 private:
  51   Glib::ustring message_;
  52 };
  53
  54 /** Format an _xmlError struct into a text string, suitable for printing.
  55  *
  56  * @newin{2,36}
  57  *
  58  * @param error Pointer to an _xmlError struct or <tt>nullptr</tt>.
  59  *              If <tt>nullptr</tt>, the error returned by xmlGetLastError() is used.
  60  * @returns A formatted text string. If the error struct does not contain an
  61  *          error (error->code == XML_ERR_OK), an empty string is returned.
  62  */
  63 Glib::ustring format_xml_error(const _xmlError* error = nullptr);
  64
  65 /** Format a parser error into a text string, suitable for printing.
  66  *
  67  * @newin{2,36}
  68  *
  69  * @param parser_context Pointer to an _xmlParserCtxt struct.
  70  * @returns A formatted text string. If the parser context does not contain an
  71  *          error (parser_context->lastError.code == XML_ERR_OK), an empty
  72  *          string is returned.
  73  */
  74 Glib::ustring format_xml_parser_error(const _xmlParserCtxt* parser_context);
  75
  76 /** Format a message from a function with C-style variadic parameters.
  77  *
  78  * Helper function that formats a message supplied in the form of a printf-style
  79  * format specification and zero or more ... parameters.
  80  *
  81  * @code
  82  * // Typical call:
  83  * void f(const char* fmt, ...)
  84  * {
  85  *   va_list args;
  86  *   va_start(args, fmt);
  87  *   Glib::ustring msg = xmlpp::format_printf_message(fmt, args);
  88  *   va_end(args);
  89  *   // ...
  90  * }
  91  * @endcode
  92  *
  93  * @newin{3,0}
  94  */
  95 Glib::ustring format_printf_message(const char* fmt, va_list args);
  96
  97 } // namespace xmlpp
  98
  99 #endif // __LIBXMLPP_EXCEPTION_H