1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
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.