Designing a generic IM DCOP interface
-------------------------------------

2 possible architectures depending on relationship between IM addresses and KDE addressbook addressees.

1) 'Closed' system - IM addresses are added manually to addressees using applications (KAddressbook) or IM addresses are related to addressees in IM clients (Kopete), and KIMProxy/KIMIface just uses existing relationships.  Simpler because we just have to deal with KABC uids.

2) 'Open' system - IM addresses found in the wild (eg WWW, email signatures) can be used in integrated IM.  Either do so in a 'volatile' manner, don't add to address books etc, just message, or provide means to relate to addressees.  Good compromises is to provide an 'Open in address book' function as we do in Kmail for email addresses, converting 2) into 1).

Consider whether the contactlist concept is appropriate for all messaging systems.  Certainly in IRC (and email) it is much less significant than in traditional IM systems.  In some situations all we want to do is message someone, or we may want to add them to our contact list, or we may have to add them to our contact list to be able to message them.

Does the library user need to know about setting the IM client online or offline?  Can we just specify that the IM client should go online if needed to carry out a request, or return an error message if unable to?

Consider presence as a contact filter - what about an SMS or email backend which has no presence information - apps may need to show even unknowns... (don't do email, then!)

Use Cases for KDE IM integration
--------------------------------

Use Cases can be divided into wanting to interact with a specific person in an arbitrary way, and wanting to act on a specific object (ie send a file, etc) with an arbitrary person.

U1) Bob opens KAddressBook to look up Chris' details.  Chris' contact summary page includes his current IM status, so Bob decides to start a chat.

U2) Dina receives an email from Chris.  KMail presents Chris' current IM status as part of the email headers, so Dina can decide if she wants to respond immediately via IM.  If she does so the IM client includes the email's subject line as the first line of the outgoing message.

U3) Ralph wants to play Atlantik with Steve.  His Atlantik client gives him a list of online contacts, including Steve.  Clicking on Steve's name lets Ralph send a formatted invitation.  Ralph copies and pastes the details into Atlantik.

U4) Alice needs help setting up a new sound card.  She decides to get Dina to help her using KRfb.  KRfb allows her to send a formatted invitation to Dina so Dina can connect to her PC and set up the card.  The formatted invitation is a small file.  This file type is associated with Krdc on Dina's machine, which loads it and establishes the connection.

U5) It's 1800 and Chris wants to talk to Eric, but isn't sure if he is home from work yet.  He hovers the mouse over the IMApplet showing Eric online on his taskbar, and can see that Eric is online using his 'Work' Jabber resource, and decides to wait until later.

U6) Eric wants to chat to Alice, but the tooltip on her icon attached to an email shows she's only contactable via SMS, and Eric's mobile phone's battery is flat so he won't be able to receive a reply, and decides to phone her on a landline instead.

U7) Rob has just made a great wallpaper and wants to send it to Chris.  He right-clicks it in Konqueror, selects 'Send File...' from the context menu, chooses Chris from a list of recipients, IM as the medium, and the file is dispatched over Jabber.

U8) Jason clicks a URL of the form aim:/foobar in a webpage in Konqueror, and Jason's preferred IM client starts a chat with that AIM user.
(These - for aim and icq at least, are common in the internet.)

U9) Jason clicks a URL of the form aim:/foobar in a webpage in Konqueror, and Jason's preferred IM client opens an 'Add Contact' dialog with that AIM user.

------------

R1) Check we have an IM address on a KABC uid (U1, U2, U5, U6)

R2) Discover someone's presence (U1, U2, U3, U4, U5)

R3) Initiate a chat with a someone in an IM app's contact list identified by KABC uid (U1, U2)

R4) Initiate a chat with someone identified only by IM protocol and IM address (U8)

R5) Initiate a chat with application supplied message content (U2, U3, U4)

R6) Access advanced presence metadata relating to a contact (U5). This could be protocol specific as in the use case, or a property of a given means of contact (U6), or derived from past activity (last message received time).

R7) Obtain a list of available chat partners (U3, U4 )

R8) Obtain a list of available file transfer recipients (U7)

R9) Initiate file transfers (U7, possibly U3 and U4)

R10) Check that the IM system supports and is configured to use a given protocol (U8, U9)

R11) Add a new contact to a contactlist given IM protocol and address (U9)

-----------

Implementation features

I1) Helper function to get (IM protocol, address) for a KABC uid ( and vice versa ) - this could be in KABC though - assuming all contacts have to be in KABC, this lets us slim down the API

I2) List of accounts' protocols - lets non-KABC users determine contact list

I3) List of contacts for a protocol? - "



Kopete's existing interface:
---------------------------

Accessor methods
	Lists of classes of contacts
		contacts();
		reachableContacts();
		onlineContacts();
		fileTransferContacts();
		imAddresseeUids()    KIMPROXY
	All contacts' status
		contactsStatus()
	
	Individual statuses
		onlineStatus()
		onlineStatusNumeric()
		statusIcon()

	Available IM accounts
		accounts() (list of Protocol||AccountID)

	Protocols usable for file xfer to a contact
		contactFileProtocols(const QString &displayName)
		
Actor methods
	messageContact()
	messageContactById()     KIMPROXY
	chatContactbyId()        KIMPROXY
	sendFileToId()           KIMPROXY

Mutator methods()
	Contact list control
		addContact()
	Connection control
		connect( proto, account )
		disconnect( protoc, account )
		connectAll()
		disconnectAll()
	Status control
		setAway
		setAway( msg )
		setAutoAway()
		setAvailable()
	Kopete specific app control
		loadPlugin()
		unloadPlugin()

SIGNALS
	Contact Information
		contactStatusChanged() KIMPROXY

Proposed generic interface
---------------------------
KABC centric:

Accessors
	Contact list
F1		allContacts()	// what if it's very large - imagine entire IRC logged in userlist
						// need to be able to say 'Not supported'
F2		reachableContacts()
F3		fileTransferContacts()
F4		isPresent( uid )	// check if present in contact list
	Individual
F5		presence( uid )	// return something like a KOS - ( i18n'ed status, enumerated code )
F6		canReceiveFiles( uid )
F16		canRespond( uid )	// To detect one-way messaging systems 
F7		locate( protocol, contactId ) return KABC uid if already known 
	Metadata
F8		icon( uid )		// Eye candy - if the address book is being used then users can save their friends' IM 
						// avatar pics to the address book and apps can read it from there.
F9		context( uid )	// (work/home) - could be specified when adding contact or obtainable from IM protocol (Jabber resources)
	
	App capabilities
F10		protocols()		// get a list of protocols the IM client supports

Actors
	
F11		messageContact( uid, message )     KIMPROXY
F12		chatWithContact( uid )    KIMPROXY
F13		sendFile( uid, URL )      KIMPROXY
F14		messageNewContact( protocol, contactId )  // add if necessary, and chat

Mutators
	Contact list
F15		addContact( protocol, contactId ) - any specifics (which IM account to use) handled by the IM client.
		// Any other contactlist management (grouping, deletion) is best carried out in a dedicated app!
		
Use case execution models
-------------------------

U1) Bob opens KAddressBook to look up Chris' details.  Chris' contact summary page includes his current IM status, so Bob decides to start a chat.

E1)	i) KAddressbook queries KIMProxy for Chris' presence.  KIMProxy calls F5 and F8 on the IM app.  It returns his presence
	ii) KIMproxy calls F12 on the IM app.  It opens a chat window with Chris.
	
E2)	i) KAddressbook queries KIMProxy for Chris' presence.  KIMProxy calls F5 and F8 on the IM app.  It returns his presence.
	ii) KIMproxy calls F11 on the IM app.  It opens a message window pre-filled with the subject line
	
E3)	i) Atlantik gets a list of reachable contacts from KIMProxy.  KIMProxy calls F2 on the IM app.  
	ii) KIMProxy calls F11 on the IM app. It opens a message window containing the invitation.
	
E4)	i) KRfb gets a list of reachable contacts from KIMProxy.  KIMProxy calls F2 on the IM app.  
	ii) KIMProxy calls F13 on the IM app.  It initiates a file transfer of the invitation file.
	iii) Optional invitation text is sent with F12.

E5)	i) as E1) with IMapplet
	ii) KIMProxy calls F9 on the IM app.  It determines from Jabber that Eric is still at work.
	
E6)	i) as E1) with IMapplet
	ii) KIMProxy calls F16 on the IM app.  It knows that Alice is only reachable via a one-way IM system and returns a bool.
		
E7)	i) Konqueror queries KIMProxy for a list of file transfer capable contacts.  KIMProxy calls F3 on the IM app. It returns a list.
	ii) Konqueror checks which contacts are online.  KIMProxy calls F5 on the IM app.  Konqueror presents a list of file transfer capable online contacts
	iii) KIMProxy calls F13 on the IM app.
	
E8) i) Konqueror asks KIMProxy to begin a chat with the contact.  It calls F14 on the IM app.  It adds the new contact to its roster if necessary and opens a chat window.  If the contact is offline it returns an error code, or displays its own error dialog.

E9) i) Konqueror asks KIMProxy to add the contact to its list.  It calls F15 on the IM app.