#include <kimiface.h>

Inheritance diagram for KIMIface:

Public Attributes
k_dcop_signals	__pad0__: void contactPresenceChanged( TQString uid

k_dcop_signals TQCString	appId

k_dcop_signals TQCString int	presence

Additional Inherited Members
Public Member Functions inherited from DCOPObject
	DCOPObject (TQObject *obj)

	DCOPObject (const TQCString &objId)

TQCString	objId () const

bool	setObjId (const TQCString &objId)

virtual bool	process (const TQCString &fun, const TQByteArray &data, TQCString &replyType, TQByteArray &replyData)

virtual bool	processDynamic (const TQCString &fun, const TQByteArray &data, TQCString &replyType, TQByteArray &replyData)

virtual QCStringList	functionsDynamic ()

virtual QCStringList	interfacesDynamic ()

virtual QCStringList	interfaces ()

virtual QCStringList	functions ()

void	emitDCOPSignal (const TQCString &signal, const TQByteArray &data)

bool	connectDCOPSignal (const TQCString &sender, const TQCString &senderObj, const TQCString &signal, const TQCString &slot, bool Volatile)

bool	disconnectDCOPSignal (const TQCString &sender, const TQCString &senderObj, const TQCString &signal, const TQCString &slot)

DCOPClient *	callingDcopClient ()

Static Public Member Functions inherited from DCOPObject
static bool	hasObject (const TQCString &objId)

static DCOPObject *	find (const TQCString &objId)

static TQPtrList< DCOPObject >	match (const TQCString &partialId)

static TQCString	objectName (TQObject *obj)

Detailed Description

Generic DCOP interface for KDE instant messenger applications.

The interface has two parts:

methods to get information about IM-contacts, such as their reachability or their presence status (if the are online or away, etc)
methods to initiate communication with IM-contacts, e.g. sending messages

Note: If you are looking for a information about accessing application's that implement this interface, have a look at the KIMProxy class.

Contacts are identified using unique identifier strings (UID) used by KABC, the KDE address book library. The UID generation is handled by TDEABC::Addressee so the your application will either have to access the address book or provide a possibility for associating a contact of your application with an entry of the address book.

Note: one omission of this interface is the lack of control over the range of values used for protocols' names.

If you are implementing this interface, note that your application must have the following information in its desktop file, so that it can be identified as providing KIMIface at runtime:

X-DCOP-ServiceName=<application-name>

ServiceTypes=DCOP/InstantMessenger

and the class implementing KIMIface must pass "KIMIface" to the DCOPObject constructor:

// just need TQObject inheritance and TQ_OBJECT if you want signals and slots
// no need to use K_DCOP macro again
 
class MyIMIface : public TQObject, public KIMIface
{
    TQ_OBJECT
public:
   MyIMIface(TQObject* parent = 0, const char* name) :
       DCOPObject("KIMIface"), // <-- passing the interface name as required
       TQObject(parent, name) {}
};

The DCOP part of the interface needs to be processed by the DCOP IDL compiler. The KDE autotools framework will do this automatically, all you have to do is add kimiface.skel and kimiface.stub to the SOURCES list in your Makefile.am

See also: KIMProxy; 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 85 of file kimiface.h.

Member Function Documentation

◆ addContact

virtual bool KIMIface::addContact	(	const TQString &	contactId,
		const TQString &	protocol
	)

pure virtual

Add a new contact given its protocol specific identifier.

Implementations might add the contact silently, including sending an authorization request if necessary, ask the user for confirmation or just prefill the usual contact addingGUI.

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 protocols()

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

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

◆ allContacts

virtual TQStringList KIMIface::allContacts ( )

pure virtual

Obtain a list of IM-contacts that are known to the application.

Return a list of KABC UIDs of all the contacts you have such IDs for.

Returns: a list of KABC UIDs known to the application

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

◆ canReceiveFiles

virtual bool KIMIface::canReceiveFiles ( const TQString & uid )

pure virtual

Indicate if a given contact can receive files.

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()

◆ canRespond

virtual bool KIMIface::canRespond ( const TQString & uid )

pure virtual

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.

Parameters

uid	the KABC UID you are interested in

Returns: whether the specified contact can respond

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

◆ chatWithContact

virtual void KIMIface::chatWithContact ( const TQString & uid )

pure virtual

Start a chat session with the specified contact.

Applications that do not support a chat mode or when the IM-service of the given contact does not support it, this can also open a normal message input GUI.

Parameters

uid	the KABC UID you want to chat with

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

◆ context

virtual TQString KIMIface::context ( const TQString & uid )

pure virtual

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, just return TQString::null

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()

◆ displayName

virtual TQString KIMIface::displayName ( const TQString & uid )

pure virtual

Obtain the IM app's idea of the contact's display name.

Useful if KABC lookups may be too slow. Should return whatever the application uses in its contact list or similar GUI, e.g. a nick name, a user configured name string, etc.

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(); presenceStatus(); TDEABC::Addressee::uid()

◆ fileTransferContacts

virtual TQStringList KIMIface::fileTransferContacts ( )

pure virtual

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

Return a list of KABC UIDs of the contacts that are capable of receiving file transfers based on the IM-service they are associated with, i.e. if it is technically able to provide this, on their online state, i.e. can likely not receive files while offline, and perhaps even information your application has additionally, e.g. a user config that tells you that the contact is behind a firewall.

The simplest implementation is to return the same list as onlineContacts(), provided all the IM-services that are currently used support it.

Returns: a list of KABC UIDs capable of file transfer

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

◆ icon

virtual TQPixmap KIMIface::icon ( const TQString & uid )

pure virtual

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

Return the image the application would use to display a contact's presence. The size and other properties of the image are currently unspecified.

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(); presenceStatus(); TDEABC::Addressee::uid()

◆ isPresent

virtual bool KIMIface::isPresent ( const TQString & uid )

pure virtual

Confirm if a given contact is known to the IM application.

Check if you can map the given KABC UID to one if the IM-contacts, e.g. the would be part of the list returned by allContacts()

Parameters

uid	the KABC UID you are interested in

Returns: whether the program knows of this KABC UID

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

◆ locate

virtual TQString KIMIface::locate	(	const TQString &	contactId,
		const TQString &	protocol
	)

pure virtual

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 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: protocols(); addContact(); isPresent(); TDEABC::Addressee::uid()

◆ messageContact

virtual void KIMIface::messageContact	(	const TQString &	uid,
		const TQString &	message
	)

pure virtual

Send a single message to the specified contact.

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

Implementations might send the message silently, ask the user for permission or just prefill the usual message input GUI.

Note: As sending any text could potentially be a breach of the user's privacy it is recommended to let the user know about it.

Parameters

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

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

◆ messageNewContact

virtual void KIMIface::messageNewContact	(	const TQString &	contactId,
		const TQString &	protocol
	)

pure virtual

Send a single message to a contact given only its protocol specific identifier.

This could be used to send a message without having to know the KABC UID of the contact or without having to add it first.

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 protocols()

See also: messageContact(); chatWithContact(); sendFile(); locate(); protocols(); addContact()

◆ onlineContacts

virtual TQStringList KIMIface::onlineContacts ( )

pure virtual

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

Return a list of KABC UIDs of the contacts you have any presence information for that indicates that they are connected to the IM-service they are associated with.

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

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

◆ presenceStatus

virtual int KIMIface::presenceStatus ( const TQString & uid )

pure virtual

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

Return 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. If the application itself or the IM-service for the given contact is offline return Unknown instead
2 - Connecting
3 - Away: for contacts that are connected to their IM-service but not Online
4 - Online

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(); TDEABC::Addressee::uid()

◆ presenceString

virtual TQString KIMIface::presenceString ( const TQString & uid )

pure virtual

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

Return a translated string your application would use when displaying the contact's presence, e.g. i18n("Online"), i18n("Away")

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(); presenceStatus(); TDEABC::Addressee::uid()

◆ protocols

virtual TQStringList KIMIface::protocols ( )

pure virtual

Obtain a list of supported IM services/protocols.

Protocol names are currently of the form "protocol name" + "Protocol" for example:

AIMProtocol: AOL instant messenger protocol
MSNProtocol: Microsoft messanger protocol
ICQProtocol: AOL (Mirabilis) ICQ protocol
....

The string is currently just an identifier to use with methods such as locate(), addContact() or messageNewContact()

Returns: the set of protocols that the application supports

See also: locate(); addContact(); messageNewContact

◆ reachableContacts

virtual TQStringList KIMIface::reachableContacts ( )

pure virtual

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

Return a list of KABC UIDs of the contacts that are reachable in the sense that you are connected to the IM-service they are associated with.

For example if your application supports ICQ and AIM and the ICQ account is active but the AIM account isn't, return just the ICQ contacts.

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

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

◆ sendFile

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

pure virtual

Send a file to the contact.

Initiates a file transfer with the given contact if possible.

Implementations might start the transfer right away, ask the user's permission or just prefill the usual file transfer GUI.

Note: As sending any file could potentially be a breach of the user's privacy it is recommended to let the user know about it.

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(); messageNewContact(); chatWithContact(); isPresent(); fileTransferContacts(); TDEABC::Addressee::uid()

Member Data Documentation

◆ pad0

k_dcop_signals KIMIface::__pad0__

Definition at line 466 of file kimiface.h.

◆ appId

k_dcop_signals TQCString KIMIface::appId

Definition at line 485 of file kimiface.h.

◆ presence

k_dcop_signals TQCString int KIMIface::presence

Definition at line 485 of file kimiface.h.

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

kimiface.h

interfaces

Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addContact

◆ allContacts

◆ canReceiveFiles

◆ canRespond

◆ chatWithContact

◆ context

◆ displayName

◆ fileTransferContacts

◆ icon

◆ isPresent

◆ locate

◆ messageContact

◆ messageNewContact

◆ onlineContacts

◆ presenceStatus

◆ presenceString

◆ protocols

◆ reachableContacts

◆ sendFile

Member Data Documentation

◆ __pad0__

◆ appId

◆ presence

interfaces

interfaces

◆ pad0