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

# Qtopia Data Linking - Protocol

- Introduction
- Overview The protocol is faily simple. A typical transaction between a client and source is as follows:
  - The client makes a request for a link by sending a QCop message to the source application's QCop channel. The request tells the source which channel to respond on.
  - The source receives the message and creates a list of records to respond with.
  - The source sends the list with a QCop message on the channel specified by the client. The source tells the client how many records it's sending.
  - The client receives the message and populates itself with the links.
- Client Requests A client makes a request by sending the following QCop message on the source application's channel. \code QDLRequestLink( QString channelName, QString hint ) \endcode 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. \code QDLProvideLinks( int numLinks ) \endcode
- 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 \code QDLActivateLink( QString dataRef ) \endcode 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. \code QDLRequestAllLinks( QString channelName, QString hint ) \endcode channelName is the name of the channel the source should respond on. hint is some data to help the source find records.

## 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:

- The client makes a request for a link by sending a QCop message to the source application's QCop channel. The request tells the source which channel to respond on.
- The source receives the message and creates a list of records to respond with.
- The source sends the list with a QCop message on the channel specified by the client. The source tells the client how many records it's sending.
- The client receives the message and populates itself with the links.

## 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.