qdl.cpp

Trolltech公司发布的图形界面操作系统。可在qt-embedded-2.3.10平台上编译为嵌入式图形界面操作系统。

/**********************************************************************
** Copyright (C) 2000-2005 Trolltech AS.  All rights reserved.
**
** This file is part of the Qtopia Environment.
** 
** This program is free software; you can redistribute it and/or modify it
** under the terms of the GNU General Public License as published by the
** Free Software Foundation; either version 2 of the License, or (at your
** option) any later version.
** 
** A copy of the GNU GPL license version 2 is included in this package as 
** LICENSE.GPL.
**
** This program is distributed in the hope that it will be useful, but
** WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
** See the GNU General Public License for more details.
**
** In addition, as a special exception Trolltech gives permission to link
** the code of this program with Qtopia applications copyrighted, developed
** and distributed by Trolltech under the terms of the Qtopia Personal Use
** License Agreement. You must comply with the GNU General Public License
** in all respects for all of the code used other than the applications
** licensed under the Qtopia Personal Use License Agreement. If you modify
** this file, you may extend this exception to your version of the file,
** but you are not obligated to do so. If you do not wish to do so, delete
** this exception statement from your version.
** 
** See http://www.trolltech.com/gpl/ for GPL licensing information.
**
** Contact [e-mail] if any conditions of this licensing are
** not clear to you.
**
**********************************************************************/

#include <qobjectlist.h>
#include <qwidget.h>
#include <qstringlist.h>
#include <qdatastream.h>
#include <qtimer.h>
#include <qlistbox.h>
#include <qvaluelist.h>
#include <qaction.h>
#include <qlayout.h>

#include <qtopia/qpeapplication.h>
#ifdef QTOPIA_PHONE
#include <qtopia/contextmenu.h>
#endif
#include <qtopia/resource.h>
#ifndef NO_QT_QCOP
#include <qtopia/qcopenvelope_qws.h>
#include <qcopchannel_qws.h>
#endif
#include <qtopia/global.h>
#include <qtopia/services.h>
#include <qtopia/applnk.h>
#include <qtopia/stringutil.h>
#include <qtopia/quuid.h>

#include "qdl.h"
#include "qdl_p.h"

const QString QDL_KEY_DELIM = "-";

//initalise QDL static constants
const QString QDL::DATA_KEY = "qdl-private-data";

const QCString QDL::CLIENT_CHANNEL = "QPE/QDL";

const ushort QDL::u1 = 0x00B9;
const ushort QDL::u2 = 0x00B2;
const ushort QDL::u3 = 0x00B3;
const ushort QDL::u4 = 0x2074;
const ushort QDL::u5 = 0x2075;
const ushort QDL::u6 = 0x2076;
const ushort QDL::u7 = 0x2077;
const ushort QDL::u8 = 0x2078;
const ushort QDL::u9 = 0x2079;
const ushort QDL::u0 = 0x2070;

/*!
  \class QDL qdl.h
  \brief The QDL class provides general utility functions for use
    with Qtopia Data Linking.

  Qtopia Data Linking (QDL) enables a client to link to data in a source.
  A client may be a stand-alone object (QDLClient) or attached to a
  widget (QDLWidgetClient).
  A source can be any application which acts as a container for useful
  data and provides the QDL Service. 

  This class provides useful functions for loading and saving links
  and dealing with general QDL usage.

  First availability: Qtopia 2.0

  \ingroup qtopiaemb
*/

/*!
  Returns all QDLClient objects that are children of \a parent.
  This is useful for automatically loading links into a bunch of clients eg.

  \code
    QDL::loadLinks( rec, QDL::clients( this ) );
  \endcode
*/
QList<QDLClient> QDL::clients( QObject *parent )
{
    QList<QDLClient> cs;

    if( !parent )
	return cs;

    QObjectList *l = parent->queryList( "QDLClient" );
    if( !l ) return cs;

    QObjectListIt it( *l );

    while( it.current() )
    {
	QDLClient *client = (QDLClient *)it.current();
	cs.append( client );
	++it;
    }

    delete l;

    return cs;
}

/*!
  Sends a heart beat to the client with the specified \a clientID.
  A heart beat is used by a source to let clients know that their request is still
  being actively processed. A client will stop waiting for a response if their request times out
  so this function should be called periodically to keep the request alive.

  Normally you don't want to use this function directly, but the abstraction class QDLHeartBeat.
  
  \sa QDLHeartBeat
*/
void QDL::sendHeartBeat( const QString &clientID )
{
#ifndef QT_NO_QCOP
    QCopEnvelope e( QDL::CLIENT_CHANNEL, "QDLHeartBeat(QString)" );
    e << clientID;
#else
    qDebug("BUG : Using a QDLHeartBeat when QCop not enabled");
#endif
}

/*
   \relates QDL
   Reads \a clientList from the \a stream
*/
QDataStream &operator>>( QDataStream &stream, QList<QDLClient> &clientList )
{
    while( !stream.atEnd() )
    {
	QString clientName;
	uint numLinks = 0;
	stream >> clientName >> numLinks;
	if( clientName.isEmpty() || numLinks == 0 )
	    continue;

	QListIterator<QDLClient> cit( clientList );
	QDLClient *c = 0;
	for( ; *cit ; ++cit )
	{
	    if( QString((*cit)->name()) == clientName )
	    {
		c = *cit;
		break;
	    }
	}

	for( uint i = 0 ; i < numLinks ; ++i )
	{
	    uint lid = 0;
	    QDLLink newLink;
	    stream >> lid >> newLink; 
	    if( c )
	    {
		if( lid == 0 )
		    qDebug("BUG : QDL::loadLinks - Tried to load link from client %s with lid 0", clientName.latin1());
		else
		    c->QDLClient::setLink( lid, newLink );//explicit call to base class version
	    }
	}
    }
    return stream;
}

/*!
  Loads the links stored in \a str into the clients in \a clientList.
  \a str is the base64 encoded binary data of the links.
*/
void QDL::loadLinks( const QString &str, QList<QDLClient> clientList )
{
    // extract all links out of the string
    if( str.isEmpty() )
	return;
    QByteArray data;
    data.duplicate( str.latin1(), str.length() );
    data = Global::decodeBase64( data );
    QDataStream stream( data, IO_ReadOnly );
    stream >> clientList;
}

/*! \overload

  Loads the links stored in \a str into a single \a client.
*/
void QDL::loadLinks( const QString &str, QDLClient *client )
{
    QList<QDLClient> clients;
    clients.append( client );
    QDL::loadLinks( str, clients );	
}

/*
   \relates QDL
   Writes \a clientList to \a stream
*/
QDataStream &operator<<( QDataStream &stream, const QList<QDLClient> &clientList )
{
    QListIterator<QDLClient> cit( clientList );
    for( ; *cit ; ++cit )
    {
	//verify links for this client
	(*cit)->verifyLinks();

	QMap<uint, QDLLink> links = (*cit)->links();
	QString clientName = (*cit)->name();

	if( clientName.isEmpty() || !links.count() )
	    continue;

	stream << clientName << links.count();

	QMap<uint, QDLLink>::ConstIterator lit;
	for( lit = links.begin() ; lit != links.end() ; ++lit )
	    stream << lit.key() << lit.data();
    }
    return stream;
}

/*!
  Saves the links from \a clientList into \a str.
  \a str will be the base64 encoded binary link data.
*/
void QDL::saveLinks( QString &str, QList<QDLClient> clientList )
{
    QByteArray data;
    QDataStream stream( data, IO_WriteOnly );
    stream << clientList;
    data = Global::encodeBase64( data );
    str = QString( data );
}

/*! \overload
  Saves the links from the single \a client to \a str.
*/
void QDL::saveLinks( QString &str, QDLClient *client )
{
    QList<QDLClient> clients;
    clients.append( client );
    QDL::saveLinks( str, clients );
}


/*!
  Converts the unicode superscript link identifier \a lid into
  an equivalent unsigned integer link identifier.

  \sa lidFromUInt()
*/
uint QDL::lidToUInt( const QString &lid )
{
    const int len = lid.length();
    uint il = 0;
    for( int i = 0 ; i < len ; ++i )
    {
	if( lid[i].isDigit() )
	{
	    il = il * 10 + (uint)lid[i].digitValue();
	    continue;
	}

	ushort ch = lid[i].unicode();
	int v = -1;
	switch( ch )
	{
	    case u1:
		v = 1;
		break;
	    case u2:
		v = 2;
		break;
	    case u3:
		v = 3;
		break;
	    case u4:
		v = 4;
		break;
	    case u5:
		v = 5;
		break;
	    case u6:
		v = 6;
		break;
	    case u7:
		v = 7;
		break;
	    case u8:
		v = 8;
		break;
	    case u9:
		v = 9;
		break;
	    case u0:
		v = 0;
		break;
	}
	if( v != -1 )
	    il = il * 10 + (uint)v;
    }
    return il;
}

/*!
  Converts the unsigned integer link identifier \a lid into an equivalent
  unicode superscript link identifier.
*/
QString QDL::lidFromUInt( uint lid )
{
    QString lidAscStr, lidStr;
    lidAscStr.setNum( lid );
    const int len = lidAscStr.length();

    for( int i = 0 ; i < len ; ++i )
    {
	char ch = lidAscStr[i].latin1();
	switch( ch )
	{
	    case '0':
		lidStr += QChar(u0);
		break;
	    case '1':
		lidStr += QChar(u1);
		break;
	    case '2':
		lidStr += QChar(u2);
		break;
	    case '3':
		lidStr += QChar(u3);
		break;
	    case '4':
		lidStr += QChar(u4);
		break;
	    case '5':
		lidStr += QChar(u5);
		break;
	    case '6':
		lidStr += QChar(u6);
		break;
	    case '7':
		lidStr += QChar(u7);
		break;
	    case '8':
		lidStr += QChar(u8);
		break;
	    case '9':
		lidStr += QChar(u9);
		break;
	}
    }
    return lidStr;
}

/*!
  Activates the QDL link specified by \a ahref. 
  ahref should be in the form \code qdl://<clientName>:<lid> \endcode.
  Rich text links are usually generated by QDL::lidsToAnchors.

  What 'activate' actually means is dependent on the source application.
  As an example, if \c the QDLLink points to a contact, the Contacts 
  application might display that particular contact.

  \sa QDL::lidsToAnchors
*/
void QDL::activateLink( const QString &ahref, const QList<QDLClient> &clientList )
{
    QString text = ahref;
    if( !text.startsWith( "qdl://" ) )
    {
	qWarning("QDL::activateLink - '%s' doesn't appear to be a valid QDL link.", text.latin1() );
	return;
    }
    text = text.mid(6);
    QString clientName;
    uint lid = 0;
    QStringList data;
    data = QStringList::split( ':', text );
    if( data.count() != 2 )
    {
	qWarning("QDL::activateLink called with invalid link data");
	return;
    }
    clientName = QDL::decodeAhref(data[0]);
    lid = QDL::decodeAhref(data[1]).toUInt();
    if( clientName.isEmpty() || lid == 0 )
    {
	qWarning("QDL::activateLink - Skipping activation of empty link.");
	return;
    }

    //find the client
    QDLClient *c = 0;
    QListIterator<QDLClient> it(clientList);
    for( ; *it ; ++it )
    {
	if( QString((*it)->name()) == clientName )
	{
	    c = *it;
	    break;
	}
    }

    if( !c )
    {
	qWarning("QDL::activateLink - Can't activate link for unknown client %s", clientName.latin1());
	return;
    }

    //get the link
    QDLLink al = c->link( lid );
    if( al.isNull() )
    {
	qWarning("QDL::activateLink - Link with lid %d does not exist in client %s", lid, clientName.latin1());
	return;
    }

#ifndef QT_NO_QCOP
    QCString channel;
    channel = "QPE/Application/" +  al.appRef();
    QCopEnvelope e( channel, "QDLActivateLink(QByteArray)" );
    e << al.dataRef();
#endif
}

/*!
  Converts the unicode superscript link identifiers in \a lidText to rich text anchors 
  based on the links in \a client.

  If \a withIcons is TRUE (the default), icons are included as part of the rich text links.
*/
QString QDL::lidsToAnchors( const QString &lidText, const QDLClient *client, bool withIcons )
{
    QMap<uint, QDLLink> links = client->links();
    QString t = lidText;
    QMap<uint, QDLLink>::ConstIterator it;
    for( it = links.begin() ; it != links.end() ; ++it )
    {
	QString lid = QDL::lidFromUInt( it.key() );
	QString lt = (*it).description()+lid;
	int f = t.find( lt ); 
	bool haveDesc = TRUE;
	if( f == -1 )
	{
	    lt = lid;
	    f = t.find( lid );
	    if( f != -1 )
		haveDesc = FALSE;
	}
	if( f != -1 )
	{
	    t = t.remove( f, lt.length() );
	    QString ahref = "<a href=\"qdl://%1:%2\">%3%4</a>";
	    ahref = ahref.arg( QDL::encodeAhref(client->name()) ).arg( it.key() );
	    if( haveDesc )
		ahref = ahref.arg( Qtopia::escapeString((*it).description()) );
	    else
		ahref = ahref.arg( "" );
	    /*
	     if they've changed the description of the link, override withIcons 
	     and always include an icon.  // otherwise, what would reference the link?
	     */
	    if( withIcons || !haveDesc ) 
	    {
		QString iFileName = (*it).icon();
		if( iFileName.isEmpty() )
		    iFileName = "qdllink";
		/* FIXME
	    should the user be able to set the size of the icon? eg font().pointSize()
		*/
		QString img = "<img width=\"12\" height=\"12\" src=\"%1\">";
		img = img.arg( Qtopia::escapeString(iFileName) );
		ahref = ahref.arg( img );
	    }
	    else
	    {
		ahref = ahref.arg(QString::null);
	    }
	    t = t.insert( f, ahref );
	}
    }
    return t;
}

/*!
  Removes the unicode superscript link identifiers in \a lidText.
*/
QString QDL::removeLids( const QString &lidText )
{
    QString t;
    for (uint i = 0; i < lidText.length(); i++) {
	switch(lidText[i].unicode()) {
	    case u0:
	    case u1:
	    case u2: