1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include <QMutex>

    43 

    44 #include "private/qobject_p.h"

    45 #include "qabstractmessagehandler.h"

    46 

    47 QT_BEGIN_NAMESPACE

    48 

    49 class QAbstractMessageHandlerPrivate : public QObjectPrivate

    50 {

    51 public:

    52     QMutex mutex;

    53 };

    54 

    55 /*!

    56   \class QAbstractMessageHandler

    57   \threadsafe

    58   \since 4.4

    59   \ingroup xml-tools

    60 

    61   \brief The QAbstractMessageHandler class provides a callback interface for handling messages.

    62 

    63   QAbstractMessageHandler is an abstract base class that provides a

    64   callback interface for handling messages. For example, class

    65   QXmlQuery parses and runs an XQuery. When it detects a compile

    66   or runtime error, it generates an appropriate error message,

    67   but rather than output the message itself, it passes the message to

    68   the message() function of its QAbstractMessageHandler.

    69   See QXmlQuery::setMessageHandler().

    70 

    71   You create a message handler by subclassing QAbstractMessageHandler

    72   and implementing handleMessage(). You then pass a pointer to an

    73   instance of your subclass to any classes that must generate

    74   messages. The messages are sent to the message handler via the

    75   message() function, which forwards them to your handleMessge().

    76   The effect is to serialize the handling of all messages, which

    77   means your QAbstractMessageHandler subclass is thread safe.

    78 

    79   A single instance of QAbstractMessageHandler can be called on to

    80   handle messages from multiple sources. Hence, the content of a

    81   message, which is the \e description parameter passed to message()

    82   and handleMessage(), must be interpreted in light of the context

    83   that required the message to be sent. That context is specified by

    84   the \e identifier and \e sourceLocation parameters to message()

    85   handleMessage().

    86  */

    87 

    88 /*!

    89   Constructs a QAbstractMessageHandler. The \a parent is passed

    90   to the QObject base class constructor.

    91  */

    92 QAbstractMessageHandler::QAbstractMessageHandler(QObject *parent) : QObject(*new QAbstractMessageHandlerPrivate(), parent)

    93 {

    94 }

    95 

    96 /*!

    97   Destructs this QAbstractMessageHandler.

    98  */

    99 QAbstractMessageHandler::~QAbstractMessageHandler()

   100 {

   101 }

   102 

   103 /*!

   104   Sends a message to this message handler. \a type is the kind of

   105   message being sent. \a description is the message content. The \a

   106   identifier is a URI that identifies the message and is the key to

   107   interpreting the other arguments.

   108 

   109   Typically, this class is used for reporting errors, as is the case

   110   for QXmlQuery, which uses a QAbstractMessageHandler to report

   111   compile and runtime XQuery errors. Hence, using a QUrl as the

   112   message \a identifier is was inspired by the explanation of \l{error

   113   handling in the XQuery language}. Because the \a identifier is

   114   composed of a namespace URI and a local part, identifiers with the

   115   same local part are unique.  The caller is responsible for ensuring

   116   that \a identifier is either a valid QUrl or a default constructed

   117   QUrl.

   118 

   119   \a sourceLocation identifies a location in a resource (i.e., file or

   120   document) where the need for reporting a message was detected.

   121 

   122   This function unconditionally calls handleMessage(), passing all

   123   its parameters unmodified.

   124 

   125   \sa {http://www.w3.org/TR/xquery/#errors}

   126  */

   127 void QAbstractMessageHandler::message(QtMsgType type,

   128                                       const QString &description,

   129                                       const QUrl &identifier,

   130                                       const QSourceLocation &sourceLocation)

   131 {

   132     Q_D(QAbstractMessageHandler);

   133     QMutexLocker(&d->mutex);

   134     handleMessage(type, description, identifier, sourceLocation);

   135 }

   136 

   137 /*!

   138   \fn void QAbstractMessageHandler::handleMessage(QtMsgType type,

   139                                                   const QString &description,

   140                                                   const QUrl &identifier = QUrl(),

   141                                                   const QSourceLocation &sourceLocation = QSourceLocation()) = 0

   142 

   143   This function must be implemented by the sub-class. message() will

   144   call this function, passing in its parameters, \a type,

   145   \a description, \a identifier and \a sourceLocation unmodified.

   146  */

   147 

   148 QT_END_NAMESPACE

   149