You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
501 lines
16 KiB
501 lines
16 KiB
/*
|
|
kimiface.h - KDE Instant Messenger DCOP Interface
|
|
|
|
Copyright (c) 2004-5 Will Stephenson <lists@stevello.free-online.co.uk>
|
|
|
|
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 <tqpixmap.h>
|
|
#include <dcopobject.h>
|
|
#include <tqstringlist.h>
|
|
#include <kurl.h>
|
|
|
|
/**
|
|
* @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
|
|
* @endcode
|
|
* and the class implementing KIMIface must pass "KIMIface" to the DCOPObject constructor:
|
|
* @code
|
|
* // just need TQObject inheritance and Q_OBJECT if you want signals and slots
|
|
* // no need to use K_DCOP macro again
|
|
*
|
|
* class MyIMIface : public TQObject, public KIMIface
|
|
* {
|
|
* Q_OBJECT
|
|
* public:
|
|
* MyIMIface(TQObject* parent = 0, const char* name) :
|
|
* DCOPObject("KIMIface"), // <-- passing the interface name as required
|
|
* TQObject(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 <lists@stevello.free-online.co.uk>
|
|
*/
|
|
class KIMIface : virtual public DCOPObject
|
|
{
|
|
K_DCOP
|
|
|
|
k_dcop:
|
|
// ACCESSORS
|
|
// contact list
|
|
/**
|
|
* @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 TQStringList allContacts() = 0;
|
|
|
|
/**
|
|
* @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 TQStringList reachableContacts() = 0;
|
|
|
|
/**
|
|
* @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 TQStringList onlineContacts() = 0;
|
|
|
|
/**
|
|
* @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 TQStringList fileTransferContacts() = 0;
|
|
|
|
// individual
|
|
/**
|
|
* @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 TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString:null if the
|
|
* UID is unknown
|
|
*
|
|
* @see isPresent()
|
|
* @see presenceString()
|
|
* @see presenceStatus()
|
|
* @see KABC::Addressee::uid()
|
|
*/
|
|
virtual TQString displayName( const TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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
|
|
* TQString::null if the UID is unknown
|
|
*
|
|
* @see isPresent()
|
|
* @see presenceStatus()
|
|
* @see KABC::Addressee::uid()
|
|
*/
|
|
virtual TQString presenceString( const TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString::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 TQString locate( const TQString & contactId, const TQString & protocol ) = 0;
|
|
|
|
// metadata
|
|
/**
|
|
* @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 TQPixmap::isNull()
|
|
*
|
|
* @see isPresent()
|
|
* @see presenceString()
|
|
* @see presenceStatus()
|
|
* @see KABC::Addressee::uid()
|
|
*/
|
|
virtual TQPixmap icon( const TQString & uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString::null
|
|
*
|
|
* @param uid the KABC UID you want the context for
|
|
* @return a string describing the context, or @c TQString::null if not
|
|
* supported or if the contact is unknown
|
|
*
|
|
* @see isPresent()
|
|
* @see KABC::Addressee::uid()
|
|
*/
|
|
virtual TQString context( const TQString & uid ) = 0;
|
|
|
|
// App capabilities
|
|
/**
|
|
* @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 TQStringList protocols() = 0;
|
|
|
|
// ACTORS
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @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 TQString &uid, const TQString& message ) = 0;
|
|
|
|
/**
|
|
* @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 TQString &contactId, const TQString &protocol ) = 0;
|
|
|
|
/**
|
|
* @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 TQString &uid ) = 0;
|
|
|
|
/**
|
|
* @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 TQString &uid, const KURL &sourceURL,
|
|
const TQString &altFileName = TQString::null, uint fileSize = 0) = 0;
|
|
|
|
// MUTATORS
|
|
// Contact list
|
|
/**
|
|
* @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 TQString &contactId, const TQString &protocol ) = 0;
|
|
|
|
// SIGNALS
|
|
k_dcop_signals:
|
|
/**
|
|
* @brief Indicates that a contact's presence has changed
|
|
*
|
|
* Notifies connected DCOP tqreceivers 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( TQString uid, TQCString appId, int presence );
|
|
};
|
|
|
|
#endif
|
|
|
|
|
|
|
|
/*
|
|
* Local variables:
|
|
* c-indentation-style: k&r
|
|
* c-basic-offset: 8
|
|
* indent-tabs-mode: t
|
|
* End:
|
|
*/
|
|
// vim: set noet ts=4 sts=4 sw=4:
|
|
|