QAbstractIpcInterface Class Reference
[QtBaseModule]

Detailed Description

The QAbstractIpcInterface class provides facilities for implementing the client and server sides of IPC communications paths.

This class makes it easier to implement IPC mechanisms using Qtopia. It is used extensively by the Qt Extended Telephony, Bluetooth, Hardware Accessory, and Multimedia libraries.

Subclasses that inherit this class implement the client side of the communication. Subclasses of the client implement the server side, overriding the client functionality with server code.

As an example, we will show how to implement a client/server "echo" interface. The client side has a send() slot which sends a string to the server. The server responds by emitting the receive() signal with the same string. The signal is delivered back to the client and emitted as receive(). First, the client class declaration:

    class QEcho : public QAbstractIpcInterface
    {
        Q_OBJECT
    public:
        QEcho( const QString& group = QString(),
               QObject *parent = 0, QAbstractIpcInterface::Mode mode = Client );

    public slots:
        virtual void send( const QString& msg );

    signals:
        void receive( const QString& msg );
    };

This declares the basic interface that all client applications will see. A client application can instantiate this class and use it like a regular QObject instance:

    QEcho *echo = new QEcho();
    connect( echo, SIGNAL(receive(QString)),
             this, SLOT(myReceive(QString)) );
    echo->send( "foo" );

In this example, we have left the group name null. This tells QAbstractIpcInterface to look up the default implementation of the QEcho interface.

If there is more than one group implementing the echo functionality, and the default is not suitable, the caller can supply an explicit group name to the QEcho constructor. Or the QAbstractIpcInterfaceGroupManager class can be used to look up a list of all groups that implement a particular interface.

As indicated above, the QEcho class is the client implementation of the functionality. We need to supply some extra code to complete the client side:

    QEcho::QEcho( const QString& group, QObject *parent,
                  QAbstractIpcInterface::Mode mode )
        : QAbstractIpcInterface( "/EchoInterfaces", "QEcho",
                                 group, parent, mode )
    {
        proxy( SIGNAL(receive(QString)) );
        proxy( SLOT(send(QString)) );
    }

    void QEcho::send( const QString& msg )
    {
        invoke( SLOT(send(QString)), qVariantFromValue( msg ) );
    }

The constructor calls proxy() for every signal and slot that it wishes to have delivered between the client and server. It can also call proxyAll() to proxy all signals and public slots. The /EchoInterfaces parameter specifies the location in the value space to place information about the interface.

The implementation of the send() slot uses invoke() to pass the request on to the server.

Now we turn our attention to the server side. The server class, QEchoServer, inherits from QEcho and overrides the send() slot to implement the server functionality.

    class QEchoServer : public QEcho
    {
        Q_OBJECT
    public:
        QEchoServer( QObject *parent ) : QEcho( "Echo", parent, Server ) {}

    public slots:
        void send( const QString& msg ) { emit receive( msg ); }
    }

We can also add another group implementing the echo functionality, which echos the value twice for every send:

    class QEchoTwiceServer : public QEcho
    {
        Q_OBJECT
    public:
        QEchoTwiceServer( QObject *parent )
            : QEcho( "EchoTwice", parent, Server )
            { setPriority(1); }

    public slots:
        void send( const QString& msg ) { emit receive( msg + msg ); }
    }

Now that we have two group implementations, the client must choose between them. It can either supply the group name explicitly or it can let the system choose. The system will choose the group with the highest priority value. If there is more than one group with the same priority, the one selected is undefined.

Here, we have set the priority of QEchoTwiceServer to 1, which will give it higher priority than QEchoServer which has the default priority of 0. Priorities can change over the lifetime of a server. For example, a VoIP group might have a higher priority than a GSM group when the phone is in range of a WiFi access point, but a lower priority when WiFi is not available. This way, the user gets the best group based on their current network coverage.

See also QAbstractIpcInterfaceGroup, QAbstractIpcInterfaceGroupManager, QCommInterface, and QHardwareInterface.

Member Type Documentation

enum QAbstractIpcInterface::Mode

Defines the client/server mode for an interface object.

enum QAbstractIpcInterface::SyncType

Defines whether interface values should be published by QAbstractIpcInterface::setValue() immediately or not.

Member Function Documentation

QAbstractIpcInterface::QAbstractIpcInterface ( const QString & valueSpaceLocation, const QString & interfaceName, const QString & groupName = QString(), QObject * parent = 0, QAbstractIpcInterface::Mode mode = Client )

Construct a new interface object for the interface called interfaceName on groupName and attach it to parent. If mode is Server, then the object is constructed in server mode and groupName must not be empty. If mode is Client, then the object is constructed in client mode and groupName may be empty to indicate the default group that implements this type of interface.

The valueSpaceLocation parameter specifies the location the value space to place all information about this interface. Subclasses such as QCommInterface will set this to a particular value meeting their requirements.

QAbstractIpcInterface::~QAbstractIpcInterface ()

Destroy this interface object. If the object is operating in client mode, then the connection to the server will be severed. If the object is operating in server mode, then it will be deregistered and all communicating clients will receive the disconnected() signal.

bool QAbstractIpcInterface::available () const

Returns true if the server is available for use; otherwise returns false. This is normally used by a client just after the constructor is called to determine if the constructor could locate a suitable server.

See also mode().

void QAbstractIpcInterface::disconnected ()   [signal]

Signal that is emitted on the client if the server disconnects before the client object is destroyed, or if the client could not connect at all because the server does not exist. Not used on the server.

The mode() of the interface object will be Invalid when this signal is emitted.

See also mode().

void QAbstractIpcInterface::groupInitialized ( QAbstractIpcInterfaceGroup * group )   [virtual protected]

Initializes server-side functionality within this interface after all interfaces in the group have been created. This is called by QAbstractIpcInterfaceGroup::initialize() after all interface handling objects on group have been created. It will not be called if the interface is not associated with a QAbstractIpcInterfaceGroup instance.

Subclasses typically override this method so that they can connect to signals on other interfaces which may not have existed when the interface constructor was called.

See also QAbstractIpcInterfaceGroup::initialize().

QString QAbstractIpcInterface::groupName () const

Returns the name of the group associated with this interface object.

See also interfaceName().

QString QAbstractIpcInterface::interfaceName () const

Returns the interface name associated with this interface object. If this object is known by more than one interface name, the interface name passed in the last call to proxyAll() will be returned.

See also groupName().

QtopiaIpcSendEnvelope QAbstractIpcInterface::invoke ( const QByteArray & name )   [protected]

Performs a call to the zero-argument slot name from the client to the server. Ignored on the server.

void QAbstractIpcInterface::invoke ( const QByteArray & name, QVariant arg1 )   [protected]

This is an overloaded member function, provided for convenience.

Performs a call to the one-argument slot name from the client to the server, with the argument arg1. Ignored on the server.

void QAbstractIpcInterface::invoke ( const QByteArray & name, QVariant arg1, QVariant arg2 )   [protected]

This is an overloaded member function, provided for convenience.

Performs a call to the two-argument slot name from the client to the server, with the arguments arg1 and arg2. Ignored on the server.

void QAbstractIpcInterface::invoke ( const QByteArray & name, QVariant arg1, QVariant arg2, QVariant arg3 )   [protected]

This is an overloaded member function, provided for convenience.

Performs a call to the three-argument slot name from the client to the server, with the arguments arg1, arg2, and arg3. Ignored on the server.

void QAbstractIpcInterface::invoke ( const QByteArray & name, const QList<QVariant> & args )   [protected]

This is an overloaded member function, provided for convenience.

Performs a call to the multi-argument slot name from the client to the server, with the arguments in the list args. Ignored on the server.

QAbstractIpcInterface::Mode QAbstractIpcInterface::mode () const

Returns the mode that this interface object is operating in. Returns QAbstractIpcInterface::Client for client mode, QAbstractIpcInterface::Server for server mode, and QAbstractIpcInterface::Invalid if the client's connection to the server could not be established or has been lost.

See also available().

void QAbstractIpcInterface::proxy ( const QByteArray & member )   [protected]

Proxies member so that it will be delivered between the client and server. This is typically called from the constructor of the immediate subclass of QAbstractIpcInterface for all signals and slots that will cross the client/server boundary.

This method is useful when the subclass has only a few signals and slots that need to be proxied. Or it contains signals and slots that must not be proxied because they are private to the client or server sides. The related proxyAll() method is simpler to use if the subclass has many signals and slots and they must all be proxied.

See also proxyAll().

void QAbstractIpcInterface::proxyAll ( const QMetaObject & meta )   [protected]

Sets up remote invocation proxies for all signals and public slots on this object, starting at the class specified by meta.

Normally meta will be the staticMetaObject value for the immediate subclass of QAbstractIpcInterface. It allows the proxying to be limited to a subset of the class hierarchy if more derived classes have signals and slots that should not be proxied.

This method is useful when the subclass has many signals and slots, and it would be error-prone to proxy them individually with proxy().

See also proxy().

void QAbstractIpcInterface::proxyAll ( const QMetaObject & meta, const QString & subInterfaceName )   [protected]

This is an overloaded member function, provided for convenience.

Sets up remote invocation proxies for all signals and public slots on this object, starting at the class specified by meta. Also register subInterfaceName as a sub-interface name for this object's primary interface name. After this call, interfaceName() will return subInterfaceName.

void QAbstractIpcInterface::removeValue ( const QString & name, QAbstractIpcInterface::SyncType sync = Immediate )   [protected]

Removes the value associated with name from the auxiliary value space.

If sync is Delayed, then delay publication of the value to clients until the server re-enters the Qt event loop. This may be more efficient if the server needs to set or remove several values at once. The default value for sync is Immediate.

See also value() and setValue().

void QAbstractIpcInterface::setPriority ( int value )   [protected]

Sets the priority of this server to value. Ignored on the client.

void QAbstractIpcInterface::setValue ( const QString & name, const QVariant & value, QAbstractIpcInterface::SyncType sync = Immediate )   [protected]

Sets name to value in the auxiliary value space for this interface object. This is called by the server to notify clients of a change in name. Ignored on the client.

If sync is Delayed, then delay publication of the value to clients until the server re-enters the Qt event loop. This may be more efficient if the server needs to set or remove several values at once. The default value for sync is Immediate.

See also value() and removeValue().

QVariant QAbstractIpcInterface::value ( const QString & name, const QVariant & def = QVariant() ) const   [protected]

Returns the value associated with name in the auxiliary value space for this interface object. Returns def if the name does not exist. This can be called on either the client or the server (but usually the client).

See also setValue() and removeValue().

QList<QString> QAbstractIpcInterface::valueNames ( const QString & path = QString() ) const   [protected]

Returns a list of all value names in the auxiliary value space for this interface object contained within path.

See also value().