libkdepim Library API Documentation

KIMProxy Class Reference

This class provides an easy-to-use interface to any instant messengers or chat programs that you have installed that implement KIMIface. More...

#include <kimproxy.h>

Inheritance diagram for KIMProxy:

Inheritance graph
[legend]
Collaboration diagram for KIMProxy:

Collaboration graph
[legend]
List of all members.

Public Slots

void registeredToDCOP (const QCString &appId)
void unregisteredFromDCOP (const QCString &appId)

Signals

void sigContactPresenceChanged (const QString &uid)
void sigPresenceInfoExpired ()

Public Member Functions

bool initialize ()
QStringList allContacts ()
QStringList reachableContacts ()
QStringList onlineContacts ()
QStringList fileTransferContacts ()
bool isPresent (const QString &uid)
QString displayName (const QString &uid)
int presenceNumeric (const QString &uid)
QString presenceString (const QString &uid)
QPixmap presenceIcon (const QString &uid)
bool canReceiveFiles (const QString &uid)
bool canRespond (const QString &uid)
QString locate (const QString &contactId, const QString &protocol)
QString context (const QString &uid)
void chatWithContact (const QString &uid)
void messageContact (const QString &uid, const QString &message)
void sendFile (const QString &uid, const KURL &sourceURL, const QString &altFileName=QString::null, uint fileSize=0)
bool addContact (const QString &contactId, const QString &protocol)
bool imAppsAvailable ()
bool startPreferredApp ()
void contactPresenceChanged (QString uid, QCString appId, int presence)

Static Public Member Functions

static KIMProxyinstance (DCOPClient *client)

Protected Member Functions

void pollAll (const QString &uid)
bool updatePresence (const QString &uid, const QCString &appId, int presence)
QString preferredApp ()
KIMIface_stub * stubForUid (const QString &uid)
KIMIface_stub * stubForProtocol (const QString &protocol)

Friends

class KStaticDeleter

Detailed Description

This class provides an easy-to-use interface to any instant messengers or chat programs that you have installed that implement KIMIface.

It works simultaneously with any running programs that implement the ServiceType DCOP/InstantMessenger If a UID is reachable with more than one program, KIMProxy aggregates the available information and presents the 'best' presence. For example, for a contact who can be seen to be Away in IRC on program A but Online using ICQ on program B, the information from program B will be used. KIMProxy is designed for simple information in a wide number of cases, not for detailed messaging.

Most operations work in terms of uids belonging to KABC::Addressee, but use of the address book is optional. You can get a list of known contacts with imAddresseeUids and then check their presence using the various accessor methods presenceString, presenceNumeric and display the IM programs' display names for them using displayName.

To use, just get an instance using instance.

Since:
3.3
Author:
Will Stephenson <lists@stevello.free-online.co.uk>

Definition at line 68 of file kimproxy.h.


Member Function Documentation

KIMProxy * KIMProxy::instance DCOPClient *  client  )  [static]
 

Obtain an instance of KIMProxy.

Note, if you share this DCOPClient with your own app, that kimproxy uses DCOPClient::setNotifications() to make sure it updates its information when the IM application it is interfacing to exits.

Parameters:
client your app's DCOP client.
Returns:
The singleton instance of this class.

Definition at line 85 of file kimproxy.cpp.

bool KIMProxy::initialize  ) 
 

Get the proxy ready to connect Discover any running preferred IM clients and set up stubs for it.

Returns:
whether the proxy is ready to use. False if there are no apps running.

Definition at line 124 of file kimproxy.cpp.

Referenced by addContact(), allContacts(), canReceiveFiles(), canRespond(), chatWithContact(), context(), displayName(), fileTransferContacts(), isPresent(), locate(), messageContact(), onlineContacts(), presenceIcon(), presenceNumeric(), presenceString(), reachableContacts(), and sendFile().

QStringList KIMProxy::allContacts  ) 
 

Obtain a list of IM-contactable entries in the KDE address book.

Returns:
a list of KABC uids.

Definition at line 174 of file kimproxy.cpp.

References initialize().

QStringList KIMProxy::reachableContacts  ) 
 

Obtain a list of KDE address book entries who are currently reachable.

Returns:
a list of KABC uids who can receive a message, even if online.

Definition at line 189 of file kimproxy.cpp.

References initialize().

QStringList KIMProxy::onlineContacts  ) 
 

Obtain a list of KDE address book entries who are currently online.

Returns:
a list of KABC uids who are online with unspecified presence.

Definition at line 204 of file kimproxy.cpp.

References initialize().

QStringList KIMProxy::fileTransferContacts  ) 
 

Obtain a list of KDE address book entries who may receive file transfers.

Returns:
a list of KABC uids capable of file transfer.

Definition at line 219 of file kimproxy.cpp.

References initialize().

bool KIMProxy::isPresent const QString uid  ) 
 

Confirm if a given KABC uid is known to KIMProxy.

Parameters:
uid the KABC uid you are interested in.
Returns:
whether one of the chat programs KIMProxy talks to knows of this KABC uid.

Definition at line 234 of file kimproxy.cpp.

References initialize().

QString KIMProxy::displayName const QString uid  ) 
 

Obtain the IM app's idea of the contact's display name Useful if KABC lookups may be too slow.

Parameters:
KABC uid.
Returns:
The corresponding display name.

Definition at line 252 of file kimproxy.cpp.

References initialize(), and stubForUid().

int KIMProxy::presenceNumeric const QString uid  ) 
 

Obtain the IM presence as a number (see KIMIface) for the specified addressee.

Parameters:
uid the KABC uid you want the presence for.
Returns:
a numeric representation of presence - currently one of 0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online)

Definition at line 264 of file kimproxy.cpp.

References initialize(), and pollAll().

Referenced by presenceIcon(), and presenceString().

QString KIMProxy::presenceString const QString uid  ) 
 

Obtain the IM presence as a i18ned string for the specified addressee.

Parameters:
uid the KABC uid you want the presence for.
Returns:
the i18ned string describing presence.

Definition at line 277 of file kimproxy.cpp.

References initialize(), presenceNumeric(), and stubForUid().

QPixmap KIMProxy::presenceIcon const QString uid  ) 
 

Obtain the icon representing IM presence for the specified addressee.

Parameters:
uid the KABC uid you want the presence for.
Returns:
a pixmap representing the uid's presence.

Definition at line 306 of file kimproxy.cpp.

References initialize(), pollAll(), presenceNumeric(), and stubForUid().

bool KIMProxy::canReceiveFiles const QString uid  ) 
 

Indicate if a given uid can receive files.

Parameters:
uid the KABC uid you are interested in.
Returns:
Whether the specified addressee can receive files.

Definition at line 332 of file kimproxy.cpp.

References initialize(), and stubForUid().

bool KIMProxy::canRespond const QString uid  ) 
 

Some media are unidirectional (eg, sending SMS via a web interface).

Parameters:
uid the KABC uid you are interested in.
Returns:
Whether the specified addressee can respond.

Definition at line 342 of file kimproxy.cpp.

References initialize(), and stubForUid().

QString KIMProxy::locate const QString contactId,
const QString protocol
 

Get the KABC uid corresponding to the supplied IM address Protocols should be.

Parameters:
contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol",
Returns:
a KABC uid or null if none found/

Definition at line 409 of file kimproxy.cpp.

References initialize(), and stubForProtocol().

QString KIMProxy::context const QString uid  ) 
 

Get the supplied addressee's current context (home, work, or any).

Parameters:
uid the KABC uid you want the context for.
Returns:
A QString describing the context, or null if not supported.

Definition at line 352 of file kimproxy.cpp.

References initialize(), and stubForUid().

void KIMProxy::chatWithContact const QString uid  ) 
 

Start a chat session with the specified addressee.

Parameters:
uid the KABC uid you want to chat with.

Definition at line 362 of file kimproxy.cpp.

References initialize(), and stubForUid().

void KIMProxy::messageContact const QString uid,
const QString message
 

Send a single message to the specified addressee Any response will be handled by the IM client as a normal conversation.

Parameters:
uid the KABC uid you want to chat with.
message the message to send them.

Definition at line 372 of file kimproxy.cpp.

References initialize(), and stubForUid().

void KIMProxy::sendFile const QString uid,
const KURL &  sourceURL,
const QString altFileName = QString::null,
uint  fileSize = 0
 

Send the file to the contact.

Parameters:
uid the KABC uid you are sending to.
sourceURL a KURL to send.
altFileName an alternate filename describing the file
fileSize file size in bytes

Definition at line 382 of file kimproxy.cpp.

References initialize().

bool KIMProxy::addContact const QString contactId,
const QString protocol
 

Add a contact to the contact list.

Parameters:
contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol",
Returns:
whether the add succeeded. False may signal already present, protocol not supported, or add operation not supported.

Definition at line 399 of file kimproxy.cpp.

References initialize(), and stubForProtocol().

bool KIMProxy::imAppsAvailable  ) 
 

Are there any compatible instant messaging apps installed?

Returns:
true if there are any apps installed, to see if they are running, initialize instead.

Definition at line 419 of file kimproxy.cpp.

bool KIMProxy::startPreferredApp  ) 
 

Start the user's preferred IM application.

Returns:
whether a preferred app was found. No guarantee that it started correctly

Definition at line 425 of file kimproxy.cpp.

References preferredApp().

void KIMProxy::contactPresenceChanged QString  uid,
QCString  appId,
int  presence
 

Just exists to let the idl compiler make the DCOP signal for this.

Definition at line 504 of file kimproxy.cpp.

References sigContactPresenceChanged(), and updatePresence().

void KIMProxy::sigContactPresenceChanged const QString uid  )  [signal]
 

Indicates that the specified UID's presence changed.

Parameters:
uid the KABC uid whose presence changed.

Referenced by contactPresenceChanged().

void KIMProxy::sigPresenceInfoExpired  )  [signal]
 

Indicates that the sources of presence information have changed so any previously supplied presence info is invalid.

void KIMProxy::pollAll const QString uid  )  [protected]
 

Bootstrap our presence data by polling all known apps.

Definition at line 538 of file kimproxy.cpp.

Referenced by presenceIcon(), presenceNumeric(), and stubForUid().

bool KIMProxy::updatePresence const QString uid,
const QCString appId,
int  presence
[protected]
 

Update our records with the given data.

Definition at line 512 of file kimproxy.cpp.

Referenced by contactPresenceChanged().

QString KIMProxy::preferredApp  )  [protected]
 

Get the name of the user's IM weapon of choice.

Definition at line 589 of file kimproxy.cpp.

Referenced by startPreferredApp(), and stubForProtocol().

KIMIface_stub * KIMProxy::stubForUid const QString uid  )  [protected]
 

Get the app stub best able to reach this uid.

Definition at line 556 of file kimproxy.cpp.

References pollAll().

Referenced by canReceiveFiles(), canRespond(), chatWithContact(), context(), displayName(), messageContact(), presenceIcon(), and presenceString().

KIMIface_stub * KIMProxy::stubForProtocol const QString protocol  )  [protected]
 

Get the app stub for this protocol.

Take the preferred app first, then any other.

Definition at line 569 of file kimproxy.cpp.

References preferredApp().

Referenced by addContact(), and locate().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for libkdepim Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Aug 2 09:53:38 2007 by doxygen 1.4.2 written by Dimitri van Heesch, © 1997-2003