QXmpp: QXmppCallManager Class Reference

QXmpp Version: 1.14.4

Loading...
Searching...
No Matches
QXmppCallManager Class Reference
Managers

The QXmppCallManager class provides support for making and receiving voice calls. More...

Inheritance diagram for QXmppCallManager:

## Public Types
enum class | Media { Audio , AudioVideo }
| Media type for starting a call. More...

## Public Member Functions
| QXmppCallManager ()
| ~QXmppCallManager () override
void | setFallbackStunServers (const QList< QXmpp::StunServer > &)
void | setFallbackTurnServer (const std::optional< QXmpp::TurnServer > &)
bool | dtlsRequired () const
void | setDtlsRequired (bool)
Q_SIGNAL void | callReceived (std::unique_ptr< QXmppCall > &call)
std::unique_ptr< QXmppCall > | call (const QString &jid, Media media=Media::Audio, const QString &proposedSid={})
Public Member Functions inherited from QXmppClientExtension
| QXmppClientExtension ()
virtual QStringList | discoveryFeatures () const
virtual QList< QXmppDiscoIdentity > | discoveryIdentities () const
virtual bool | handleStanza (const QDomElement &stanza)
| You need to implement this method to process incoming XMPP stanzas.
virtual bool | handleStanza (const QDomElement &stanza, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
| You need to implement this method to process incoming XMPP stanzas.
Public Member Functions inherited from QXmppLoggable
| QXmppLoggable (QObject *parent=nullptr)
Q_SIGNAL void | setGauge (const QString &gauge, double value)
| Sets the given gauge to value.
Q_SIGNAL void | logMessage (QXmppLogger::MessageType type, const QString &msg)
| This signal is emitted to send logging messages.
Q_SIGNAL void | updateCounter (const QString &counter, qint64 amount=1)
| Updates the given counter by amount.

## Friends
class | QXmppCall
class | QXmppCallPrivate
class | QXmppCallManagerPrivate
class | tst_QXmppCallManager

## Additional Inherited Members
Protected Member Functions inherited from QXmppClientExtension
QXmppClient * | client () const
virtual void | setClient (QXmppClient *client)
virtual void | onRegistered (QXmppClient *client)
virtual void | onUnregistered (QXmppClient *client)
void | injectIq (const QDomElement &element, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
bool | injectMessage (QXmppMessage &&message)
Protected Member Functions inherited from QXmppLoggable
void | debug (const QString &message)
| Logs a debugging message.
void | info (const QString &message)
| Logs an informational message.
void | warning (const QString &message)
| Logs a warning message.
void | logReceived (const QString &message)
| Logs a received packet.
void | logSent (const QString &message)
| Logs a sent packet.

## Detailed Description

The QXmppCallManager class provides support for making and receiving voice calls.

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>();
QXmppCallManager::QXmppCallManager
QXmppCallManager()
Definition QXmppCallManager.cpp:283
QXmppClientExtension::client
QXmppClient * client() const
Definition QXmppClientExtension.cpp:57

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

## ◆ Media

enum class QXmppCallManager::Media
| strong

Media type for starting a call.

Enumerator
AudioVideo | only contains an audio stream

## Constructor & Destructor Documentation

## ◆ QXmppCallManager()

QXmppCallManager::QXmppCallManager | ( |  | ) |

Constructs a QXmppCallManager object to handle incoming and outgoing Voice-Over-IP calls.

## ◆ ~QXmppCallManager()

QXmppCallManager::~QXmppCallManager | ( |  | ) |
| overridedefault

Destroys the QXmppCallManager object.

## Member Function Documentation

## ◆ call()

std::unique_ptr< QXmppCall > QXmppCallManager::call | ( | const QString & | jid,
|  | Media | media = Media::Audio,
|  | const QString & | proposedSid = {} )

Initiates a new outgoing call to the specified recipient.

Parameters

  jid | Full-JID of the recipient.
  media | whether initiate with audio or audio and video
  proposedSid | Session ID of the call. If empty, a new session ID will be generated. Must be unique.

Since
  QXmpp 1.14, previously this function had a different signature.

## ◆ callReceived()

Q_SIGNAL 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
});
QXmppCallManager::call
std::unique_ptr< QXmppCall > call(const QString &jid, Media media=Media::Audio, const QString &proposedSid={})
Definition QXmppCallManager.cpp:377
QXmppCallManager::callReceived
Q_SIGNAL void callReceived(std::unique_ptr< QXmppCall > &call)

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.
  Incoming calls need to be accepted or rejected using QXmppCall::accept() or QXmppCall::hangUp().

Since
  QXmpp 1.14, previously this signal had a different signature.

## ◆ dtlsRequired()

bool QXmppCallManager::dtlsRequired | ( |  | ) | const

Returns whether the call manager requires encryption using XEP-0320: Use of DTLS-SRTP in Jingle Sessions for all calls.

Since
  QXmpp 1.11

## ◆ setDtlsRequired()

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.

Since
  QXmpp 1.11

## ◆ setFallbackStunServers()

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.

Since
  QXmpp 1.14

## ◆ setFallbackTurnServer()

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.

Since
  QXmpp 1.14

The documentation for this class was generated from the following files:

- QXmppCallManager.h
- QXmppCallManager.cpp