Qt Extended IPC Layer

Overview

Qt Extended IPC API is exposed to the user through the QtopiaIpcAdaptor class. QtopiaIpcAdaptor can be used in two ways: direct access and an inheritance based approach.

To use QtopiaIpcAdaptor directly, we first construct a new object by providing a channel as so:

    QtopiaIpcAdaptor *adaptor = new QtopiaIpcAdaptor("QPE/CannonExample");

The newly created adaptor object can now be used to send messages to remote applications, or to receive messages. To send messages use the send method calls:

    // First we aim the cannon
    QtopiaIpcSendEnvelope envelope = adaptor->send(MESSAGE(aimCannon(int,int)));
    envelope << direction << elevation;

    // Alternatively if there are less than 3 arguments we can use send directly
    adaptor->send(MESSAGE(shootCannon(int)), cannonPower);

Another application is responsible for actually aiming and shooting the cannon. Let us suppose that the cannon application can reply with two types of messages, a hit or a miss. E.g. the remote application will send a missed() or hit() message. We can listen for such messages in the following manner:

    class CannonListener : public QObject
    {
        Q_OBJECT

    public slots:
        void missed();
        void hit();
    };

    ...

    CannonListener *listener = new CannonListener;
    QtopiaIpcAdaptor *adaptor = new QtopiaIpcAdaptor("QPE/CannonExample");
    QtopiaIpcAdaptor::connect(adaptor, MESSAGE(missed()), listener, SLOT(missed()));
    QtopiaIpcAdaptor::connect(adaptor, MESSAGE(hit()), listener, SLOT(hit()));

We can also use QtopiaIpcAdaptor::connect to enable an object's signals to be sent over a channel automatically. For instance, we can rewrite the above example like this:

    class CannonController : public QObject
    {
        Q_OBJECT

    public slots:
        void missed();
        void hit();

    signals:
        void aimCannon(int dir, int elev);
        void shootCannon(int power);
    };

    ...

    CannonController *control = new CannonController;
    QtopiaIpcAdaptor *adaptor = new QtopiaIpcAdaptor("QPE/CannonExample");

    // Hookup remote messages to our object
    QtopiaIpcAdaptor::connect(adaptor, MESSAGE(missed()), control, SLOT(missed()));
    QtopiaIpcAdaptor::connect(adaptor, MESSAGE(hit()), control, SLOT(hit()));

    // Send our signals to the remote object
    QtopiaIpcAdaptor::connect(control, SIGNAL(aimCannon(int,int)), adaptor, MESSAGE(aimCannon(int,int)));
    QtopiaIpcAdaptor::connect(control, SIGNAL(shootCannon(int)), adaptor, MESSAGE(shootCannon(int)));

We should now recognize that for non-trivial interactions the last example is a quite common use case. It is thus desirable to avoid using QtopiaIpcAdaptor::connect for each connection, which can be quite error prone. QtopiaIpcAdaptor provides an alternate interaction technique based on inheritance. Instead of creating another class and using QtopiaIpcAdaptor::connect, we inherit directly from QtopiaIpcAdaptor and use the publish or publishAll methods to automatically publish all signals and slots on the channel. E.g.:

        class CannonController : public QtopiaIpcAdaptor
        {
            Q_OBJECT

        public:
            CannonController(QObject *parent = 0);
            void shoot();

        public slots:
            void missed();
            void hit();

        signals:
            void aimCannon(int dir, int elev);
            void shootCannon(int power);
        };

        CannonController::CannonController(QObject *parent)
            : QtopiaIpcAdaptor("QPE/CannonExample", parent)
        {
            publishAll(QtopiaIpcAdaptor::SignalsAndSlots);
        }

        void CannonController::missed()
        {
            qDebug() << "Cannon missed!";
        }

        void CannonController::hit()
        {
            qDebug() << "Cannon HIT!";
        }

        void CannonController::shoot()
        {
            emit aimCannon(0, 45);
            emit shootCannon(100);
        }

    ...

        CannonController *control = new CannonController;
        control->shoot();

        // Header
        class CannonController : public QtopiaIpcAdaptor
        {
            Q_OBJECT

        public:
            enum AmmunitionType { Explosive = 0, ArmorPiercing, Napalm }

            CannonController(QObject *parent = 0);
            void shoot();

        public slots:
            void missed();
            void hit();

        signals:
            void aimCannon(int dir, int elev);
            void shootCannon(int power);
            void setAmmunitionType(AmmunitionType type);
        };

        Q_DECLARE_USER_METATYPE_ENUM(CannonController::AmmunitionType)

    ...

        // Implementation:

        Q_IMPLEMENT_USER_METATYPE_ENUM(CannonController::AmmunitionType)

        class CannonFireOrders
        {
        public:
            enum AmmunitionType { Explosive = 0, ArmorPiercing, Napalm }
            CannonFireOrders( AmmunitionType type, int direction, int elevation, int power);

            int direction() const;
            int elevation() const;
            int power() const;
            AmmunitionType type() const;

        private:
            int m_dir;
            int m_elev;
            int m_power;
            AmmunitionType m_type;
        };

        Q_DECLARE_USER_METATYPE_ENUM(CannonFireOrders::AmmunitionType)
        Q_DECLARE_USER_METATYPE(CannonFireOrders)

        class CannonController : public QtopiaIpcAdaptor
        {
            Q_OBJECT

        public:
            CannonController(QObject *parent = 0);
            void shoot();

        public slots:
            void missed();
            void hit();

        signals:
            void shootCannon(const CannonFireOrders &orders);
        };

        class CannonFireOrders
    {
        public:

        ....

        template <typename Stream> void serialize(Stream &stream) const;
        template <typename Stream> void deserialize(Stream &stream);
        ...
    };

        Q_IMPLEMENT_USER_METATYPE_ENUM(CannonFireOrders::AmmunitionType)
        Q_IMPLEMENT_USER_METATYPE(CannonFireOrders)

        ....

        template <typename Stream> void CannonFireOrders::serialize(Stream &s) const
        {
            s << m_dir;
            s << m_elev;
            s << m_power;
            s << m_type;
        }

        template <typename Stream> void CannonFireOrders::deserialize(Stream &s)
        {
            s >> m_dir;
            s >> m_elev;
            s >> m_power;
            s >> m_type;
        }