QtopiaIpcAdaptor Class Reference
[QtBaseModule]

Detailed Description

The QtopiaIpcAdaptor class provides an interface to messages on a Qt Extended IPC channel which simplifies remote signal and slot invocations.

Using this class, it is very easy to convert a signal emission into an IPC message on a channel, and to convert an IPC message on a channel into a slot invocation. In the following example, when the signal valueChanged(int) is emitted from the object source, the IPC message changeValue(int) will be sent on the channel QPE/Foo:

    QtopiaIpcAdaptor *adaptor = new QtopiaIpcAdaptor("QPE/Foo");
    QtopiaIpcAdaptor::connect
        (source, SIGNAL(valueChanged(int)), adaptor, MESSAGE(changeValue(int)));

Note that we use QtopiaIpcAdaptor::connect() to connect the signal to the IPC message, not QObject::connect(). A common error is to use connect() without qualifying it with QtopiaIpcAdaptor:: and picking up QObject::connect() by mistake.

On the server side of an IPC protocol, the changeValue(int) message can be connected to the slot setValue() on dest:

    QtopiaIpcAdaptor *adaptor = new QtopiaIpcAdaptor("QPE/Foo");
    QtopiaIpcAdaptor::connect
        (adaptor, MESSAGE(changeValue(int)), dest, SLOT(setValue(int)));

Now, whenever the client emits the valueChanged(int) signal, the setValue(int) slot will be automatically invoked on the server side, with the int parameter passed as its argument.

Only certain parameter types can be passed across an IPC boundary in this fashion. The type must be visible to QVariant as a meta-type. Many simple built-in types are already visible; for user-defined types, use Q_DECLARE_USER_METATYPE().

See also QtopiaAbstractService and QtopiaIpcEnvelope.

Member Type Documentation

enum QtopiaIpcAdaptor::ChannelSelector

Select which of the sender or receiver in QtopiaIpcAdaptor::connect is the channel.

enum QtopiaIpcAdaptor::PublishType

Type of members to publish via QtopiaIpcAdaptor.

Member Function Documentation

QtopiaIpcAdaptor::QtopiaIpcAdaptor ( const QString & channel, QObject * parent = 0 )

Construct a Qt Extended IPC message object for channel and attach it to parent. If channel is empty, then messages are taken from the application's appMessage channel.

QtopiaIpcAdaptor::~QtopiaIpcAdaptor ()

Destroy this Qt Extended IPC messaging object.

bool QtopiaIpcAdaptor::connect ( QObject * sender, const QByteArray & signal, QObject * receiver, const QByteArray & member, QtopiaIpcAdaptor::ChannelSelector selector = AutoDetect )   [static]

Connects signal on sender to member on receiver. Returns true if the connection was possible; otherwise returns false.

If either sender or receiver are instances of QtopiaIpcAdaptor, this function will arrange for the signal to be delivered over a Qt Extended IPC channel. If both sender and receiver are local, this function is identical to QObject::connect().

The selector argument allows the caller to disambiguate the case where both sender and receiver are instances of QtopiaIpcAdaptor.

If the same signal is connected to same slot multiple times, then signal delivery will happen that many times.

See also QtopiaIpcAdaptor::ChannelSelector.

bool QtopiaIpcAdaptor::isConnected ( const QByteArray & signal )

Returns true if the message on the Qt Extended IPC channel corresponding to signal has been connected to a local slot; otherwise returns false.

QString QtopiaIpcAdaptor::memberToMessage ( const QByteArray & member )   [virtual protected]

Converts a signal or slot member name into a Qt Extended IPC message name. The default implementation strips the signal or slot prefix number from member and then normalizes the name to convert types such as const QString& into QString.

bool QtopiaIpcAdaptor::publish ( const QByteArray & member )   [protected]

Publishes the signal or slot called member on this object on the Qt Extended IPC channel represented by this QtopiaIpcAdaptor.

If member is a slot, then whenever an application sends a message to the channel with that name, the system will arrange for the slot to be invoked.

If member is a signal, then whenever this object emits that signal, the system will arrange for a message with that name to be sent on the channel.

Returns false if member does not refer to a valid signal or slot.

See also publishAll().

void QtopiaIpcAdaptor::publishAll ( QtopiaIpcAdaptor::PublishType type )   [protected]

Publishes all signals or public slots on this object within subclasses of QtopiaIpcAdaptor. This is typically called from a subclass constructor. The type indicates if all signals, all public slots, or both, should be published. Private and protected slots will never be published.

See also publish().

QString QtopiaIpcAdaptor::receiveChannel ( const QString & channel )   [virtual protected]

Converts channel into a new name to use for receiving messages. The default implementation returns channel.

QtopiaIpcSendEnvelope QtopiaIpcAdaptor::send ( const QByteArray & member )

Sends a message on the Qt Extended IPC channel which will cause the invocation of member on receiving objects. The return value can be used to add arguments to the message before transmission.

void QtopiaIpcAdaptor::send ( const QByteArray & member, const QVariant & arg1 )

This is an overloaded member function, provided for convenience.

Sends a message on the Qt Extended IPC channel which will cause the invocation of the single-argument member on receiving objects, with the argument arg1.

void QtopiaIpcAdaptor::send ( const QByteArray & member, const QVariant & arg1, const QVariant & arg2 )

This is an overloaded member function, provided for convenience.

Sends a message on the Qt Extended IPC channel which will cause the invocation of the double-argument member on receiving objects, with the arguments arg1 and arg2.

void QtopiaIpcAdaptor::send ( const QByteArray & member, const QVariant & arg1, const QVariant & arg2, const QVariant & arg3 )

This is an overloaded member function, provided for convenience.

Sends a message on the Qt Extended IPC channel which will cause the invocation of the triple-argument member on receiving objects, with the arguments arg1, arg2, and arg3.

void QtopiaIpcAdaptor::send ( const QByteArray & member, const QList<QVariant> & args )

This is an overloaded member function, provided for convenience.

Sends a message on the Qt Extended IPC channel which will cause the invocation of the multi-argument member on receiving objects, with the argument list args.

QStringList QtopiaIpcAdaptor::sendChannels ( const QString & channel )   [virtual protected]

Converts channel into a list of names to use for sending messages. The default implementation returns a list containing just channel.