QXmpp Version: 1.7.0
Classes | Typedefs | Enumerations | Functions
QXmpp Namespace Reference

Classes

struct  AuthenticationError
 
struct  BindError
 
struct  Cancelled
 
struct  SendSuccess
 
struct  Success
 
struct  TimeoutError
 

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  StreamError {
  BadFormat , BadNamespacePrefix , Conflict , ConnectionTimeout ,
  HostGone , HostUnknown , ImproperAddressing , InternalServerError ,
  InvalidFrom , InvalidNamespace , InvalidXml , NotAuthorized ,
  NotWellFormed , PolicyViolation , RemoteConnectionFailed , Reset ,
  ResourceConstraint , RestrictedXml , SystemShutdown , UndefinedCondition ,
  UnsupportedEncoding , UnsupportedFeature , UnsupportedStanzaType , UnsupportedVersion
}
 
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

Cipher for encrypting data streams and files.

Since
QXmpp 1.5

◆ 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.

◆ StreamError

enum class QXmpp::StreamError
strong

All XMPP top-level stream errors

Since
QXmpp 1.7

◆ 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

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'.");
}
});
@ Set
Set request.
Definition: QXmppIq.h:29
@ Get
Get request.
Definition: QXmppIq.h:28
QXmppIq::Type type() const
Definition: QXmppIq.cpp:53
The QXmppVersionIq class represents an IQ for conveying a software version as defined by XEP-0092: So...
Definition: QXmppVersionIq.h:16

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) {
// ...
}
});
Represents the XMPP vCard.
Definition: QXmppVCardIq.h:210

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