QXmpp: QXmpp Namespace Reference

QXmpp Version: 1.14.3

Loading...
Searching...
No Matches
QXmpp Namespace Reference

## Namespaces
namespace | Uri

## Classes
struct | Success
struct | Cancelled
struct | TimeoutError
struct | Reply
struct | SendSuccess
struct | StunServer
| STUN server address. More...
struct | TurnServer
| TURN server address. More...
struct | AuthenticationError
struct | BindError

## Concepts
concept | IsTask

## Typedefs
template<typename T = Success>
using | Result = std::variant<T, QXmppError>
using | SendResult = std::variant<SendSuccess, QXmppError>
template<IsTask T>
using | TaskValueType = typename Private::IsTaskHelper<T>::Type

## 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 | JingleErrorCondition { OutOfOrder , TieBreak , UnknownSession , UnsupportedInfo }
enum class | StreamError { BadFormat , BadNamespacePrefix , Conflict , ConnectionTimeout , HostGone , HostUnknown , ImproperAddressing , InternalServerError , InvalidFrom , InvalidId , 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
template<typename T>
const QXmppError & | getError (const Result< T > &r)
template<typename T>
QXmppError & | getError (Result< T > &r)
template<typename T>
QXmppError | getError (Result< T > &&r)
constexpr bool | operator& (SceMode mode1, SceMode mode2)
template<typename T>
bool | hasValue (const Result< T > &r)
template<typename T>
bool | hasError (const Result< T > &r)
template<typename T>
const T & | getValue (const Result< T > &r)
template<typename T>
T & | getValue (Result< T > &r)
template<typename T>
T | getValue (Result< T > &&r)
QXMPP_EXPORT QString | generateSequentialStanzaId ()
template<typename T>
bool | isIqElement (const QDomElement &el)
| Checks whether a QDomElement is an IQ stanza of a specific type T.
template<Private::HasXmlTag T>
bool | isElement (const QDomElement &el)
| Checks whether an XML element has the correct tag name and namespace URI for type T.
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

## ◆ Result

template<typename T = Success>

using QXmpp::Result = std::variant<T, QXmppError>

Generic result type offering value or QXmppError

T defaults to QXmpp::Success since QXmpp 1.13.

Since
  QXmpp 1.12

## ◆ SendResult

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

A variant containing either a SendSuccess object or a QXmppError.

The QXmppError will likely contain a SendError.

## ◆ TaskValueType

template<IsTask T>

using QXmpp::TaskValueType = typename Private::IsTaskHelper<T>::Type

Returns the type T of a QXmppTask<T>

Since
  QXmpp 1.14

## 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

## ◆ JingleErrorCondition

enum class QXmpp::JingleErrorCondition
| strong

XEP-0166: Jingle-specific error condition, used in QXmppStanza::Error.

Since
  QXmpp 1.14

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

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

## ◆ generateSequentialStanzaId()

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.

Since
  QXmpp 1.11

## ◆ getError() [1/3]

template<typename T>

const QXmppError & QXmpp::getError | ( | const Result< T > & | r | ) |

Returns the error of a result or throws

Since
  QXmpp 1.13

## ◆ getError() [2/3]

template<typename T>

QXmppError QXmpp::getError | ( | Result< T > && | r | ) |

Returns the error of a result or throws

Since
  QXmpp 1.13

## ◆ getError() [3/3]

template<typename T>

QXmppError & QXmpp::getError | ( | Result< T > & | r | ) |

Returns the error of a result or throws

Since
  QXmpp 1.13

## ◆ getValue() [1/3]

template<typename T>

const T & QXmpp::getValue | ( | const Result< T > & | r | ) |

Returns the value of a result or throws

Since
  QXmpp 1.13

## ◆ getValue() [2/3]

template<typename T>

T QXmpp::getValue | ( | Result< T > && | r | ) |

Returns the value of a result or throws

Since
  QXmpp 1.13

## ◆ getValue() [3/3]

template<typename T>

T & QXmpp::getValue | ( | Result< T > & | r | ) |

Returns the value of a result or throws

Since
  QXmpp 1.13

## ◆ 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'.");
}
});
QXmppIq::Set
@ Set
Set request.
Definition QXmppIq.h:29
QXmppIq::Get
@ Get
Get request.
Definition QXmppIq.h:28
QXmppIq::type
QXmppIq::Type type() const
Definition QXmppIq.cpp:60
QXmppStanza::Error
The Error class represents a stanza error.
Definition QXmppStanza.h:112
QXmppStanza::Error::Cancel
@ Cancel
The error is not temporary.
Definition QXmppStanza.h:120
QXmppStanza::Error::BadRequest
@ BadRequest
The request does not contain a valid schema.
Definition QXmppStanza.h:130
QXmppVersionIq
The QXmppVersionIq class represents an IQ for conveying a software version as defined by XEP-0092: So...
Definition QXmppVersionIq.h:17
QXmppVersionIq::setVersion
void setVersion(const QString &version)
Sets the software version.
Definition QXmppVersionIq.cpp:48
QXmppVersionIq::setName
void setName(const QString &name)
Sets the name of the software.
Definition QXmppVersionIq.cpp:24

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

## ◆ hasError()

template<typename T>

bool QXmpp::hasError | ( | const Result< T > & | r | ) |

Returns whether a result contains an error

Since
  QXmpp 1.13

## ◆ hasValue()

template<typename T>

bool QXmpp::hasValue | ( | const Result< T > & | r | ) |

Returns whether a result contains the expected value

Since
  QXmpp 1.13

## ◆ operator&()

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