VoIP Integration

Phone Calls

Once the service has been checked, and the network registered, the next step is to enable the placement of phone calls. Qt Extended achieves this in telephony services with the QPhoneCallProvider interface. Our Asterisk agent needs to inherit from QPhoneCallProvider and override the create() method (iaxcallprovider.h and iaxcallprovider.cpp):

    class IaxCallProvider : public QPhoneCallProvider
    {
        Q_OBJECT
    public:
        IaxCallProvider( IaxTelephonyService *service );
        ~IaxCallProvider() {}

        void stateEvent( struct iaxc_ev_call_state *e );

    protected:
        virtual QPhoneCallImpl *create
            ( const QString& identifier, const QString& callType );
    };

    IaxCallProvider::IaxCallProvider( IaxTelephonyService *service )
        : QPhoneCallProvider( service->service(), service )
    {
        setCallTypes( QStringList( "Asterisk" ) );
        ...
    }

    QPhoneCallImpl *IaxCallProvider::create
            ( const QString& identifier, const QString& callType )
    {
        return new IaxPhoneCall( this, identifier, callType, -1 );
    }

The call to QPhoneCallProvider::setCallTypes() in the constructor is very important. It publishes the call types that are understood by the telephony service into the value space. Qt Extended uses this information to select an appropriate service to place an outgoing call. If the setCallTypes() function is not called in the constructor, then it will not be possible to place phone calls using the service.

Call types are typically simple names such as Voice, VoIP, Data, Fax, Video, etc. See the documentation for QPhoneCallManager::create() for a description of how call types are used to select an appropriate telephony service.

The VoIP call type is reserved for use by SIP-based telephony services. We cannot use that for our IAX2 implementation, so we publish the service's call type as Asterisk instead.

By convention, service names start with a lower-case letter, and call type names start with an upper-case letter. This convention is not strictly enforced by Qt Extended, but it can help when diagnosing telephony problems to be able to distinguish a word used as a service name and the same word used as a call type.

This code creates an instance of IaxPhoneCall whenever the user attempts to place an outgoing phone call. It will then be followed by a call to IaxPhoneCall::dial(). The IaxPhoneCall class is declared as follows:

    class IaxPhoneCall : public QPhoneCallImpl
    {
        Q_OBJECT
    public:
        IaxPhoneCall( IaxCallProvider *provider, const QString& identifier,
                      const QString& callType, int callNo );
        virtual ~IaxPhoneCall();

        virtual void dial( const QDialOptions& options );
        virtual void hangup( QPhoneCall::Scope scope );
        virtual void accept();
        virtual void hold();
        virtual void activate( QPhoneCall::Scope scope );
        virtual void tone( const QString& tones );
        virtual void transfer( const QString& number );

        void stateEvent( struct iaxc_ev_call_state *e );

        ...
    };

All telephony services must inherit from QPhoneCallImpl to provide the functions on phone calls. See the documentation for that class for more information on the functionality that is required.

The above applies to outgoing calls. For incoming calls, the Asterisk service detects the call in IaxCallProvider::stateEvent() and then constructs an instance of IaxPhoneCall directly:

    void IaxCallProvider::stateEvent( struct iaxc_ev_call_state *e )
    {
        IaxPhoneCall *call = fromCallNo( e->callNo );
        if ( call ) {
            // State change on a known call.
            call->stateEvent( e );
        } else if ( ( e->state & IAXC_CALL_STATE_RINGING ) != 0 ) {
            // Newly arrived incoming call.
            beginStateTransaction();
            QString identifier = QUuid::createUuid().toString();
            IaxPhoneCall *call = new IaxPhoneCall
                ( this, identifier, "Asterisk", e->callNo );
            call->setNumber( e->remote );
            call->setActions( QPhoneCallImpl::Transfer );
            call->setState( QPhoneCall::Incoming );
            endStateTransaction();
        }
    }

    class SipPresence : public QPresence
    {
        Q_OBJECT
    public:
        SipPresence( SipTelephonyService *service );
        ~SipPresence();

    public slots:
        virtual bool startMonitoring( const QString& uri );
        virtual bool stopMonitoring( const QString& uri );
        virtual void setLocalPresence( QPresence::Status status );

        ...
    };

    if ( !supports<QPresence>() )
        addInterface( new SipPresence( this ) );

    class IaxConfiguration : public QTelephonyConfiguration
    {
        Q_OBJECT
    public:
        IaxConfiguration( IaxTelephonyService *service );
        ~IaxConfiguration() {}

    public slots:
        virtual void update( const QString& name, const QString& value );
        virtual void request( const QString& name );

    private:
        IaxTelephonyService *service;
    };

    IaxConfiguration::IaxConfiguration( IaxTelephonyService *service )
        : QTelephonyConfiguration( service->service(), service, Server )
    {
        this->service = service;
    }

    void IaxConfiguration::update( const QString& name, const QString& )
    {
        // Process messages from the "iaxsettings" program for config updates.
        if ( name == "registration" )
            service->updateRegistrationConfig();
        else if ( name == "callerid" )
            service->updateCallerIdConfig();
    }

    void IaxConfiguration::request( const QString& name )
    {
        // Not supported - just return an empty value.
        emit notification( name, QString() );
    }

    class AsteriskManager : public QAbstractCallPolicyManager
    {
        Q_OBJECT
    public:
        AsteriskManager( QObject *parent=0 );
        ~AsteriskManager();

        virtual QString callType() const;
        virtual QString trCallType() const;
        virtual QString callTypeIcon() const;
        virtual QTelephony::RegistrationState registrationState() const;
        virtual QAbstractCallPolicyManager::CallHandling handling(const QString& number);
        virtual bool isAvailable(const QString& number);
        virtual QString registrationMessage() const;
        virtual QString registrationIcon() const;

        ...
    };

    QTOPIA_TASK_INTERFACE(AsteriskManager);

    QAbstractCallPolicyManager::CallHandling AsteriskManager::handling
            (const QString& number)
    {
        // Cannot handle URI's that contain '@' or ':'.
        if (number.contains(QChar('@')) || number.contains(QChar(':')))
            return CannotHandle;

        // If no network registration, then cannot handle at this time.
        if (registrationState() != QTelephony::RegistrationHome)
            return CannotHandle;

        // Assume that this is a number that we can dial.
        return CanHandle;
    }