QXmpp Namespace Reference

Classes
struct	Cancelled
struct	SendSuccess
struct	Success

Typedefs
using	SendResult = std::variant< SendSuccess, QXmppError >

Enumerations
enum	EncryptionMethod {   NoEncryption , UnknownEncryption , Otr , LegacyOpenPgp ,   Ox , Omemo0 , Omemo1 , Omemo2 ,   OTR = Otr , LegacyOpenPGP = LegacyOpenPgp , OX = Ox , OMEMO = Omemo0 }
enum	SceMode : uint8_t { SceAll , ScePublic , SceSensitive }
enum	Cipher { Aes128GcmNoPad , Aes256GcmNoPad , Aes256CbcPkcs7 }
enum class	HashAlgorithm : uint32_t {   Unknown , Md2 , Md5 , Shake128 ,   Shake256 , Sha1 , Sha224 , Sha256 ,   Sha384 , Sha512 , Sha3_256 , Sha3_512 ,   Blake2b_256 , Blake2b_512 }
enum class	SendError : uint8_t { SocketWriteError , Disconnected , EncryptionError }
enum class	TrustLevel {   Undecided = 1 , AutomaticallyDistrusted = 2 , ManuallyDistrusted = 4 , AutomaticallyTrusted = 8 ,   ManuallyTrusted = 16 , Authenticated = 32 }
enum	TrustSecurityPolicy { NoSecurityPolicy , Toakafa }

Functions
constexpr bool	operator& (SceMode mode1, SceMode mode2)
template<typename... IqTypes, typename Handler >
bool	handleIqRequests (const QDomElement &element, const std::optional< QXmppE2eeMetadata > &e2eeMetadata, QXmppClient *client, Handler handler)
template<typename... IqTypes, typename Handler >
bool	handleIqRequests (const QDomElement &element, QXmppClient *client, Handler handler)

Detailed Description

Contains global functions and enumerations.

Since

QXmpp 1.5

Typedef Documentation

SendResult

using QXmpp::SendResult = typedef std::variant<SendSuccess, QXmppError>

A variant containing either a SendSuccess object or a QXmppError.

The QXmppError will likely contain a SendError.

Enumeration Type Documentation

Cipher

enum QXmpp::Cipher

Cipher for encrypting data streams and files.

Since

QXmpp 1.5

EncryptionMethod

enum QXmpp::EncryptionMethod

This enum describes different end-to-end encryption methods. These can be used to mark a stanza as encrypted or decrypted with a specific algorithm (e.g., for XEP-0380: Explicit Message Encryption).

Since

QXmpp 1.5

Enumerator
NoEncryption	No encryption.
UnknownEncryption	Unknown encryption.
Otr	XEP-0364: Current Off-the-Record Messaging Usage
LegacyOpenPgp	XEP-0027: Current Jabber OpenPGP Usage
Ox	XEP-0373: OpenPGP for XMPP
Omemo0	XEP-0384: OMEMO Encryption
Omemo1	XEP-0384: OMEMO Encryption since version 0.4
Omemo2	XEP-0384: OMEMO Encryption since version 0.8
OTR	XEP-0364: Current Off-the-Record Messaging Usage Deprecated: This enum is deprecated since QXmpp 1.5. Use QXmpp::Otr instead.
LegacyOpenPGP	XEP-0027: Current Jabber OpenPGP Usage Deprecated: This enum is deprecated since QXmpp 1.5. Use QXmpp::LegacyOpenPgp instead.
OX	XEP-0373: OpenPGP for XMPP Deprecated: This enum is deprecated since QXmpp 1.5. Use QXmpp::Ox instead.
OMEMO	XEP-0384: OMEMO Encryption Deprecated: This enum is deprecated since QXmpp 1.5. Use QXmpp::Omemo0 instead.

HashAlgorithm

enum class QXmpp::HashAlgorithm : uint32_t

strong

One of the hash algorithms specified by the IANA registry or XEP-0300: Use of Cryptographic Hash Functions in XMPP.

Since

QXmpp 1.5

SceMode

enum QXmpp::SceMode : uint8_t

Parsing/serialization mode when using Stanza Content Encryption.

See also

XEP-0420: Stanza Content Encryption

Since

QXmpp 1.5

Enumerator
SceAll	Processes all known elements.
ScePublic	Only processes 'public' elements (e.g. needed for routing).
SceSensitive	Only processes sensitive elements that should be encrypted.

SendError

enum class QXmpp::SendError : uint8_t

strong

Describes the type of a packet sending error.

Since

QXmpp 1.5

Enumerator
SocketWriteError	The packet was written to the socket with no success (only happens when Stream Management is disabled).
Disconnected	The packet couldn't be sent because the connection hasn't been (re)established.
EncryptionError	The packet couldn't be sent because prior encryption failed.

TrustLevel

enum class QXmpp::TrustLevel

strong

Trust level of public long-term keys used by end-to-end encryption protocols

Since

QXmpp 1.5

Enumerator
Undecided	The key's trust is not decided.
AutomaticallyDistrusted	The key is automatically distrusted (e.g., by the security policy TOAKAFA). See also SecurityPolicy
ManuallyDistrusted	The key is manually distrusted (e.g., by clicking a button or XEP-0450: Automatic Trust Management (ATM)).
AutomaticallyTrusted	The key is automatically trusted (e.g., by the client for all keys of a bare JID until one of it is authenticated).
ManuallyTrusted	The key is manually trusted (e.g., by clicking a button).
Authenticated	The key is authenticated (e.g., by QR code scanning or XEP-0450: Automatic Trust Management (ATM)).

TrustSecurityPolicy

enum QXmpp::TrustSecurityPolicy

Security policy to decide which public long-term keys are used for encryption because they are trusted

Since

QXmpp 1.5

Enumerator
NoSecurityPolicy	New keys must be trusted manually.
Toakafa	New keys are trusted automatically until the first authentication but automatically distrusted afterwards. See also XEP-0450: Automatic Trust Management (ATM)

Function Documentation

handleIqRequests() [1/2]

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().

Parameters

element	The DOM element that might contain an IQ.
e2eeMetadata	The end-to-end encryption metadata that is used to encrypt the response correctly and to be set on the parsed IQ.
client	The client that should be used to send the response.
handler	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.

Since

QXmpp 1.5

handleIqRequests() [2/2]

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.

Parameters

element	The DOM element that might contain an IQ.
client	The client that should be used to send the response.
handler	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.

Since

QXmpp 1.5

operator&()

constexpr bool QXmpp::operator& ( SceMode  mode1, SceMode  mode2  )

inlineconstexpr

Checks whether a mode is enabled.

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

Since

QXmpp 1.5