QXmppCallManager Class Reference

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

Inheritance diagram for QXmppCallManager:

Collaboration 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>();

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

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.

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