QXmpp Namespace

Function Documentation

[since QXmpp 1.16] QString QXmpp::formatXmlForDebug(QStringView raw, bool indent = true, int indentWidth = 2, bool colorize = false)

Pretty-prints an XML fragment for debug display.

Reparses raw with QXmlStreamReader and re-emits it with line breaks and indentation. If colorize is true, ANSI 16-color escape sequences are inserted for terminal syntax highlighting (tags, attributes, text).

Tolerates XMPP stream fragments that are not standalone documents (such as inner child stanzas without their enclosing <stream:stream>). If the input cannot be parsed as XML at all, the original string is returned unchanged, so non-XML payloads (e.g. STUN packet dumps) pass through.

raw is the raw XML string. indent controls whether line breaks and indentation are added, and indentWidth sets the number of spaces per indentation level.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.11] QString QXmpp::generateSequentialStanzaId()

Generates a new sequential stanza id. The ID is locally unique, not globally unique (see QXmppUtils::generateStanzaUuid()).

This is used for all QXmppStanzas automatically.

This function was introduced in QXmpp 1.11.

[since QXmpp 1.13] template <typename T> const QXmppError &QXmpp::getError(const QXmpp::Result<T> &r)

Returns the error of a result r or throws.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> QXmppError &QXmpp::getError(QXmpp::Result<T> &r)

Returns the error of a result r or throws.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> QXmppError QXmpp::getError(QXmpp::Result<T> &&r)

Returns the error of a result r or throws.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> T &QXmpp::getValue(QXmpp::Result<T> &r)

Returns the value of a result or throws

r.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> T QXmpp::getValue(QXmpp::Result<T> &&r)

Returns the value of a result or throws

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> const T &QXmpp::getValue(const QXmpp::Result<T> &r)

Returns the value of a result or throws

r.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.5] template <typename... IqTypes, typename Handler> bool QXmpp::handleIqRequests(const QDomElement &element, QXmppClient *client, Handler handler)

Parses IQ requests, calls a handler and sends an IQ result or error.

It is the easiest to explain this function with a few examples.

auto handled = QXmpp::handleIqElements<QXmppVersionIq>(element, client, [](QXmppVersionIq iq) -> std::variant<QXmppVersionIq, QXmppStanza::Error> {
if (iq.type() == QXmppIq::Get) {
QXmppVersionIq response;
response.setName("MyApp");
response.setVersion("1.0");
// id, to and type of the IQ are set automatically.
return response;
} else if (iq.type() == QXmppIq::Set) {
return QXmppStanza::Error(QXmppStanza::Error::Cancel, QXmppStanza::Error::BadRequest, "IQ must be of type 'get'.");
}
});

It is also possible to handle multiple IQ types.

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(
element, client, [](std::variant<QXmppVersionIq, QXmppVCardIq> iqVariant) {
// ...
});

It doesn't need to be a std::variant, it's only important that the object is callable with all the IQ types. You can for example use different lambdas per type using this 'overloaded' helper.

template<class... Ts>
struct overloaded : Ts... {
using Ts::operator()...;
};
// explicit deduction guide (not needed as of C++20)
template<class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(
element, client, overloaded {
[](QXmppVersionIq iq) {
// ...
},
[](QXmppVCardIq iq) {
// ...
}
});

And another option is to an object with handleIq() functions.

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(element, client, this);
// will call this->handleIq(QXmppVersionIq) or this->handleIq(QXmppVCardIq)

The return type of the handler function can be: 1. an QXmppIq based type 2. a std::variant of QXmppIq based types (multiple are possible) and optionally also QXmppStanza::Error 3. a QXmppTask of 1. or 2.

You don't need to set the values for id or the to address on the IQ result because that's done automatically. Unless you want to return an error IQ you also don't need to set the IQ type.

If you return an QXmppStanza::Error, a normal QXmppIq with the error will be sent.

element is the DOM element that might contain an IQ. client is the client that should be used to send the response. handler is a function that can handle the IQ types from the template parameter or an object that has handleIq() functions for each of the IQ types.

Returns whether the IQ could be parsed, handled and a response was or will be sent.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.5] template <typename... IqTypes, typename Handler> bool QXmpp::handleIqRequests(const QDomElement &element, const std::optional<QXmppE2eeMetadata> &e2eeMetadata, QXmppClient *client, Handler handler)

Parses IQ requests, calls a handler and sends an IQ result or error.

It is the easiest to explain this function with a few examples.

auto handled = QXmpp::handleIqElements<QXmppVersionIq>(element, e2eeMetadata, client, [](QXmppVersionIq iq) -> std::variant<QXmppVersionIq, QXmppStanza::Error> {
if (iq.type() == QXmppIq::Get) {
QXmppVersionIq response;
response.setName("MyApp");
response.setVersion("1.0");
// id, to and type of the IQ are set automatically.
return response;
} else if (iq.type() == QXmppIq::Set) {
return QXmppStanza::Error(QXmppStanza::Error::Cancel, QXmppStanza::Error::BadRequest, "IQ must be of type 'get'.");
}
});

It is also possible to handle multiple IQ types.

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(
element, e2eeMetadata, client, [](std::variant<QXmppVersionIq, QXmppVCardIq> iqVariant) {
// ...
});

It doesn't need to be a std::variant, it's only important that the object is callable with all the IQ types. You can for example use different lambdas per type using this 'overloaded' helper.

template<class... Ts>
struct overloaded : Ts... {
using Ts::operator()...;
};
// explicit deduction guide (not needed as of C++20)
template<class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(
element, e2eeMetadata, client, overloaded {
[](QXmppVersionIq iq) {
// ...
},
[](QXmppVCardIq iq) {
// ...
}
});

And another option is to an object with handleIq() functions.

auto handled = QXmpp::handleIqElements<QXmppVersionIq, QXmppVCardIq>(element, e2eeMetadata, client, this);
// will call this->handleIq(QXmppVersionIq) or this->handleIq(QXmppVCardIq)

The return type of the handler function can be: 1. an QXmppIq based type 2. a std::variant of QXmppIq based types (multiple are possible) and optionally also QXmppStanza::Error 3. a QXmppTask of 1. or 2.

You don't need to set the values for id or the to address on the IQ result because that's done automatically. Unless you want to return an error IQ you also don't need to set the IQ type.

If you return an QXmppStanza::Error, a normal QXmppIq with the error will be sent.

The provided optional QXmppE2eeMetadata is set on the parsed IQ and used to correctly encrypt the IQ response using QXmppClient::reply().

element is the DOM element that might contain an IQ. e2eeMetadata is the end-to-end encryption metadata that is used to encrypt the response correctly and to be set on the parsed IQ. client is the client that should be used to send the response. handler is a function that can handle the IQ types from the template parameter or an object that has handleIq() functions for each of the IQ types.

Returns whether the IQ could be parsed, handled and a response was or will be sent.

This function was introduced in QXmpp 1.5.

[since QXmpp 1.13] template <typename T> bool QXmpp::hasError(const QXmpp::Result<T> &r)

Returns whether a result contains an error

r.

This function was introduced in QXmpp 1.13.

[since QXmpp 1.13] template <typename T> bool QXmpp::hasValue(const QXmpp::Result<T> &r)

Returns whether a result contains the expected value

r.

This function was introduced in QXmpp 1.13.

template <HasXmlTag T> bool QXmpp::isElement(const QDomElement &el)

Returns true if an XML element has the correct tag name and namespace URI for type T.

el.

template <typename T> bool QXmpp::isIqElement(const QDomElement &el)

Returns true if a QDomElement is an IQ stanza of a specific type T.

el.

[constexpr, since QXmpp 1.5] bool QXmpp::operator&(QXmpp::SceMode mode1, QXmpp::SceMode mode2)

Returns true if a mode is enabled in both mode1 and mode2.

When an SceMode is given you can use this to check whether Public or Private elements are enabled.

This function was introduced in QXmpp 1.5.