home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kimiface.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  16.1 KB  |  501 lines
  1. /*
  2.     kimiface.h - KDE Instant Messenger DCOP Interface
  3.  
  4.     Copyright (c) 2004-5 Will Stephenson   <lists@stevello.free-online.co.uk>
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.  
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.     Boston, MA 02110-1301, USA.
  20. */
  21.  
  22. #ifndef KIMIFACE_H
  23. #define KIMIFACE_H
  24.  
  25. #include <qpixmap.h>
  26. #include <dcopobject.h>
  27. #include <qstringlist.h>
  28. #include <kurl.h>
  29.  
  30. /**
  31.  * @brief Generic DCOP interface for KDE instant messenger applications
  32.  *
  33.  * The interface has two parts:
  34.  * - methods to get information about IM-contacts, such as their reachability
  35.  *   or their presence status (if the are online or away, etc)
  36.  * - methods to initiate communication with IM-contacts, e.g. sending messages
  37.  *
  38.  * @note If you are looking for a information about accessing application's
  39.  * that implement this interface, have a look at the KIMProxy class.
  40.  *
  41.  * Contacts are identified using unique identifier strings (UID) used by
  42.  * KABC, the KDE address book library.
  43.  * The UID generation is handled by KABC::Addressee so the your application
  44.  * will either have to access the address book or provide a possibility
  45.  * for associating a contact of your application with an entry of the address
  46.  * book.
  47.  *
  48.  * @note one omission of this interface is the lack of control over the range
  49.  * of values used for protocols' names.
  50.  *
  51.  * If you are implementing this interface, note that your application must
  52.  * have the following information in its desktop file, so that it can be
  53.  * identified as providing KIMIface at runtime:
  54.  * @code
  55.  * X-DCOP-ServiceName=<application-name>
  56.  * ServiceTypes=DCOP/InstantMessenger
  57.  * @endcode
  58.  * and the class implementing KIMIface must pass "KIMIface" to the DCOPObject constructor:
  59.  * @code
  60.  * // just need QObject inheritance and Q_OBJECT if you want signals and slots
  61.  * // no need to use K_DCOP macro again
  62.  *
  63.  * class MyIMIface : public QObject, public KIMIface
  64.  * {
  65.  *     Q_OBJECT
  66.  * public:
  67.  *    MyIMIface(QObject* parent = 0, const char* name) :
  68.  *        DCOPObject("KIMIface"), // <-- passing the interface name as required
  69.  *        QObject(parent, name) {}
  70.  * };
  71.  * @endcode
  72.  *
  73.  * The DCOP part of the interface needs to be processed by the DCOP IDL
  74.  * compiler. The KDE autotools framework will do this automatically, all
  75.  * you have to do is add kimiface.skel and kimiface.stub to the
  76.  * @c SOURCES list in your @c Makefile.am
  77.  *
  78.  * @see KIMProxy
  79.  * @see KABC::AddressBook
  80.  * @see KABC::Addressee
  81.  *
  82.  * @since 3.3
  83.  * @author Will Stephenson <lists@stevello.free-online.co.uk>
  84.  */
  85. class KIMIface : virtual public DCOPObject
  86. {
  87.     K_DCOP
  88.  
  89. k_dcop:
  90. // ACCESSORS
  91. // contact list
  92.     /**
  93.      * @brief Obtain a list of IM-contacts that are known to the application
  94.      *
  95.      * Return a list of KABC UIDs of all the contacts you have such IDs for.
  96.      *
  97.      * @return a list of KABC UIDs known to the application
  98.      *
  99.      * @see reachableContacts()
  100.      * @see onlineContacts()
  101.      * @see fileTransferContacts()
  102.      * @see isPresent()
  103.      * @see KABC::Addressee::uid()
  104.      */
  105.     virtual QStringList allContacts() = 0;
  106.  
  107.     /**
  108.      * @brief Obtain a list of IM-contacts that are currently reachable
  109.      *
  110.      * Return a list of KABC UIDs of the contacts that are reachable in the
  111.      * sense that you are connected to the IM-service they are
  112.      * associated with.
  113.      *
  114.      * For example if your application supports ICQ and AIM and the ICQ account is
  115.      * active but the AIM account isn't, return just the ICQ contacts.
  116.      *
  117.      * @return a list of KABC UIDs who can receive a message, even if offline
  118.      *
  119.      * @see allContacts()
  120.      * @see onlineContacts()
  121.      * @see fileTransferContacts()
  122.      * @see messageContact()
  123.      * @see KABC::Addressee::uid()
  124.      */
  125.     virtual QStringList reachableContacts() = 0;
  126.  
  127.     /**
  128.      * @brief Obtain a list of IM-contacts that are currently online
  129.      *
  130.      * Return a list of KABC UIDs of the contacts you have any presence
  131.      * information for that indicates that they are connected to the
  132.      * IM-service they are associated with.
  133.      *
  134.      * @return a list of KABC UIDs who are online with unspecified presence
  135.      *
  136.      * @see allContacts()
  137.      * @see reachableContacts()
  138.      * @see fileTransferContacts()
  139.      * @see messageContact()
  140.      * @see chatWithContact()
  141.      * @see KABC::Addressee::uid()
  142.      */
  143.     virtual QStringList onlineContacts() = 0;
  144.  
  145.     /**
  146.      * @brief Obtain a list of IM-contacts who may receive file transfers
  147.      *
  148.      * Return a list of KABC UIDs of the contacts that are capable of
  149.      * receiving file transfers based on the IM-service they are associated
  150.      * with, i.e. if it is technically able to provide this, on their online
  151.      * state, i.e. can likely not receive files while offline, and perhaps even
  152.      * information your application has additionally, e.g. a user config that
  153.      * tells you that the contact is behind a firewall.
  154.      *
  155.      * The simplest implementation is to return the same list as
  156.      * onlineContacts(), provided all the IM-services that are currently used
  157.      * support it.
  158.      *
  159.      * @return a list of KABC UIDs capable of file transfer
  160.      *
  161.      * @see allContacts()
  162.      * @see reachableContacts()
  163.      * @see onlineContacts()
  164.      * @see canReceiveFiles()
  165.      * @see sendFile()
  166.      * @see KABC::Addressee::uid()
  167.      */
  168.     virtual QStringList fileTransferContacts() = 0;
  169.  
  170. // individual
  171.     /**
  172.      * @brief Confirm if a given contact is known to the IM application
  173.      *
  174.      * Check if you can map the given KABC UID to one if the IM-contacts, e.g.
  175.      * the would be part of the list returned by allContacts()
  176.      *
  177.      * @param uid the KABC UID you are interested in
  178.      * @return whether the program knows of this KABC UID
  179.      *
  180.      * @see allContacts()
  181.      * @see presenceString()
  182.      * @see presenceStatus()
  183.      * @see KABC::Addressee::uid()
  184.      */
  185.     virtual bool isPresent( const QString & uid ) = 0;
  186.  
  187.     /**
  188.      * @brief Obtain the IM app's idea of the contact's display name
  189.      *
  190.      * Useful if KABC lookups may be too slow. Should return whatever
  191.      * the application uses in its contact list or similar GUI, e.g.
  192.      * a nick name, a user configured name string, etc.
  193.      *
  194.      * @param uid the KABC UID you are interested in
  195.      * @return the corresponding display name or QString:null if the
  196.      *         UID is unknown
  197.      *
  198.      * @see isPresent()
  199.      * @see presenceString()
  200.      * @see presenceStatus()
  201.      * @see KABC::Addressee::uid()
  202.      */
  203.     virtual QString displayName( const QString & uid ) = 0;
  204.  
  205.     /**
  206.      * @brief Obtain the IM presence as a i18ned string for the specified
  207.      *        contact
  208.      *
  209.      * Return a translated string your application would use when displaying
  210.      * the contact's presence, e.g. i18n("Online"), i18n("Away")
  211.      *
  212.      * @param uid the KABC UID you want the presence for
  213.      * @return the i18ned string describing the contact's presence or
  214.      *         QString::null if the UID is unknown
  215.      *
  216.      * @see isPresent()
  217.      * @see presenceStatus()
  218.      * @see KABC::Addressee::uid()
  219.      */
  220.     virtual QString presenceString( const QString & uid ) = 0;
  221.  
  222.     /**
  223.      * @brief Obtain the IM presence as a number for the specified contact
  224.      *
  225.      * Return one of the following values depending on the given contact's
  226.      * presence:
  227.      * - 0 - @c Unknown: for contacts where you can not use any of the other
  228.      *   values
  229.      *
  230.      * - 1 - @c Offline: for contacts that are offline, i.e. not connected to
  231.      *   their IM-service. If the application itself or the IM-service for the
  232.      *   given contact is offline return @c Unknown instead
  233.      *
  234.      * - 2 - @c Connecting
  235.      *
  236.      * - 3 - @c Away: for contacts that are connected to their IM-service but
  237.      *   not @c Online
  238.      *
  239.      * - 4 - @c Online
  240.      *
  241.      * @param uid the KABC UID you want the presence for
  242.      * @return a numeric representation of presence - currently one of
  243.      *         0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online).
  244.      *         Returns 0 if the given UID is unknown
  245.      *
  246.      * @see isPresent()
  247.      * @see presenceString()
  248.      * @see KABC::Addressee::uid()
  249.      */
  250.     virtual int presenceStatus( const QString & uid ) = 0;
  251.  
  252.     /**
  253.      * @brief Indicate if a given contact can receive files
  254.      *
  255.      * @param uid the KABC UID you want to the file transfer capability for
  256.      * @return whether the specified contact can receive files
  257.      *
  258.      * @see fileTransferContacts()
  259.      * @see KABC::Addressee::uid()
  260.      */
  261.     virtual bool canReceiveFiles( const QString & uid ) = 0;
  262.  
  263.     /**
  264.      * @brief Indicate if a given contact will be able to respond
  265.      *
  266.      * Some media are unidirectional (e.g., sending SMS via a web interface).
  267.      * This refers to the contact's ability to respond as defined by the
  268.      * medium, not by their presence.
  269.      *
  270.      * Someone may appear offline (SMS has no presence) to you but in fact be
  271.      * able to respond.
  272.      *
  273.      * @param uid the KABC UID you are interested in
  274.      * @return whether the specified contact can respond
  275.      *
  276.      * @see isPresent()
  277.      * @see KABC::Addressee::uid()
  278.      */
  279.     virtual bool canRespond( const QString & uid ) = 0;
  280.  
  281.     /**
  282.      * @brief Obtain the KABC UID corresponding to the given IM address
  283.      *
  284.      * @param contactId the protocol specific identifier for the contact,
  285.      *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
  286.      * @param protocol the IM protocol/service to check. See protocols()
  287.      * @return the KABC UID for the given contact or @c QString::null if not
  288.      *         found or either input stream was empty or the protocol is not
  289.      *         supported
  290.      *
  291.      * @see protocols()
  292.      * @see addContact()
  293.      * @see isPresent()
  294.      * @see KABC::Addressee::uid()
  295.      */
  296.     virtual QString locate( const QString & contactId, const QString & protocol ) = 0;
  297.  
  298. // metadata
  299.     /**
  300.      * @brief Obtain the icon representing the IM presence for the specified
  301.      *        contact
  302.      *
  303.      * Return the image the application would use to display a contact's presence.
  304.      * The size and other properties of the image are currently unspecified.
  305.      *
  306.      * @param uid the KABC UID you want the presence icon for
  307.      * @return a pixmap representing the contact's presence or a null pixmap
  308.      *         if the contact is unknown. See QPixmap::isNull()
  309.      *
  310.      * @see isPresent()
  311.      * @see presenceString()
  312.      * @see presenceStatus()
  313.      * @see KABC::Addressee::uid()
  314.      */
  315.     virtual QPixmap icon( const QString & uid ) = 0;
  316.  
  317.     /**
  318.      * @brief Obtain the given contact's current context (home, work, or any)
  319.      *
  320.      * Not all IM services/protocols support the concept of contexts. If the
  321.      * given UID maps to such a service, just return @c QString::null
  322.      *
  323.      * @param uid the KABC UID you want the context for
  324.      * @return a string describing the context, or @c QString::null if not
  325.      *         supported or if the contact is unknown
  326.      *
  327.      * @see isPresent()
  328.      * @see KABC::Addressee::uid()
  329.      */
  330.     virtual QString context( const QString & uid ) = 0;
  331.  
  332. // App capabilities
  333.     /**
  334.      * @brief Obtain a list of supported IM services/protocols
  335.      *
  336.      * Protocol names are currently of the form "protocol name" + "Protocol"
  337.      * for example:
  338.      * - AIMProtocol: AOL instant messenger protocol
  339.      * - MSNProtocol: Microsoft messanger protocol
  340.      * - ICQProtocol: AOL (Mirabilis) ICQ protocol
  341.      * - ....
  342.      *
  343.      * The string is currently just an identifier to use with methods such as
  344.      * locate(), addContact() or messageNewContact()
  345.      *
  346.      * @return the set of protocols that the application supports
  347.      *
  348.      * @see locate()
  349.      * @see addContact()
  350.      * @see messageNewContact
  351.      */
  352.     virtual QStringList protocols() = 0;
  353.  
  354. // ACTORS
  355.     /**
  356.      * @brief Send a single message to the specified contact
  357.      *
  358.      * Any response will be handled by the IM client as a normal
  359.      * conversation.
  360.      *
  361.      * Implementations might send the message silently, ask the user for
  362.      * permission or just prefill the usual message input GUI.
  363.      *
  364.      * @note As sending any text could potentially be a breach of the user's
  365.      * privacy it is recommended to let the user know about it.
  366.      *
  367.      * @param uid the KABC UID you want to send the message to
  368.      * @param message the message text to send to the contact
  369.      *
  370.      * @see messageNewContact()
  371.      * @see chatWithContact()
  372.      * @see sendFile()
  373.      * @see isPresent()
  374.      * @see reachableContacts()
  375.      * @see KABC::Addressee::uid()
  376.      */
  377.     virtual void messageContact( const QString &uid, const QString& message ) = 0;
  378.  
  379.     /**
  380.      * @brief Send a single message to a contact given only its protocol
  381.      *        specific identifier
  382.      *
  383.      * This could be used to send a message without having to know the KABC UID
  384.      * of the contact or without having to add it first.
  385.      * 
  386.      * @param contactId the protocol specific identifier for the contact,
  387.      *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
  388.      * @param protocol the IM protocol/service to check. See protocols()
  389.      *
  390.      * @see messageContact()
  391.      * @see chatWithContact()
  392.      * @see sendFile()
  393.      * @see locate()
  394.      * @see protocols()
  395.      * @see addContact()
  396.      */
  397.     virtual void messageNewContact( const QString &contactId, const QString &protocol ) = 0;
  398.  
  399.     /**
  400.      * @brief Start a chat session with the specified contact
  401.      *
  402.      * Applications that do not support a chat mode or when the IM-service
  403.      * of the given contact does not support it, this can also open
  404.      * a normal message input GUI.
  405.      *
  406.      * @param uid the KABC UID you want to chat with
  407.      *
  408.      * @see messageContact()
  409.      * @see messageNewContact()
  410.      * @see sendFile()
  411.      * @see isPresent()
  412.      * @see reachableContacts()
  413.      * @see KABC::Addressee::uid()
  414.      */
  415.     virtual void chatWithContact( const QString &uid ) = 0;
  416.  
  417.     /**
  418.      * @brief Send a file to the contact
  419.      *
  420.      * Initiates a file transfer with the given contact if possible.
  421.      *
  422.      * Implementations might start the transfer right away, ask the user's
  423.      * permission or just prefill the usual file transfer GUI.
  424.      *
  425.      * @note As sending any file could potentially be a breach of the user's
  426.      * privacy it is recommended to let the user know about it.
  427.      *
  428.      * @param uid the KABC UID you want to send to
  429.      * @param sourceURL a KURL pointing to the file to send
  430.      * @param altFileName an alternate filename describing the file or a
  431.      *        description or title
  432.      * @param fileSize file size in bytes
  433.      *
  434.      * @see messageContact()
  435.      * @see messageNewContact()
  436.      * @see chatWithContact()
  437.      * @see isPresent()
  438.      * @see fileTransferContacts()
  439.      * @see KABC::Addressee::uid()
  440.      */
  441.     virtual void sendFile(const QString &uid, const KURL &sourceURL,
  442.         const QString &altFileName = QString::null, uint fileSize = 0) = 0;
  443.  
  444. // MUTATORS
  445. // Contact list
  446.     /**
  447.      * @brief Add a new contact given its protocol specific identifier
  448.      *
  449.      * Implementations might add the contact silently, including sending an
  450.      * authorization request if necessary, ask the user for confirmation or
  451.      * just prefill the usual contact addingGUI.
  452.      *
  453.      * @param contactId the protocol specific identifier for the contact
  454.      *        e.g. UIN for ICQ, screenname for AIM, nick for IRC
  455.      * @param protocol the IM protocol/service to use. See protocols()
  456.      * @return whether the add succeeded. @c false may signal already present,
  457.      *         protocol not supported, or add operation not supported.
  458.      *
  459.      * @see locate()
  460.      * @see protocols()
  461.      * @see messageNewContact()
  462.      */
  463.     virtual bool addContact( const QString &contactId, const QString &protocol ) = 0;
  464.  
  465. // SIGNALS
  466. k_dcop_signals:
  467.     /**
  468.      * @brief Indicates that a contact's presence has changed
  469.      *
  470.      * Notifies connected DCOP receivers about a change in a contact's
  471.      * presence.
  472.      *
  473.      * Implementations just have to call this method with the appropriate
  474.      * values to get the DCOP signal emitted.
  475.      *
  476.      * @param uid the KABC UID whose presence changed
  477.      * @param appId the DCOP application ID of the program the signal
  478.      *        originates from
  479.      * @param presence the new presence's numeric value. See presenceStatus()
  480.      *
  481.      * @see presenceStatus()
  482.      * @see KABC::Addressee::uid()
  483.      * @see DCOPClient::appId()
  484.      */
  485.     void contactPresenceChanged( QString uid, QCString appId, int presence );
  486. };
  487.  
  488. #endif
  489.  
  490.  
  491.  
  492. /*
  493.  * Local variables:
  494.  * c-indentation-style: k&r
  495.  * c-basic-offset: 8
  496.  * indent-tabs-mode: t
  497.  * End:
  498.  */
  499. // vim: set noet ts=4 sts=4 sw=4:
  500.  
  501.