Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Qtopia Data Linking - Protocol

Introduction

The QDL protocol is a series of messages and behaviours that are defined for applications wishing to implement QDL. This document deals exclusively with the protocol of QDL. For more general information about QDL, please see the specification.

Overview The protocol is faily simple. A typical transaction between a client and source is as follows:

Client Requests A client makes a request by sending the following QCop message on the source application's channel.
    QDLRequestLink( QString channelName, QString hint )
channelName is the name of the channel the source should respond on. hint is some data to help the source find records. The hint may be empty.

Source Responses A source reponds to a QDLGetLink message by sending the following QCop message on the channel specified by the client.
    QDLProvideLinks( int numLinks )

numLinks is the number of links sent in this message. numLinks can be zero (ie. there are no links) or it can be a positive integer. In the latter case, the following information will be encoded into the QCop message numLinks times.

An example of how to handle this QCop message is given below:

void receiveMessage( QString message, QByteArray data )
{
    if ( message == "QDLProvideLinks(int)" ) {
        QDataStream source( data );
        int numLinks;
        source >> numLinks;
        QString appRef, dataRef, description, icon;
        for ( int i = 0; i < numLinks; i++ ) {
            source >> appRef >> dataRef >> description >> icon;
            // do something with the link
        }
    }
}

appRef is the application the link references. dataRef this is data to be passed to the Source so that it can perform an action. description is the descriptive text of the link. icon is the filename of the icon associated with the link.

Note: The Source is not required to allow selecting multiple links.

Detecting a stalled Source The Client is notified by the QDL library if the Source application cannot be contacted. There is communication between the Source and the QDL library to ensure the Client is not kept waiting if the Source crashes.

Link Activation To activate a link an application sends the following message to the source
    QDLActivateLink( QString dataRef )
dataRef is a unique reference to some data that the source application contains.

Global Find Global Find will send the following message to each Source.
    QDLRequestAllLinks( QString channelName, QString hint )
channelName is the name of the channel the source should respond on. hint is some data to help the source find records.

The Source is not expected to display anything when processing a Global Find operation since the Global Find application itself will display the results it received.


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1