QXmppCallManager Class
The QXmppCallManager class provides support for making and receiving voice and video calls using XEP-0166: Jingle. More...
| Header: | #include <QXmppCallManager.h> |
| Inherits: | QXmppClientExtension |
- List of all members, including inherited members
- QXmppCallManager is part of Managers.
Public Types
| enum class | Media { Audio, AudioVideo } |
Public Functions
| QXmppCallManager() | |
| virtual | ~QXmppCallManager() override |
(since QXmpp 1.14, previously this function had a different signature.) std::unique_ptr<QXmppCall> | call(const QString &jid, QXmppCallManager::Media media = Media::Audio, const QString &proposedSid = {}) |
(since QXmpp 1.11) bool | dtlsRequired() const |
(since QXmpp 1.11) void | setDtlsRequired(bool dtlsRequired) |
(since QXmpp 1.14) void | setFallbackStunServers(const QList<QXmpp::StunServer> &servers) |
(since QXmpp 1.14) void | setFallbackTurnServer(const std::optional<QXmpp::TurnServer> &server) |
Signals
(since QXmpp 1.14, previously this signal had a different signature.) void | callReceived(std::unique_ptr<QXmppCall> &call) |
Detailed Description
Session initiation is performed as described by XEP-0166: Jingle, XEP-0167: Jingle RTP Sessions and XEP-0176: Jingle ICE-UDP Transport Method.
The data stream is connected using Interactive Connectivity Establishment (RFC 5245) and data is transferred using Real Time Protocol (RFC 3550) packets.
To make use of this manager, you need to instantiate it and load it into the QXmppClient instance as follows:
auto *client = new QXmppClient();
auto *callManager = client->addNewExtension<QXmppCallManager>();Call interaction
Incoming calls are exposed via the callReceived() signal. You can take ownership of the call by moving the unique_ptr, otherwise the call manager will decline and delete the call. You can accept or reject (hang up) the call.
Outgoing calls are created using call().
In both cases you are responsible for taking ownership of the call. Note that QXmppCalls in another state than finished require the QXmppCallManager to be active, though. You must not delete the QXmppCallManager until all QXmppCalls are in finished state.
XEP-0320: Use of DTLS-SRTP in Jingle Sessions
DTLS-SRTP allows to encrypt peer-to-peer calls. Internally, a TLS handshake is done to negotiate keys for SRTP (Secure RTP). By default DTLS is not enforced, this can be done using setDtlsRequired(), though.
DTLS-SRTP by default exchanges the fingerprint via unencrypted XMPP packets. This means that the XMPP server could potentially replace the fingerprint or prevent the clients from using DTLS at all. However, the actual media connection is typically peer-to-peer, so the XMPP server does not have access to the transmitted data.
Support for DTLS-SRTP is available since QXmpp 1.11.
Warning: THIS API IS NOT FINALIZED YET
Member Type Documentation
enum class QXmppCallManager::Media
Media type for starting a call.
| Constant | Value | Description |
|---|---|---|
QXmppCallManager::Media::Audio | 0 | Only contains an audio stream. |
QXmppCallManager::Media::AudioVideo | 1 | Contains audio and video streams. |
Member Function Documentation
QXmppCallManager::QXmppCallManager()
Constructs a QXmppCallManager object to handle incoming and outgoing Voice-Over-IP calls.
[override virtual noexcept] QXmppCallManager::~QXmppCallManager()
Destroys the QXmppCallManager object.
[since QXmpp 1.14, previously this function had a different signature.] std::unique_ptr<QXmppCall> QXmppCallManager::call(const QString &jid, QXmppCallManager::Media media = Media::Audio, const QString &proposedSid = {})
Initiates a new outgoing call to the specified recipient.
jid is the Full-JID of the recipient. media specifies whether to initiate with audio or audio and video. proposedSid is the session ID of the call. If empty, a new session ID will be generated. Must be unique.
This function was introduced in QXmpp 1.14, previously this function had a different signature..
[signal, since QXmpp 1.14, previously this signal had a different signature.] void QXmppCallManager::callReceived(std::unique_ptr<QXmppCall> &call)
This signal is emitted when an incoming call is received.
You can take over ownership of the call by moving out the unique pointer. However, this is only possible for one slot connected to this signal, all other slots after that will receive a nullptr.
std::vector<std::unique_ptr<QXmppCall>> myActiveCalls;
connect(manager, &QXmppCallManager::callReceived, this, [&](std::unique_ptr<QXmppCall> &call) {
// take over ownership
myActiveCalls.push_back(std::move(call));
// call is now nullptr
});Note that you do not need to continue to use a unique pointer for memory management, you can also use QObject-parent ownership or another ownership model.
Note: If you do not take ownership of the call, the call manager will automatically decline the call.
Note: Incoming calls need to be accepted or rejected using QXmppCall::accept() or QXmppCall::hangUp().
This function was introduced in QXmpp 1.14, previously this signal had a different signature..
[since QXmpp 1.11] bool QXmppCallManager::dtlsRequired() const
Returns whether the call manager requires encryption using XEP-0320: Use of DTLS-SRTP in Jingle Sessions for all calls.
This function was introduced in QXmpp 1.11.
See also setDtlsRequired().
[since QXmpp 1.11] void QXmppCallManager::setDtlsRequired(bool dtlsRequired)
Sets whether the call manager requires encryption using XEP-0320: Use of DTLS-SRTP in Jingle Sessions for all calls.
dtlsRequired.
This function was introduced in QXmpp 1.11.
See also dtlsRequired().
[since QXmpp 1.14] void QXmppCallManager::setFallbackStunServers(const QList<QXmpp::StunServer> &servers)
Sets STUN servers that are used as a fallback, additionally to the ones provided by the XMPP server via XEP-0215: External Service Discovery.
STUN is used to determine server-reflexive addresses and ports.
servers.
This function was introduced in QXmpp 1.14.
[since QXmpp 1.14] void QXmppCallManager::setFallbackTurnServer(const std::optional<QXmpp::TurnServer> &server)
Set a TURN server that is used as a fallback, if the XMPP server does not provide any TURN server via XEP-0215: External Service Discovery.
TURN is used to relay packets in double-NAT configurations.
server.
This function was introduced in QXmpp 1.14.