.TH "KIMProxy" kde3 "11 Jun 2005" "Version Version 3.4.1" "interfaces Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KIMProxy \- This class provides an easy-to-use interface to any instant messengers or chat programs that you have installed that implement.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kimproxy.h>\fP
.PP
Inherits \fBQObject\fP, and KIMProxyIface.
.PP
.SS "Public Slots"

.in +1c
.ti -1c
.RI "void \fBregisteredToDCOP\fP (const \fBQCString\fP &appId)"
.br
.ti -1c
.RI "void \fBunregisteredFromDCOP\fP (const \fBQCString\fP &appId)"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBsigContactPresenceChanged\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "void \fBsigPresenceInfoExpired\fP ()"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "bool \fBinitialize\fP ()"
.br
.ti -1c
.RI "\fBQStringList\fP \fBallContacts\fP ()"
.br
.ti -1c
.RI "\fBQStringList\fP \fBreachableContacts\fP ()"
.br
.ti -1c
.RI "\fBQStringList\fP \fBonlineContacts\fP ()"
.br
.ti -1c
.RI "\fBQStringList\fP \fBfileTransferContacts\fP ()"
.br
.ti -1c
.RI "bool \fBisPresent\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "\fBQString\fP \fBdisplayName\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "int \fBpresenceNumeric\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "\fBQString\fP \fBpresenceString\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "\fBQPixmap\fP \fBpresenceIcon\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "bool \fBcanReceiveFiles\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "bool \fBcanRespond\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "\fBQString\fP \fBlocate\fP (const \fBQString\fP &contactId, const \fBQString\fP &protocol)"
.br
.ti -1c
.RI "\fBQString\fP \fBcontext\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "void \fBchatWithContact\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "void \fBmessageContact\fP (const \fBQString\fP &uid, const \fBQString\fP &message)"
.br
.ti -1c
.RI "void \fBsendFile\fP (const \fBQString\fP &uid, const \fBKURL\fP &sourceURL, const \fBQString\fP &altFileName=QString::null, uint fileSize=0)"
.br
.ti -1c
.RI "bool \fBaddContact\fP (const \fBQString\fP &contactId, const \fBQString\fP &protocol)"
.br
.ti -1c
.RI "bool \fBimAppsAvailable\fP ()"
.br
.ti -1c
.RI "bool \fBstartPreferredApp\fP ()"
.br
.ti -1c
.RI "void \fBcontactPresenceChanged\fP (\fBQString\fP uid, \fBQCString\fP appId, int presence)"
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static \fBKIMProxy\fP * \fBinstance\fP (\fBDCOPClient\fP *client)"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "void \fBpollApp\fP (const \fBQCString\fP &appId)"
.br
.ti -1c
.RI "void \fBpollAll\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "bool \fBupdatePresence\fP (const \fBQString\fP &uid, const \fBQCString\fP &appId, int presence)"
.br
.ti -1c
.RI "\fBQString\fP \fBpreferredApp\fP ()"
.br
.ti -1c
.RI "KIMIface_stub * \fBstubForUid\fP (const \fBQString\fP &uid)"
.br
.ti -1c
.RI "KIMIface_stub * \fBstubForProtocol\fP (const \fBQString\fP &protocol)"
.br
.in -1c
.SH "Detailed Description"
.PP 
This class provides an easy-to-use interface to any instant messengers or chat programs that you have installed that implement. 

\fBSee also:\fP
.RS 4
\fBKIMIface\fP
.RE
.PP
It works simultaneously with any running programs that implement the 
.PP
\fBSee also:\fP
.RS 4
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.
.RE
.PP
Most operations work in terms of uids belonging to 
.PP
\fBSee also:\fP
.RS 4
KABC::Addressee, but use of the address book is optional. You can get a list of known contacts with 
.PP
imAddresseeUids and then check their presence using the various accessor methods 
.PP
\fBpresenceString\fP, 
.PP
\fBpresenceNumeric\fP and display the IM programs' display names for them using 
.PP
\fBdisplayName\fP.
.RE
.PP
To use, just get an instance using \fBinstance\fP.
.PP
\fBSince:\fP
.RS 4
3.3 
.RE
.PP
\fBAuthor:\fP
.RS 4
Will Stephenson <lists@stevello.free-online.co.uk> 
.RE
.PP

.PP
Definition at line 71 of file kimproxy.h.
.SH "Member Function Documentation"
.PP 
.SS "\fBKIMProxy\fP * KIMProxy::instance (\fBDCOPClient\fP * client)\fC [static]\fP"
.PP
Obtain an instance of KIMProxy. 
.PP
Note, if you share this 
.PP
\fBSee also:\fP
.RS 4
\fBDCOPClient\fP with your own app, that kimproxy uses \fBDCOPClient::setNotifications()\fP to make sure it updates its information when the IM application it is interfacing to exits. 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIclient\fP your app's DCOP client. 
.RE
.PP
\fBReturns:\fP
.RS 4
The singleton instance of this class.
.RE
.PP

.PP
Definition at line 166 of file kimproxy.cpp.
.PP
References KStaticDeleter< type >::setObject().
.SS "bool KIMProxy::initialize ()"
.PP
Get the proxy ready to connect Discover any running preferred IM clients and set up stubs for it. 
.PP
\fBReturns:\fP
.RS 4
whether the proxy is ready to use. False if there are no apps running.
.RE
.PP

.PP
Definition at line 215 of file kimproxy.cpp.
.PP
References endl(), QDict::find(), QDict::insert(), QDict::isEmpty(), QCString::isEmpty(), kdDebug(), QString::latin1(), QString::left(), QCString::length(), pollApp(), and KShortcut::toString().
.PP
Referenced by addContact(), canReceiveFiles(), canRespond(), chatWithContact(), context(), displayName(), fileTransferContacts(), locate(), messageContact(), presenceIcon(), presenceNumeric(), presenceString(), reachableContacts(), and sendFile().
.SS "\fBQStringList\fP KIMProxy::allContacts ()"
.PP
Obtain a list of IM-contactable entries in the \fBKDE\fP address book. 
.PP
\fBReturns:\fP
.RS 4
a list of KABC uids.
.RE
.PP

.PP
Definition at line 394 of file kimproxy.cpp.
.SS "\fBQStringList\fP KIMProxy::reachableContacts ()"
.PP
Obtain a list of \fBKDE\fP address book entries who are currently reachable. 
.PP
\fBReturns:\fP
.RS 4
a list of KABC uids who can receive a message, even if online.
.RE
.PP

.PP
Definition at line 400 of file kimproxy.cpp.
.PP
References QDictIterator::current(), and initialize().
.SS "\fBQStringList\fP KIMProxy::onlineContacts ()"
.PP
Obtain a list of \fBKDE\fP address book entries who are currently online. 
.PP
\fBReturns:\fP
.RS 4
a list of KABC uids who are online with unspecified presence.
.RE
.PP

.PP
Definition at line 415 of file kimproxy.cpp.
.SS "\fBQStringList\fP KIMProxy::fileTransferContacts ()"
.PP
Obtain a list of \fBKDE\fP address book entries who may receive file transfers. 
.PP
\fBReturns:\fP
.RS 4
a list of KABC uids capable of file transfer.
.RE
.PP

.PP
Definition at line 427 of file kimproxy.cpp.
.PP
References QDictIterator::current(), and initialize().
.SS "bool KIMProxy::isPresent (const \fBQString\fP & uid)"
.PP
Confirm if a given KABC uid is known to KIMProxy. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you are interested in. 
.RE
.PP
\fBReturns:\fP
.RS 4
whether one of the chat programs KIMProxy talks to knows of this KABC uid.
.RE
.PP

.PP
Definition at line 442 of file kimproxy.cpp.
.SS "\fBQString\fP KIMProxy::displayName (const \fBQString\fP & uid)"
.PP
Obtain the IM app's idea of the contact's display name Useful if KABC lookups may be too slow. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you are interested in. 
.RE
.PP
\fBReturns:\fP
.RS 4
The corresponding display name.
.RE
.PP

.PP
Definition at line 447 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "int KIMProxy::presenceNumeric (const \fBQString\fP & uid)"
.PP
Obtain the IM presence as a number (see \fBKIMIface\fP) for the specified addressee. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want the presence for. 
.RE
.PP
\fBReturns:\fP
.RS 4
a numeric representation of presence - currently one of 0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online)
.RE
.PP

.PP
Definition at line 346 of file kimproxy.cpp.
.PP
References initialize().
.SS "\fBQString\fP KIMProxy::presenceString (const \fBQString\fP & uid)"
.PP
Obtain the IM presence as a i18ned string for the specified addressee. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want the presence for. 
.RE
.PP
\fBReturns:\fP
.RS 4
the i18ned string describing presence.
.RE
.PP

.PP
Definition at line 358 of file kimproxy.cpp.
.PP
References initialize().
.SS "\fBQPixmap\fP KIMProxy::presenceIcon (const \fBQString\fP & uid)"
.PP
Obtain the icon representing IM presence for the specified addressee. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want the presence for. 
.RE
.PP
\fBReturns:\fP
.RS 4
a pixmap representing the uid's presence.
.RE
.PP

.PP
Definition at line 373 of file kimproxy.cpp.
.PP
References initialize().
.SS "bool KIMProxy::canReceiveFiles (const \fBQString\fP & uid)"
.PP
Indicate if a given uid can receive files. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you are interested in. 
.RE
.PP
\fBReturns:\fP
.RS 4
Whether the specified addressee can receive files.
.RE
.PP

.PP
Definition at line 459 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "bool KIMProxy::canRespond (const \fBQString\fP & uid)"
.PP
Some media are unidirectional (eg, sending SMS via a web interface). 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you are interested in. 
.RE
.PP
\fBReturns:\fP
.RS 4
Whether the specified addressee can respond.
.RE
.PP

.PP
Definition at line 469 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "\fBQString\fP KIMProxy::locate (const \fBQString\fP & contactId, const \fBQString\fP & protocol)"
.PP
Get the KABC uid corresponding to the supplied IM address Protocols should be. 
.PP
\fBParameters:\fP
.RS 4
\fIcontactId\fP the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC. 
.br
\fIprotocol\fP the protocol, eg one of 'AIMProtocol', 'MSNProtocol', 'ICQProtocol', 
.RE
.PP
\fBReturns:\fP
.RS 4
a KABC uid or null if none found/
.RE
.PP

.PP
Definition at line 543 of file kimproxy.cpp.
.PP
References initialize(), and stubForProtocol().
.SS "\fBQString\fP KIMProxy::context (const \fBQString\fP & uid)"
.PP
Get the supplied addressee's current context (home, work, or any). 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want the context for. 
.RE
.PP
\fBReturns:\fP
.RS 4
A \fBQString\fP describing the context, or null if not supported.
.RE
.PP

.PP
Definition at line 479 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "void KIMProxy::chatWithContact (const \fBQString\fP & uid)"
.PP
Start a chat session with the specified addressee. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want to chat with.
.RE
.PP

.PP
Definition at line 489 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "void KIMProxy::messageContact (const \fBQString\fP & uid, const \fBQString\fP & message)"
.PP
Send a single message to the specified addressee Any response will be handled by the IM client as a normal conversation. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you want to chat with. 
.br
\fImessage\fP the message to send them.
.RE
.PP

.PP
Definition at line 502 of file kimproxy.cpp.
.PP
References initialize(), and stubForUid().
.SS "void KIMProxy::sendFile (const \fBQString\fP & uid, const \fBKURL\fP & sourceURL, const \fBQString\fP & altFileName = \fCQString::null\fP, uint fileSize = \fC0\fP)"
.PP
Send the file to the contact. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid you are sending to. 
.br
\fIsourceURL\fP a 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBKURL\fP to send. 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIaltFileName\fP an alternate filename describing the file 
.br
\fIfileSize\fP file size in bytes
.RE
.PP

.PP
Definition at line 515 of file kimproxy.cpp.
.PP
References QDictIterator::current(), and initialize().
.SS "bool KIMProxy::addContact (const \fBQString\fP & contactId, const \fBQString\fP & protocol)"
.PP
Add a contact to the contact list. 
.PP
\fBParameters:\fP
.RS 4
\fIcontactId\fP the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC. 
.br
\fIprotocol\fP the protocol, eg one of 'AIMProtocol', 'MSNProtocol', 'ICQProtocol', 
.RE
.PP
\fBReturns:\fP
.RS 4
whether the add succeeded. False may signal already present, protocol not supported, or add operation not supported.
.RE
.PP

.PP
Definition at line 533 of file kimproxy.cpp.
.PP
References initialize(), and stubForProtocol().
.SS "bool KIMProxy::imAppsAvailable ()"
.PP
Are there any compatible instant messaging apps installed? 
.PP
\fBReturns:\fP
.RS 4
true if there are any apps installed, to see if they are running, \fBinitialize\fP instead.
.RE
.PP

.PP
Definition at line 553 of file kimproxy.cpp.
.PP
References QDict::isEmpty().
.SS "bool KIMProxy::startPreferredApp ()"
.PP
Start the user's preferred IM application. 
.PP
\fBReturns:\fP
.RS 4
whether a preferred app was found. No guarantee that it started correctly
.RE
.PP

.PP
Definition at line 558 of file kimproxy.cpp.
.PP
References endl(), k_funcinfo, kdDebug(), and preferredApp().
.SS "void KIMProxy::contactPresenceChanged (\fBQString\fP uid, \fBQCString\fP appId, int presence)"
.PP
Just exists to let the idl compiler make the DCOP signal for this. 
.PP
Definition at line 328 of file kimproxy.cpp.
.PP
References sigContactPresenceChanged().
.SS "void KIMProxy::sigContactPresenceChanged (const \fBQString\fP & uid)\fC [signal]\fP"
.PP
Indicates that the specified UID's presence changed. 
.PP
\fBParameters:\fP
.RS 4
\fIuid\fP the KABC uid whose presence changed.
.RE
.PP

.PP
Referenced by contactPresenceChanged(), and pollApp().
.SS "void KIMProxy::sigPresenceInfoExpired ()\fC [signal]\fP"
.PP
Indicates that the sources of presence information have changed so any previously supplied presence info is invalid. 
.PP

.SS "void KIMProxy::pollApp (const \fBQCString\fP & appId)\fC [protected]\fP"
.PP
Bootstrap our presence data for a newly registered app. 
.PP
Definition at line 594 of file kimproxy.cpp.
.PP
References sigContactPresenceChanged().
.PP
Referenced by initialize().
.SS "void KIMProxy::pollAll (const \fBQString\fP & uid)\fC [protected]\fP"
.PP
Bootstrap our presence data by polling all known apps. 
.PP
Definition at line 576 of file kimproxy.cpp.
.SS "bool KIMProxy::updatePresence (const \fBQString\fP & uid, const \fBQCString\fP & appId, int presence)\fC [protected]\fP"
.PP
Update our records with the given data. 
.PP
.SS "\fBQString\fP KIMProxy::preferredApp ()\fC [protected]\fP"
.PP
Get the name of the user's IM weapon of choice. 
.PP
Definition at line 644 of file kimproxy.cpp.
.PP
References preferredApp(), KConfigBase::readEntry(), and KConfigBase::setGroup().
.PP
Referenced by preferredApp(), startPreferredApp(), and stubForProtocol().
.SS "KIMIface_stub * KIMProxy::stubForUid (const \fBQString\fP & uid)\fC [protected]\fP"
.PP
Get the app stub best able to reach this uid. 
.PP
Definition at line 616 of file kimproxy.cpp.
.PP
References QDict::find().
.PP
Referenced by canReceiveFiles(), canRespond(), chatWithContact(), context(), displayName(), and messageContact().
.SS "KIMIface_stub * KIMProxy::stubForProtocol (const \fBQString\fP & protocol)\fC [protected]\fP"
.PP
Get the app stub for this protocol. 
.PP
Take the preferred app first, then any other.
.PP
Definition at line 624 of file kimproxy.cpp.
.PP
References QDictIterator::count(), QDictIterator::current(), QDict::find(), and preferredApp().
.PP
Referenced by addContact(), and locate().

.SH "Author"
.PP 
Generated automatically by Doxygen for interfaces Library from the source code.
