#include <tdeimproxy.h>

Inherits TQObject, and KIMProxyIface.

Public Slots
void	registeredToDCOP (const TQCString &appId)

void	unregisteredFromDCOP (const TQCString &appId)

Signals
void	sigContactPresenceChanged (const TQString &uid)

void	sigPresenceInfoExpired ()

Public Member Functions
bool	initialize ()

TQStringList	allContacts ()

TQStringList	reachableContacts ()

TQStringList	onlineContacts ()

TQStringList	fileTransferContacts ()

bool	isPresent (const TQString &uid)

TQString	displayName (const TQString &uid)

int	presenceNumeric (const TQString &uid)

TQString	presenceString (const TQString &uid)

TQPixmap	presenceIcon (const TQString &uid)

bool	canReceiveFiles (const TQString &uid)

bool	canRespond (const TQString &uid)

TQString	locate (const TQString &contactId, const TQString &protocol)

TQString	context (const TQString &uid)

void	chatWithContact (const TQString &uid)

void	messageContact (const TQString &uid, const TQString &message)

void	sendFile (const TQString &uid, const KURL &sourceURL, const TQString &altFileName=TQString::null, uint fileSize=0)

bool	addContact (const TQString &contactId, const TQString &protocol)

bool	imAppsAvailable ()

bool	startPreferredApp ()

void	contactPresenceChanged (TQString uid, TQCString appId, int presence)

Static Public Member Functions
static KIMProxy *	instance (DCOPClient *client)

Protected Member Functions
void	pollApp (const TQCString &appId)

void	pollAll (const TQString &uid)

bool	updatePresence (const TQString &uid, const TQCString &appId, int presence)

TQString	preferredApp ()

KIMIface_stub *	stubForUid (const TQString &uid)

KIMIface_stub *	stubForProtocol (const TQString &protocol)

Friends
template<class >
class	KStaticDeleter

Detailed Description

Provides access to instant messenger programs which implement KDE's instant messanger interface KIMIface.

This class provides an easy-to-use interface to all running instant messengers or chat programs that implement KIMIface.

It works simultaneously with any running programs that implement the ServiceType DCOP/InstantMessenger.

IM-contacts are identified using unique identifier strings (UID) used by KDE's address book framework KABC. However the use of the address book API is optional, KIMProxy provides methods to fetch lists of available contact UIDs from the applications. 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.

The class is implemented as a singleton, so whenever you need access to one of its methods, just retrieve the single instance using instance(). The following code snippet demonstrated how to send a message to all reachable IM-contacts:

// get proxy instance
KIMProxy* proxy = KIMProxy::instance();
 
// check if there are suitable applications reachable
if (!proxy->initialize()) return;
 
TQString message = "Hi!\nHow are you on this wonderful day?";
 
// iterate over the list of reachable contacts
TQStringList reachableContacts = proxy->reachableContacts();
for (TQStringList::const_iterator it = reachableContacts.begin();
     it != reachableContacts.end(); ++it)
{
    proxy->messageContact(*it, message);
}

Note: While it is possible to communicate with each of those application's by DCOP using KIMProxy has the advantage of communicating with all applications simultaneously and thus getting an augmented view of availability, capability and presence (online status) of IM-contacts.

See also: KIMIface; TDEABC::AddressBook; TDEABC::Addressee

Since: 3.3

Author: Will Stephenson lists.nosp@m.@ste.nosp@m.vello.nosp@m..fre.nosp@m.e-onl.nosp@m.ine..nosp@m.co.uk

Definition at line 107 of file tdeimproxy.h.

Member Function Documentation

◆ addContact()

bool KIMProxy::addContact	(	const TQString &	contactId,
		const TQString &	protocol
	)

Add a new contact given its protocol specific identifier.

Parameters

contactId	the protocol specific identifier for the contact e.g. UIN for ICQ, screenname for AIM, nick for IRC
protocol	the IM protocol/service to use. See KIMIface:::protocols()

Returns: whether the add succeeded. false may signal already present, protocol not supported, or add operation not supported.

See also: locate(); KIMIface::protocols()

Definition at line 533 of file tdeimproxy.cpp.

◆ allContacts()

TQStringList KIMProxy::allContacts ( )

Obtain a list of IM-contacts known to IM-applications.

Returns a list of KABC UIDs gathered by merging the lists of each application the proxy can communicate with. The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

Returns: a list of KABC UIDs known to any IM-application

See also: reachableContacts(); onlineContacts(); fileTransferContacts(); isPresent(); TDEABC::Addressee::uid()

Definition at line 394 of file tdeimproxy.cpp.

◆ canReceiveFiles()

bool KIMProxy::canReceiveFiles ( const TQString & uid )

Indicate if a given contact can receive files.

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Parameters

uid	the KABC UID you want to the file transfer capability for

Returns: whether the specified contact can receive files

See also: fileTransferContacts(); TDEABC::Addressee::uid()

Definition at line 459 of file tdeimproxy.cpp.

◆ canRespond()

bool KIMProxy::canRespond ( const TQString & uid )

Indicate if a given contact will be able to respond.

Some media are unidirectional (e.g., sending SMS via a web interface). This refers to the contact's ability to respond as defined by the medium, not by their presence.

Someone may appear offline (SMS has no presence) to you but in fact be able to respond.

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Parameters

uid	the KABC UID you are interested in

Returns: whether the specified contact can respond

See also: isPresent(); TDEABC::Addressee::uid()

Definition at line 469 of file tdeimproxy.cpp.

◆ chatWithContact()

void KIMProxy::chatWithContact ( const TQString & uid )

Start a chat session with the specified contact.

Parameters

uid	the KABC UID you want to chat with

See also: messageContact(); sendFile(); isPresent(); reachableContacts(); TDEABC::Addressee::uid()

Definition at line 489 of file tdeimproxy.cpp.

◆ contactPresenceChanged()

void KIMProxy::contactPresenceChanged	(	TQString	uid,
		TQCString	appId,
		int	presence
	)

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

Definition at line 328 of file tdeimproxy.cpp.

◆ context()

TQString KIMProxy::context ( const TQString & uid )

Obtain the given contact's current context (home, work, or any)

Not all IM services/protocols support the concept of contexts. If the given UID maps to such a service, TQString::null will be returned

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Parameters

uid	the KABC UID you want the context for

Returns: a string describing the context, or TQString::null if not supported or if the contact is unknown

See also: isPresent(); TDEABC::Addressee::uid()

Definition at line 479 of file tdeimproxy.cpp.

◆ displayName()

TQString KIMProxy::displayName ( const TQString & uid )

Obtain the proxy's idea of the contact's display name.

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Useful if KABC lookups may be too slow.

Parameters

uid	the KABC UID you are interested in

Returns: the corresponding display name or TQString:null if the UID is unknown

See also: isPresent(); presenceString(); presenceNumeric(); TDEABC::Addressee::uid()

Definition at line 447 of file tdeimproxy.cpp.

◆ fileTransferContacts()

TQStringList KIMProxy::fileTransferContacts ( )

Obtain a list of IM-contacts who may receive file transfers.

Returned IM-contacts might not be capable of receiving file tranfers due to limitations of their clients or because they are behind a firewall. KIMProxy doesn't have the possibilities to discover this and will list them as well.

Returns a list of KABC UIDs gathered by merging the lists of each application the proxy can communicate with.

Returns: a list of KABC UIDs capable of file transfer

See also: allContacts(); reachableContacts(); onlineContacts(); canReceiveFiles(); TDEABC::Addressee::uid()

Definition at line 427 of file tdeimproxy.cpp.

◆ imAppsAvailable()

bool KIMProxy::imAppsAvailable ( )

Checks if there are any compatible instant messaging applications available.

Available means that they are started and registered with DCOP and implementing the correct DCOP service. This information will be updated on the first call to initialize() and whenever an application registers or unregisters with DCOP, i.e. the information will be kept up to date.

Returns: true if there are any apps available

Definition at line 553 of file tdeimproxy.cpp.

◆ initialize()

bool KIMProxy::initialize ( )

Get the proxy ready to connect.

Discover any running IM clients and setup communication handlers for them. The list of available clients is updated automatically through notification about added or removed DCOP applications as provided by DCOPClient.

It is safe to call this method more than once, initialization only occurs at the first time.

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

Definition at line 215 of file tdeimproxy.cpp.

◆ instance()

KIMProxy * KIMProxy::instance ( DCOPClient * client )

static

Obtain an instance of KIMProxy.

Creates a new instance if it is called for the first time. Call initialize() to check if there are applications available for communication.

Note: KIMProxy uses DCOPClient::setNotifications() to make sure it updates its information about IM applications it interacts with, e.g. that it gets notified about newly available applications or about applications exiting

Parameters

client your application's DCOP client

Returns: the singleton instance of this class

Definition at line 166 of file tdeimproxy.cpp.

◆ isPresent()

bool KIMProxy::isPresent ( const TQString & uid )

Confirm if a given contact is known to the proxy.

A contact is known to the proxy if it is know to at least one IM-application the proxy is communicating with.

The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

Parameters

uid	the KABC UID you are interested in

Returns: whether any IM-program knows of this KABC UID

See also: allContacts(); presenceString(); presenceNumeric(); TDEABC::Addressee::uid()

Definition at line 442 of file tdeimproxy.cpp.

◆ locate()

TQString KIMProxy::locate	(	const TQString &	contactId,
		const TQString &	protocol
	)

Obtain the KABC UID corresponding to the given IM address.

Parameters

contactId	the protocol specific identifier for the contact, e.g. UIN for ICQ, screenname for AIM, nick for IRC
protocol	the IM protocol/service to check. See KIMIface::protocols()

Returns: the KABC UID for the given contact or TQString::null if not found or either input stream was empty or the protocol is not supported

See also: KIMIface::protocols(); addContact(); isPresent(); TDEABC::Addressee::uid()

Definition at line 543 of file tdeimproxy.cpp.

◆ messageContact()

void KIMProxy::messageContact	(	const TQString &	uid,
		const TQString &	message
	)

Send a single message to the specified contact.

Any response will be handled by the IM client as a normal conversation.

Parameters

uid	the KABC UID you want to send the message to
message	the message text to send to the contact

See also: chatWithContact(); sendFile(); isPresent(); reachableContacts(); TDEABC::Addressee::uid()

Definition at line 502 of file tdeimproxy.cpp.

◆ onlineContacts()

TQStringList KIMProxy::onlineContacts ( )

Obtain a list of IM-contacts that are currently online.

Returns a list of KABC UIDs gathered by merging the lists of each application the proxy can communicate with. The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

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

See also: allContacts(); reachableContacts(); fileTransferContacts(); messageContact(); chatWithContact(); TDEABC::Addressee::uid()

Definition at line 415 of file tdeimproxy.cpp.

◆ pollAll()

void KIMProxy::pollAll ( const TQString & uid )

protected

Bootstrap our presence data by polling all known apps.

Definition at line 576 of file tdeimproxy.cpp.

◆ pollApp()

void KIMProxy::pollApp ( const TQCString & appId )

protected

Bootstrap our presence data for a newly registered app.

Definition at line 594 of file tdeimproxy.cpp.

◆ preferredApp()

TQString KIMProxy::preferredApp ( )

protected

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

Definition at line 644 of file tdeimproxy.cpp.

◆ presenceIcon()

TQPixmap KIMProxy::presenceIcon ( const TQString & uid )

Obtain the icon representing the IM presence for the specified contact.

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Note: The presence icon is chosen based on the numerical presence value returned by the applications. It currently does not return the presence icon used by the applications.

The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

Parameters

uid	the KABC UID you want the presence icon for

Returns: a pixmap representing the contact's presence or a null pixmap if the contact is unknown. See TQPixmap::isNull()

See also: isPresent(); presenceString(); presenceNumeric(); TDEABC::Addressee::uid()

Definition at line 373 of file tdeimproxy.cpp.

◆ presenceNumeric()

int KIMProxy::presenceNumeric ( const TQString & uid )

Obtain the IM presence as a number for the specified contact.

Returns one of the following values depending on the given contact's presence:

0 - Unknown: for contacts where you can not use any of the other values
1 - Offline: for contacts that are offline, i.e. not connected to their IM-service.
2 - Connecting
3 - Away: for contacts that are connected to their IM-service but not Online
4 - Online

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

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). Returns 0 if the given UID is unknown

See also: isPresent(); presenceString(); presenceIcon(); KIMIface::presenceStatus(); TDEABC::Addressee::uid()

Definition at line 346 of file tdeimproxy.cpp.

◆ presenceString()

TQString KIMProxy::presenceString ( const TQString & uid )

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

The presence string is one of the following:

i18n("Unknown")
i18n("Offline")
i18n("Connecting")
i18n("Away")
i18n("Online")

If the given KABC UID is known to more than one IM-application the result of the application which has the best presence for the contact is taken. For example if a contact is Online on ICQ and Away on AIM, the value returned by the application providing ICQ is taken.

Note: The presence string is created based on the numerical presence value returned by the applications. It currently does not return the presence strings used by the applications.

The method uses cached information to make it fast and not require actually communicating with the applications every time it is called.

Parameters

uid	the KABC UID you want the presence for

Returns: the i18ned string describing the contact's presence or TQString::null if the UID is unknown

See also: isPresent(); presenceNumeric(); presenceIcon(); TDEABC::Addressee::uid()

Definition at line 358 of file tdeimproxy.cpp.

◆ reachableContacts()

TQStringList KIMProxy::reachableContacts ( )

Obtain a list of IM-contacts that are currently reachable.

Returns a list of KABC UIDs gathered by merging the lists of each application the proxy can communicate with.

Returns: a list of KABC UIDs who can receive a message, even if offline

See also: allContacts(); onlineContacts(); fileTransferContacts(); messageContact(); TDEABC::Addressee::uid()

Definition at line 400 of file tdeimproxy.cpp.

◆ registeredToDCOP

void KIMProxy::registeredToDCOP ( const TQCString & appId )

slot

Updates the proxy's data after a new application registered with DCOP.

Checks if the application specified by the given DCOP application identifier implements the instant messenger service.

Parameters

appId the DCOP application ID of the newly registered application

See also: DCOPClient::applicationRegistered()

Definition at line 266 of file tdeimproxy.cpp.

◆ sendFile()

void KIMProxy::sendFile	(	const TQString &	uid,
		const KURL &	sourceURL,
		const TQString &	altFileName = `TQString::null`,
		uint	fileSize = `0`
	)

Send a file to the contact.

Initiates a file transfer with the given contact if possible.

Parameters

uid	the KABC UID you want to send to
sourceURL	a KURL pointing to the file to send
altFileName	an alternate filename describing the file or a description or title
fileSize	file size in bytes

See also: messageContact(); chatWithContact(); isPresent(); fileTransferContacts(); TDEABC::Addressee::uid()

Definition at line 515 of file tdeimproxy.cpp.

◆ sigContactPresenceChanged

void KIMProxy::sigContactPresenceChanged ( const TQString & uid )

signal

Indicates that the specified IM-contact's presence changed.

Parameters

uid	the KABC UID whose presence changed

See also: isPresent(); presenceNumeric(); presenceIcon(); TDEABC::Addressee::uid()

◆ sigPresenceInfoExpired

void KIMProxy::sigPresenceInfoExpired ( )

signal

Indicates that presence information obtained earlier on might not be valid any longer.

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

◆ startPreferredApp()

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 558 of file tdeimproxy.cpp.

◆ stubForProtocol()

KIMIface_stub * KIMProxy::stubForProtocol ( const TQString & protocol )

protected

Get the app stub for this protocol.

Take the preferred app first, then any other.

Definition at line 624 of file tdeimproxy.cpp.

◆ stubForUid()

KIMIface_stub * KIMProxy::stubForUid ( const TQString & uid )

protected

Get the app stub best able to reach this uid.

Definition at line 616 of file tdeimproxy.cpp.

◆ unregisteredFromDCOP

void KIMProxy::unregisteredFromDCOP ( const TQCString & appId )

slot

Updates the proxy's data after an application unregistered with DCOP.

If the application specified by the given DCOP application identifier is one of the instant messenger applications of the proxy, it will remove the presence information it gathered from it earlier on.

Emits sigPresenceInfoExpired() to let the using applcation know its presence related information might need updating.

Parameters

appId the DCOP application ID of the now unregistered application

See also: DCOPClient::applicationRemoved()

Definition at line 301 of file tdeimproxy.cpp.

◆ updatePresence()

bool KIMProxy::updatePresence	(	const TQString &	uid,
		const TQCString &	appId,
		int	presence
	)

protected

Update our records with the given data.

Friends And Related Function Documentation

◆ KStaticDeleter

template<class >

friend class KStaticDeleter

friend

Definition at line 112 of file tdeimproxy.h.

The documentation for this class was generated from the following files:

interfaces/tdeimproxy/library

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Function Documentation

◆ addContact()

◆ allContacts()

◆ canReceiveFiles()

◆ canRespond()

◆ chatWithContact()

◆ contactPresenceChanged()

◆ context()

◆ displayName()

◆ fileTransferContacts()

◆ imAppsAvailable()

◆ initialize()

◆ instance()

◆ isPresent()

◆ locate()

◆ messageContact()

◆ onlineContacts()

◆ pollAll()

◆ pollApp()

◆ preferredApp()

◆ presenceIcon()

◆ presenceNumeric()

◆ presenceString()

◆ reachableContacts()

◆ registeredToDCOP

◆ sendFile()

◆ sigContactPresenceChanged

◆ sigPresenceInfoExpired

◆ startPreferredApp()

◆ stubForProtocol()

◆ stubForUid()

◆ unregisteredFromDCOP

◆ updatePresence()

Friends And Related Function Documentation

◆ KStaticDeleter

interfaces/tdeimproxy/library

interfaces/tdeimproxy/library