/* kimiface.h - KDE Instant Messenger DCOP Interface Copyright (c) 2004 Will Stephenson This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef KIMIFACE_H #define KIMIFACE_H #include #include #include #include /** * Generic DCOP interface for TDE instant messenger applications * Note one omission of this interface is the lack of control over the range of values used for protocols' names. * @since 3.3 * @author Will Stephenson */ class KIMIface : virtual public DCOPObject { K_DCOP k_dcop: // ACCESSORS // contact list /** * Obtain a list of IM-contactable entries in the TDE * address book. * @return a list of KABC uids. */ virtual TQStringList allContacts() = 0; /** * Obtain a list of TDE address book entries who are * currently reachable. * @return a list of KABC uids who can receive a message, even if online. */ virtual TQStringList reachableContacts() = 0; /** * Obtain a list of TDE address book entries who are * currently online. * @return a list of KABC uids who are online with unspecified presence. */ virtual TQStringList onlineContacts() = 0; /** * Obtain a list of TDE address book entries who may * receive file transfers. * @return a list of KABC uids capable of file transfer. */ virtual TQStringList fileTransferContacts() = 0; // individual /** * Confirm if a given KABC uid is known to KIMProxy * @param uid the KABC uid you are interested in. * @return whether one of the chat programs KIMProxy talks to knows of this KABC uid. */ virtual bool isPresent( const TQString & uid ) = 0; /** * Obtain the IM app's idea of the contact's display name * Useful if KABC lookups may be too slow * @param KABC uid. * @return The corresponding display name. */ virtual TQString displayName( const TQString & uid ) = 0; /** * Obtain the IM presence as a i18ned string for the specified addressee * @param uid the KABC uid you want the presence for. * @return the i18ned string describing presence. */ virtual TQString presenceString( const TQString & uid ) = 0; /** * Obtain the IM presence as a number (see KIMIface) for the specified addressee * @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) */ virtual int presenceStatus( const TQString & uid ) = 0; /** * Indicate if a given uid can receive files * @param uid the KABC uid you are interested in. * @return Whether the specified addressee can receive files. */ virtual bool canReceiveFiles( const TQString & uid ) = 0; /** * Some media are unidirectional (eg, sending SMS via a web interface). * @param uid the KABC uid you are interested in. * @return Whether the specified addressee can respond. */ virtual bool canRespond( const TQString & uid ) = 0; /** * Get the KABC uid corresponding to the supplied IM address * Protocols should be * @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/ */ virtual TQString locate( const TQString & contactId, const TQString & protocol ) = 0; // metadata /** * Obtain the icon representing IM presence for the specified addressee * @param uid the KABC uid you want the presence for. * @return a pixmap representing the uid's presence. */ virtual TQPixmap icon( const TQString & uid ) = 0; /** * Get the supplied addressee's current context (home, work, or any). * @param uid the KABC uid you want the context for. * @return A TQString describing the context, or null if not supported. */ virtual TQString context( const TQString & uid ) = 0; // App capabilities /** * Discover what protocols the application supports * @return the set of protocols that the application supports */ virtual TQStringList protocols() = 0; // ACTORS /** * Send a single message to the specified addressee * Any response will be handled by the IM client as a normal * conversation. * @param uid the KABC uid you want to chat with. * @param message the message to send them. */ virtual void messageContact( const TQString &uid, const TQString& message ) = 0; /** * Open a chat to a contact, and optionally set some initial text */ virtual void messageNewContact( const TQString &contactId, const TQString &protocol ) = 0; /** * Start a chat session with the specified addressee * @param uid the KABC uid you want to chat with. */ virtual void chatWithContact( const TQString &uid ) = 0; /** * Send the file to the contact * @param uid the KABC uid you are sending to. * @param sourceURL a @ref KURL to send. * @param altFileName an alternate filename describing the file * @param fileSize file size in bytes */ virtual void sendFile(const TQString &uid, const KURL &sourceURL, const TQString &altFileName = TQString(), uint fileSize = 0) = 0; // 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. */ virtual bool addContact( const TQString &contactId, const TQString &protocol ) = 0; // SIGNALS k_dcop_signals: /** * Indicates that a contact's presence has changed * @param uid the contact whose presence changed. * @param appId the dcop application id of the program the signal originates from. * @param presence the new numeric presence @ref presenceStatus */ void contactPresenceChanged( TQString uid, TQCString appId, int presence ); }; #endif