Author: erijo
Date: Sat Sep 16 01:59:41 2006
New Revision: 4609
URL: http://svn.licq.org/viewvc/licq?rev=4609&view=rev
Log:
Updated kimiface.h from KDE 3.5.4
Modified:
branches/qt-gui-no-qt2/src/kimiface.h
Modified: branches/qt-gui-no-qt2/src/kimiface.h
URL:
http://svn.licq.org/viewvc/licq/branches/qt-gui-no-qt2/src/kimiface.h?rev=4609&r1=4608&r2=4609&view=diff
==============================================================================
--- branches/qt-gui-no-qt2/src/kimiface.h (original)
+++ branches/qt-gui-no-qt2/src/kimiface.h Sat Sep 16 01:59:41 2006
@@ -1,7 +1,7 @@
/*
kimiface.h - KDE Instant Messenger DCOP Interface
- Copyright (c) 2004 Will Stephenson <[EMAIL PROTECTED]>
+ Copyright (c) 2004-5 Will Stephenson <[EMAIL PROTECTED]>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
@@ -15,8 +15,8 @@
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
- the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
#ifndef KIMIFACE_H
@@ -28,14 +28,56 @@
#include <kurl.h>
/**
- * Generic DCOP interface for KDE instant messenger applications
- * 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\>
+ * @brief 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 KABC::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:
+ * @code
+ * X-DCOP-ServiceName=<application-name>
* ServiceTypes=DCOP/InstantMessenger
- * and the class implementing KIMIface must pass "KIMIface" to the DCOPObject
constructor.
+ * @endcode
+ * and the class implementing KIMIface must pass "KIMIface" to the DCOPObject
constructor:
+ * @code
+ * // just need QObject inheritance and Q_OBJECT if you want signals and slots
+ * // no need to use K_DCOP macro again
+ *
+ * class MyIMIface : public QObject, public KIMIface
+ * {
+ * Q_OBJECT
+ * public:
+ * MyIMIface(QObject* parent = 0, const char* name) :
+ * DCOPObject("KIMIface"), // <-- passing the interface name as required
+ * QObject(parent, name) {}
+ * };
+ * @endcode
+ *
+ * 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
+ * @c SOURCES list in your @c Makefile.am
+ *
+ * @see KIMProxy
+ * @see KABC::AddressBook
+ * @see KABC::Addressee
*
* @since 3.3
* @author Will Stephenson <[EMAIL PROTECTED]>
@@ -48,125 +90,353 @@
// ACCESSORS
// contact list
/**
- * Obtain a list of IM-contactable entries in the KDE
- * address book.
- * @return a list of KABC uids.
+ * @brief 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.
+ *
+ * @return a list of KABC UIDs known to the application
+ *
+ * @see reachableContacts()
+ * @see onlineContacts()
+ * @see fileTransferContacts()
+ * @see isPresent()
+ * @see KABC::Addressee::uid()
*/
virtual QStringList allContacts() = 0;
- /**
- * Obtain a list of KDE address book entries who are
- * currently reachable.
- * @return a list of KABC uids who can receive a message, even if
offline.
+
+ /**
+ * @brief 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.
+ *
+ * @return a list of KABC UIDs who can receive a message, even if
offline
+ *
+ * @see allContacts()
+ * @see onlineContacts()
+ * @see fileTransferContacts()
+ * @see messageContact()
+ * @see KABC::Addressee::uid()
*/
virtual QStringList reachableContacts() = 0;
- /**
- * Obtain a list of KDE address book entries who are
- * currently online.
- * @return a list of KABC uids who are online with unspecified presence.
+
+ /**
+ * @brief 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.
+ *
+ * @return a list of KABC UIDs who are online with unspecified presence
+ *
+ * @see allContacts()
+ * @see reachableContacts()
+ * @see fileTransferContacts()
+ * @see messageContact()
+ * @see chatWithContact()
+ * @see KABC::Addressee::uid()
*/
virtual QStringList onlineContacts() = 0;
- /**
- * Obtain a list of KDE address book entries who may
- * receive file transfers.
- * @return a list of KABC uids capable of file transfer.
+
+ /**
+ * @brief 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.
+ *
+ * @return a list of KABC UIDs capable of file transfer
+ *
+ * @see allContacts()
+ * @see reachableContacts()
+ * @see onlineContacts()
+ * @see canReceiveFiles()
+ * @see sendFile()
+ * @see KABC::Addressee::uid()
*/
virtual QStringList fileTransferContacts() = 0;
// individual
/**
- * Confirm if a given contact is known to the IM application
- * @param uid the KABC uid you are interested in.
- * @return whether the program knows of this KABC uid.
+ * @brief 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()
+ *
+ * @param uid the KABC UID you are interested in
+ * @return whether the program knows of this KABC UID
+ *
+ * @see allContacts()
+ * @see presenceString()
+ * @see presenceStatus()
+ * @see KABC::Addressee::uid()
*/
virtual bool isPresent( const QString & uid ) = 0;
- /**
- * Obtain the IM app's idea of the contact's display name
- * Useful if KABC lookups may be too slow
- * @param uid the KABC uid you are interested in.
- * @return the corresponding display name.
+
+ /**
+ * @brief 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.
+ *
+ * @param uid the KABC UID you are interested in
+ * @return the corresponding display name or QString:null if the
+ * UID is unknown
+ *
+ * @see isPresent()
+ * @see presenceString()
+ * @see presenceStatus()
+ * @see KABC::Addressee::uid()
*/
virtual QString displayName( const QString & uid ) = 0;
- /**
- * Obtain the IM presence as a i18ned string for the specified contact
- * @param uid the KABC uid you want the presence for.
- * @return the i18ned string describing presence.
+
+ /**
+ * @brief 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")
+ *
+ * @param uid the KABC UID you want the presence for
+ * @return the i18ned string describing the contact's presence or
+ * QString::null if the UID is unknown
+ *
+ * @see isPresent()
+ * @see presenceStatus()
+ * @see KABC::Addressee::uid()
*/
virtual QString presenceString( const QString & uid ) = 0;
- /**
- * Obtain the IM presence as a number for the specified contact
- * @param uid the KABC uid you want the presence for.
- * @return a numeric representation of presence - currently one of 0
(Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online)
+
+ /**
+ * @brief 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 - @c Unknown: for contacts where you can not use any of the other
+ * values
+ *
+ * - 1 - @c 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 @c Unknown instead
+ *
+ * - 2 - @c Connecting
+ *
+ * - 3 - @c Away: for contacts that are connected to their IM-service
but
+ * not @c Online
+ *
+ * - 4 - @c Online
+ *
+ * @param uid the KABC UID you want the presence for
+ * @return 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 isPresent()
+ * @see presenceString()
+ * @see KABC::Addressee::uid()
*/
virtual int presenceStatus( const QString & uid ) = 0;
- /**
- * Indicate if a given contact can receive files
- * @param uid the KABC uid you are interested in.
- * @return whether the specified addressee can receive files.
+
+ /**
+ * @brief Indicate if a given contact can receive files
+ *
+ * @param uid the KABC UID you want to the file transfer capability for
+ * @return whether the specified contact can receive files
+ *
+ * @see fileTransferContacts()
+ * @see KABC::Addressee::uid()
*/
virtual bool canReceiveFiles( const QString & uid ) = 0;
- /**
- * Some media are unidirectional (eg, 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.
- * @param uid the KABC uid you are interested in.
- * @return whether the specified contact can respond.
+
+ /**
+ * @brief 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.
+ *
+ * @param uid the KABC UID you are interested in
+ * @return whether the specified contact can respond
+ *
+ * @see isPresent()
+ * @see KABC::Addressee::uid()
*/
virtual bool canRespond( const QString & uid ) = 0;
- /**
- * Get the KABC uid corresponding to the supplied IM address
- * @param contactId the protocol specific identifier for the contact,
eg UIN for ICQ, screenname for AIM, nick for IRC.
- * @param protocol the protocol, eg one of "AIMProtocol",
"MSNProtocol", "ICQProtocol",
- * @return a KABC uid or null if none found
+
+ /**
+ * @brief Obtain the KABC UID corresponding to the given IM address
+ *
+ * @param contactId the protocol specific identifier for the contact,
+ * e.g. UIN for ICQ, screenname for AIM, nick for IRC
+ * @param protocol the IM protocol/service to check. See protocols()
+ * @return the KABC UID for the given contact or @c QString::null if not
+ * found or either input stream was empty or the protocol is not
+ * supported
+ *
+ * @see protocols()
+ * @see addContact()
+ * @see isPresent()
+ * @see KABC::Addressee::uid()
*/
virtual QString locate( const QString & contactId, const QString &
protocol ) = 0;
+
// metadata
/**
- * Obtain the icon representing IM presence for the specified contact
- * @param uid the KABC uid you want the presence for.
- * @return a pixmap representing the uid's presence.
+ * @brief 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.
+ *
+ * @param uid the KABC UID you want the presence icon for
+ * @return a pixmap representing the contact's presence or a null pixmap
+ * if the contact is unknown. See QPixmap::isNull()
+ *
+ * @see isPresent()
+ * @see presenceString()
+ * @see presenceStatus()
+ * @see KABC::Addressee::uid()
*/
virtual QPixmap icon( const QString & uid ) = 0;
- /**
- * Get the supplied contact's current context (home, work, or any).
- * @param uid the KABC uid you want the context for.
- * @return a QString describing the context, or null if not supported.
+
+ /**
+ * @brief 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 @c QString::null
+ *
+ * @param uid the KABC UID you want the context for
+ * @return a string describing the context, or @c QString::null if not
+ * supported or if the contact is unknown
+ *
+ * @see isPresent()
+ * @see KABC::Addressee::uid()
*/
virtual QString context( const QString & uid ) = 0;
+
// App capabilities
/**
- * Discover what protocols the application supports
- * @return the set of protocols that the application supports, ie a
list of
- * protocol names, eg "AIMProtocol", "MSNProtocol", "ICQProtocol", ...
+ * @brief 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()
+ *
+ * @return the set of protocols that the application supports
+ *
+ * @see locate()
+ * @see addContact()
+ * @see messageNewContact
*/
virtual QStringList protocols() = 0;
// ACTORS
/**
- * Send a single message to the specified contact
+ * @brief Send a single message to the specified contact
+ *
* Any response will be handled by the IM client as a normal
* conversation.
- * @param uid the KABC uid you want to send the message to.
- * @param message the message to send them.
+ *
+ * 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.
+ *
+ * @param uid the KABC UID you want to send the message to
+ * @param message the message text to send to the contact
+ *
+ * @see messageNewContact()
+ * @see chatWithContact()
+ * @see sendFile()
+ * @see isPresent()
+ * @see reachableContacts()
+ * @see KABC::Addressee::uid()
*/
virtual void messageContact( const QString &uid, const QString& message
) = 0;
/**
- * Open a chat to a contact, and optionally set some initial text
+ * @brief 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.
+ *
+ * @param contactId the protocol specific identifier for the contact,
+ * e.g. UIN for ICQ, screenname for AIM, nick for IRC
+ * @param protocol the IM protocol/service to check. See protocols()
+ *
+ * @see messageContact()
+ * @see chatWithContact()
+ * @see sendFile()
+ * @see locate()
+ * @see protocols()
+ * @see addContact()
*/
virtual void messageNewContact( const QString &contactId, const QString
&protocol ) = 0;
/**
- * Start a chat session with the specified contact
- * @param uid the KABC uid you want to chat with.
+ * @brief 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.
+ *
+ * @param uid the KABC UID you want to chat with
+ *
+ * @see messageContact()
+ * @see messageNewContact()
+ * @see sendFile()
+ * @see isPresent()
+ * @see reachableContacts()
+ * @see KABC::Addressee::uid()
*/
virtual void chatWithContact( const QString &uid ) = 0;
/**
- * Send a file to the contact
- * @param uid the KABC uid you are sending to.
- * @param sourceURL a @see KURL to send.
- * @param altFileName an alternate filename describing the file
+ * @brief 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.
+ *
+ * @param uid the KABC UID you want to send to
+ * @param sourceURL a KURL pointing to the file to send
+ * @param altFileName an alternate filename describing the file or a
+ * description or title
* @param fileSize file size in bytes
+ *
+ * @see messageContact()
+ * @see messageNewContact()
+ * @see chatWithContact()
+ * @see isPresent()
+ * @see fileTransferContacts()
+ * @see KABC::Addressee::uid()
*/
virtual void sendFile(const QString &uid, const KURL &sourceURL,
const QString &altFileName = QString::null, uint fileSize = 0)
= 0;
@@ -174,20 +444,43 @@
// MUTATORS
// Contact list
/**
- * Add a contact to the contact list
- * @param contactId the protocol specific identifier for the contact,
eg UIN for ICQ, screenname for AIM, nick for IRC.
- * @param protocol the protocol, eg one of "AIMProtocol",
"MSNProtocol", "ICQProtocol", ...
- * @return whether the add succeeded. False may signal already
present, protocol not supported, or add operation not supported.
- * @see locate
+ * @brief 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.
+ *
+ * @param contactId the protocol specific identifier for the contact
+ * e.g. UIN for ICQ, screenname for AIM, nick for IRC
+ * @param protocol the IM protocol/service to use. See protocols()
+ * @return whether the add succeeded. @c false may signal already
present,
+ * protocol not supported, or add operation not supported.
+ *
+ * @see locate()
+ * @see protocols()
+ * @see messageNewContact()
*/
virtual bool addContact( const QString &contactId, const QString
&protocol ) = 0;
+
// SIGNALS
k_dcop_signals:
/**
- * Indicates that a contact's presence has changed
- * @param uid the KABC uid whose presence changed.
- * @param appId the dcop application id of the program the signal
originates from.
- * @param presence the new numeric presence @ref presenceStatus
+ * @brief Indicates that a contact's presence has changed
+ *
+ * Notifies connected DCOP receivers about a change in a contact's
+ * presence.
+ *
+ * Implementations just have to call this method with the appropriate
+ * values to get the DCOP signal emitted.
+ *
+ * @param uid the KABC UID whose presence changed
+ * @param appId the DCOP application ID of the program the signal
+ * originates from
+ * @param presence the new presence's numeric value. See
presenceStatus()
+ *
+ * @see presenceStatus()
+ * @see KABC::Addressee::uid()
+ * @see DCOPClient::appId()
*/
void contactPresenceChanged( QString uid, QCString appId, int presence
);
};
