1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
44 #include "private/qobject_p.h"
45 #include "qabstractmessagehandler.h"
49 class QAbstractMessageHandlerPrivate : public QObjectPrivate
56 \class QAbstractMessageHandler
60 \inmodule QtXmlPatterns
61 \brief The QAbstractMessageHandler class provides a callback interface for handling messages.
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().
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.
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()
89 Constructs a QAbstractMessageHandler. The \a parent is passed
90 to the QObject base class constructor.
92 QAbstractMessageHandler::QAbstractMessageHandler(QObject *parent) : QObject(*new QAbstractMessageHandlerPrivate(), parent)
97 Destructs this QAbstractMessageHandler.
99 QAbstractMessageHandler::~QAbstractMessageHandler()
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.
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
119 \a sourceLocation identifies a location in a resource (i.e., file or
120 document) where the need for reporting a message was detected.
122 This function unconditionally calls handleMessage(), passing all
123 its parameters unmodified.
125 \sa {http://www.w3.org/TR/xquery/#errors}
127 void QAbstractMessageHandler::message(QtMsgType type,
128 const QString &description,
129 const QUrl &identifier,
130 const QSourceLocation &sourceLocation)
132 Q_D(QAbstractMessageHandler);
133 QMutexLocker(&d->mutex);
134 handleMessage(type, description, identifier, sourceLocation);
138 \fn void QAbstractMessageHandler::handleMessage(QtMsgType type,
139 const QString &description,
140 const QUrl &identifier = QUrl(),
141 const QSourceLocation &sourceLocation = QSourceLocation()) = 0
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.