diff options
Diffstat (limited to 'interfaces/tdeimproxy/interface')
| -rw-r--r-- | interfaces/tdeimproxy/interface/CMakeLists.txt | 22 | ||||
| -rw-r--r-- | interfaces/tdeimproxy/interface/Makefile.am | 13 | ||||
| -rw-r--r-- | interfaces/tdeimproxy/interface/dcopinstantmessenger.desktop | 72 | ||||
| -rw-r--r-- | interfaces/tdeimproxy/interface/kcm_instantmessenger.desktop | 138 | ||||
| -rw-r--r-- | interfaces/tdeimproxy/interface/kimiface.h | 500 |
5 files changed, 745 insertions, 0 deletions
diff --git a/interfaces/tdeimproxy/interface/CMakeLists.txt b/interfaces/tdeimproxy/interface/CMakeLists.txt new file mode 100644 index 000000000..d62819ed8 --- /dev/null +++ b/interfaces/tdeimproxy/interface/CMakeLists.txt @@ -0,0 +1,22 @@ +################################################# +# +# (C) 2010 Serghei Amelian +# serghei (DOT) amelian (AT) gmail.com +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +##### headers ################################### + +install( FILES + kimiface.h + DESTINATION ${INCLUDE_INSTALL_DIR} ) + + +##### other data ################################ + +install( FILES kcm_instantmessenger.desktop DESTINATION ${DATA_INSTALL_DIR}/kcm_componentchooser ) +install( FILES dcopinstantmessenger.desktop DESTINATION ${SERVICETYPES_INSTALL_DIR} ) diff --git a/interfaces/tdeimproxy/interface/Makefile.am b/interfaces/tdeimproxy/interface/Makefile.am new file mode 100644 index 000000000..348130e46 --- /dev/null +++ b/interfaces/tdeimproxy/interface/Makefile.am @@ -0,0 +1,13 @@ +INCLUDES = $(all_includes) + +kimifaceinclude_HEADERS = kimiface.h +kimifaceincludedir = $(includedir) + +servicetypedir = $(kde_servicetypesdir) +servicetype_DATA = dcopinstantmessenger.desktop + +kcm_instantmessenger_DATA = kcm_instantmessenger.desktop +kcm_instantmessengerdir = $(kde_datadir)/kcm_componentchooser + +include $(top_srcdir)/admin/Doxyfile.am +DOXYGEN_REFERENCES = kabc diff --git a/interfaces/tdeimproxy/interface/dcopinstantmessenger.desktop b/interfaces/tdeimproxy/interface/dcopinstantmessenger.desktop new file mode 100644 index 000000000..a69994421 --- /dev/null +++ b/interfaces/tdeimproxy/interface/dcopinstantmessenger.desktop @@ -0,0 +1,72 @@ +[Desktop Entry] +Type=ServiceType +X-TDE-ServiceType=DCOP/InstantMessenger +Comment=Instant Messenger with a DCOP interface +Comment[af]=Oombliklike Boodskapper met DCOP intervlak +Comment[be]=Імгненны абвестнік з інтэрфэйсам DCOP +Comment[bg]=Програма за съобщения в реално време с интерфейс DCOP +Comment[bn]=ডিকপ (DCOP) ইন্টারফেস সহ ইনস্ট্যান্ট মেসেঞ্জার +Comment[bs]=Instant poruke sa DCOP interfejsom +Comment[ca]=Missatgeria instantània amb una interfície DCOP +Comment[cs]=Komunikátor s DCOP rozhraním +Comment[csb]=Internetowi kòmùnikator z interfejsã DCOP +Comment[cy]=Negesydd Chwim efo rhyngwyneb DCOP +Comment[da]=Instant Messenger med en DCOP-grænseflade +Comment[de]=Instant Messenger mit DCOP-Schnittstelle +Comment[el]=Στιγμιαίος αποστολέας με διασύνδεση DCOP +Comment[eo]=Tujmesaĝilo kun DCOP-interfaco +Comment[es]=Instant Messenger con un interfaz DCOP +Comment[et]=Kiirsuhtlemisrakendus DCOP-liidesega +Comment[eu]=Berehalako mezularitza DCOP interfazearekin +Comment[fa]=پیامرسان فوری با یک واسط DCOP +Comment[fi]=Pikaviestiohjelma, jossa on DCOP-rajapinta +Comment[fr]=Messagerie instantanée munie d'une interface DCOP +Comment[fy]=Instant Messenger mei in DCOP-interface +Comment[ga]=Clár teachtaireachtaí meandaracha le comhéadan DCOP +Comment[gl]=Mensaxeria Instantánea con interface DCOP +Comment[he]=תכנת מסרים מידיים עם ממשק DCOP +Comment[hi]=डीकॉप इंटरफेस सहित इंस्टैंट मैसेंजर +Comment[hr]=Trenutne poruke s DCOP sučeljem +Comment[hsb]=Instant Messenger z DCOP-interfejsom +Comment[hu]=Azonnali üzenetküldő DCOP-felülettel +Comment[id]=Instant Messenger dengan antarmuka DCOP +Comment[is]=Spjallforrit með DCOP viðmóti +Comment[it]=Messaggistica istantanea con un'interfaccia DCOP +Comment[ja]=DCOP インターフェースをもつインスタントメッセンジャー +Comment[ka]=DCOP ინტერფეისთან შეტყობინებების გაცვლის შიკრიკი +Comment[kk]=DCOP интерфейсті жедел хабарласу бағдарламасы +Comment[km]=កម្មវិធីជជែកកំសាន្តដែលមានចំណុចប្រទាក់ DCOP +Comment[lb]=Instant Messenger mat engem DCOP-Interface +Comment[lt]=Momentinių žinučių klientas su DCOP sąsaja +Comment[mk]=Инстант Гласник (Messenger) со DCOP интерфејс +Comment[ms]=Utusan Segera dengan antaramuka DCOP +Comment[nb]=Lynmeldingsprogram med DCOP-grensesnitt +Comment[nds]=Kortnarichten-Maker mit DCOP-Koppelsteed +Comment[ne]=DCOP इन्टरफेससँग आवश्यक मेसेन्जर +Comment[nl]=Instant messenger met een DCOP interface +Comment[nn]=Lynmeldingsprogram med DCOP-grensesnitt +Comment[pa]=ਇੱਕ DCOP ਇੰਟਰਫੇਸ ਲਈ ਇੱਕ ਮੌਕਾ ਸੁਨੇਹਾਕਾਰ +Comment[pl]=Komunikator internetowy z interfejsem DCOP +Comment[pt]=Mensageiro Instantâneo com interface DCOP +Comment[pt_BR]=Mensageiro Instantâneo com uma interface DCOP +Comment[ro]=Aplicaţie de mesaje instantanee cu interfaţă DCOP +Comment[ru]=Клиент обмена сообщениями с интерфейсом DCOP +Comment[rw]=Intumwa y'Akokanya ifite imigaragarire DCOP +Comment[se]=Šleađgadiehtoprográmma mas lea DCOP-lákta +Comment[sk]=Instant Messanger s rozhraním DCOP +Comment[sl]=Takojšni sporočilnik z vmesnikom DCOP +Comment[sr]=Брзи гласник са DCOP интерфејсом +Comment[sr@Latn]=Brzi glasnik sa DCOP interfejsom +Comment[sv]=Direktmeddelanden med ett DCOP-gränssnitt +Comment[ta]=உடனடி செய்தியாளர் DCOP இடைமுகத்தோடு +Comment[te]=డిసిఓపి ఇంటర్ఫెస్ కలిగివున్న ఇంస్టెంట్ మెస్సెన్జర్ +Comment[tg]=Мубодилаи паёмҳо бо интерфейси DCOP +Comment[th]=โปรแกรมส่งข้อความแบบทันที ด้วยส่วนติดต่อกับ DCOP +Comment[tr]=DCOP arayüzüyle Anında Mesajlaşma +Comment[tt]=DCOP protokolı belän Aşığıç Xäbärçe +Comment[uk]=Програма для миттєвого зв'язку через DCOP +Comment[vi]=Bộ tin nhắn tức khắc có giao diện DCOP +Comment[wa]=Messaedjreye sol moumint avou ene eterface DCOP +Comment[zh_CN]=带 DCOP 接口的即时通讯程序 +Comment[zh_HK]=附有 DCOP 介面的即時通訊軟件 +Comment[zh_TW]=DCOP 介面的即時通訊系統 diff --git a/interfaces/tdeimproxy/interface/kcm_instantmessenger.desktop b/interfaces/tdeimproxy/interface/kcm_instantmessenger.desktop new file mode 100644 index 000000000..860f82944 --- /dev/null +++ b/interfaces/tdeimproxy/interface/kcm_instantmessenger.desktop @@ -0,0 +1,138 @@ +Name=Instant Messenger +Name[af]=Oombliklike Boodskapper +Name[be]=Імгненны абвеснік +Name[bg]=Съобщения в реално време +Name[bn]=ইনস্ট্যান্ট মেসেঞ্জার +Name[br]=Posteler a-benn-kaer +Name[bs]=Instant poruke +Name[ca]=Missatgeria instantània +Name[cs]=Komunikátor +Name[csb]=Internetowi kòmùnikator +Name[cy]=Negesydd Chwim +Name[el]=Στιγμιαίος αποστολέας +Name[eo]=Tujmesaĝilo +Name[et]=Kiirsuhtlus +Name[eu]=Berehalako mezularitza +Name[fa]=پیامرسان فوری +Name[fi]=Pikaviestiohjelma +Name[fr]=Messagerie instantanée +Name[ga]=Clár teachtaireachtaí meandaracha +Name[gl]=Mensaxeria Instantánea +Name[he]=מסרים מידיים +Name[hi]=इंस्टैंट मैसेंजर +Name[hu]=Azonnali üzenetküldő +Name[is]=Spjallforrit +Name[it]=Messaggistica istantanea +Name[ja]=インスタントメッセンジャー +Name[ka]=შიკრიკი +Name[kk]=Жедел хабарласу +Name[km]=កម្មវិធីវិធីជជែកកំសាន្ត +Name[lt]=Momentinių žinučių klientas +Name[mk]=Инстант Гласник (Messenger) +Name[ms]=Mesej Segera +Name[nb]=Lynmelding +Name[nds]=Kortnarichten-Maker +Name[ne]=आवश्यक मेसेन्जर +Name[nl]=Instant messenger +Name[nn]=Lynmelding +Name[pa]=ਮੌਕਾ ਸੁਨੇਹਾਕਾਰ +Name[pl]=Komunikator internetowy +Name[pt]=Mensageiro Instantâneo +Name[pt_BR]=Mensagem Instantâneo +Name[ro]=Mesaje instantanee +Name[ru]=Обмен сообщениями +Name[se]=Šleađgadieđut +Name[sl]=Takojšni sporočilnik +Name[sr]=Брзи гласник +Name[sr@Latn]=Brzi glasnik +Name[sv]=Direktmeddelanden +Name[ta]=உடனடி செய்தியாளர் +Name[te]=ఇంస్టెంట్ మెస్సెన్జర్ +Name[tg]=Мубодилаи паёмҳо +Name[th]=โปรแกรมส่งข้อความทันที +Name[tr]=Anında Mesajlaşma +Name[tt]=Aşığıç Xäbärçe +Name[uk]=Програма для миттєвого зв'язку через DCOP +Name[uz]=Xabar almashish vositasi +Name[uz@cyrillic]=Хабар алмашиш воситаси +Name[vi]=Bộ tin nhắn tức khắc +Name[wa]=Messaedjreye sol moumint +Name[zh_CN]=即时通讯程序 +Name[zh_HK]=即時通訊軟件 +Name[zh_TW]=即時通訊 +Comment=The instant messenger allows two-way chat between individuals and groups. +Comment[af]=Die oombliklike boodskappe laat twee rigting kommunikasie tussen individue en groepe toe. +Comment[be]=Імгненны абвеснік дазваляе весці размову двум і больш асобам/гуртам. +Comment[bg]=Разговор между различни хора в реално време. +Comment[bn]=ইনস্ট্যান্ট মেসেঞ্জার একাধিক ব্যক্তি বা গোষ্ঠীকে দ্বিমুখী বার্তালাপ বা আড্ডার সুযোগ দেয়। +Comment[bs]=Program za instant poruke omogućuje dvosmjernu komunikaciju između pojedinaca i grupa. +Comment[ca]=La missatgeria instantània permet converses en dos sentits entre individus i grups. +Comment[cs]=Komunikátor vám umožňuje obousměrný rozhovor s jednotlivci nebo skupinami. +Comment[csb]=Internetowi kòmùnikator dôwô mòżnota kôrbionczi midzë lëdzama ë karnama. +Comment[cy]=Mae'r negesydd chwim yn caniatàu sgwrs dwy-ffordd rhwng unigolion a grwpiau. +Comment[da]=Instant messenger tillader tovejs chat mellem individer og grupper. +Comment[de]=Der Instant Messenger ermöglicht Chats zwischen Personen und Gruppen in jede Richtung. +Comment[el]=Ο στιγμιαίος αποστολέας επιτρέπει τη συζήτηση μεταξύ ατόμων και ομάδων. +Comment[eo]=La tujmesaĝilo ebligas ambaŭdirekta parolado inter homoj kaj grupoj +Comment[es]=El Instant Messenger permite conversación en dos sentidos entre indivíduos y grupos. +Comment[et]=Kiirsuhtlus võimaldab üksikisikute ja gruppide kahepoolset vestlust. +Comment[eu]=Berehalako mezularitzak banan-banako edo taldeen arteko berriketan aritzeko. +Comment[fa]=پیامرسان فوری امکان گپ دو طرفه بین افراد و گروهها را میدهد. +Comment[fi]=Pikaviestiohjelman avulla voidaan keskustella kahden kesken tai ryhmässä. +Comment[fr]=La messagerie instantanée permet un dialogue bidirectionnel entre individus et groupes. +Comment[fy]=Mei de instant messenger kinne jo twaspraak hâlde mei in yndividu en groepen. +Comment[ga]=Is féidir comhrá déthreoch a dhéanamh idir daoine agus grúpaí leis an gclár teachtaireachtaí meandaracha. +Comment[gl]=O instant messenger permite conversas nos dous sentidos entre indivíduos e grupos. +Comment[he]=תוכנת מסרים מידיים מאשרת לשוחח ברשת (לצ'טט) בין יחידים או קבוצות +Comment[hi]=इंस्टैंट मैसेंजर जो व्यक्तियों या समूहों के बीच दो-तरफा गपशप स्वीकारता है. +Comment[hr]=Trenutne poruke omogućuju dvosmjerno brbljanje između pojedinaca i grupa. +Comment[hsb]=Instant messenger zmóžni jednotliwcam a skupinam spěšnu wuměnu zdźělenkow. +Comment[hu]=Interaktív társalgást tesz lehetővé az interneten keresztül két személy vagy csoport között. +Comment[id]=Instant messenger memungkinan chat dua-arah antara individu dan grup +Comment[is]=Spjallforritið gerir einstaklingum og hópum kleyft að spjalla saman á einfaldan máta. +Comment[it]=La messaggistica istantanea permette di chiacchierare tra due persone o in gruppo. +Comment[ja]=インスタントメッセンジャーは個人とグループとの双方向チャットを可能にします。 +Comment[ka]=შიკრიკი პიროვნებებსა და ჯგუფებს შორის მყისი შეტყობინებების გაცვლის საშუალებას იძლევა. +Comment[kk]=Жедел хабарласу жеке тұлға және топтар араларында әңгімелесу мүмкіндігін береді. +Comment[km]=កម្មវិធីជជែកកំសាន្តអនុញ្ញាតឲ្យជជែកតាមរបៀបពីរបែបរវាងបុគ្គល និងក្រុម ។ +Comment[lb]=Den Instant Messenger erlaabt eng zwee-Weeër Kommunikatioun tëschent eenzelne Persounen a Gruppen. +Comment[lt]=Momentinių žinučių klientas kalbėtis individams ir grupėms. +Comment[mk]=Инстант гласникот овозможува двонасочна комуникација меѓу индивидуи и групи. +Comment[ms]=Utusan segera membenarkan perbualan di antara individu dan kumpulan. +Comment[nb]=Et lynmeldingsprogram som tallater toveis samtale mellom enkeltpersoner og grupper. +Comment[nds]=Mit den Kortnarichten-Maker köönt enkelte Minschen oder Gruppen ünnerenanner snacken. +Comment[ne]= आवश्यक मेसेन्जरले एकल र समूहहरुबीच दोहोरो कुराकानीलाई अनुमति दिन्छ । +Comment[nl]=De instant messenger maakt directe communicatie tussen personen of groepen mogelijk. +Comment[nn]=Eit lynmeldingsprogram som tillèt tovegsprat mellom enkeltpersonar og grupper. +Comment[pa]=ਇਹ ਮੌਕਾ ਸੁਨੇਹਾਕਾਰ ਇੱਕਲੇ ਤੇ ਸਮੂਹ ਵਿਚਕਾਰ ਦੋ ਪਾਸੀ ਗਲਬਾਤ ਲਈ ਸਹਾਇਕ ਹੈ +Comment[pl]=Komunikator internetowy umożliwia pogawędki między dwiema osobami lub grupami osób. +Comment[pt]=O mensageiro instantâneo permite conversar entre dois extremos com indivíduos e com grupos. +Comment[pt_BR]=O mensageiro instantâneo permite que exista um bate-papo entre indivíduos e grupos +Comment[ro]=Aplicaţia de mesaje instantanee permite convorbiri între persoane sau grupuri de persoane. +Comment[ru]=Клиент обмена сообщениями служит для обмена сообщениями между людьми и группами. +Comment[rw]=Intumwa y'Akokanya yemerera inzira-zombi z'ikiganiroInterineti hagati y'abantu ubwabo n'amatsinda +Comment[se]=Šleađgadiehtoprográmma gos olbmot ja joavkkut sáhttet buillardallat (chat). +Comment[sk]=Instant messenger umožňuje rozhovor medzi rôznymi osobami a skupinami. +Comment[sl]=Takojšni sporočilnik omogoča dvosmeren klepet med posamezniki in skupinami. +Comment[sr]=Брзи гласник вам омогућава двосмерно ћаскање између појединаца и група. +Comment[sr@Latn]=Brzi glasnik vam omogućava dvosmerno ćaskanje između pojedinaca i grupa. +Comment[sv]=Direktmeddelanden möjliggör tvåvägschatt mellan individer och grupper. +Comment[ta]=உடனடி தகவல் உங்களை இரண்டு வழியில் தனிநபர் மற்றும் குழுக்கள் இடையே அனுமதிக்கும். +Comment[te]=ఇంస్టెంట్ మెస్సెన్జర్ వ్యక్తు లు మరయు గుంపుల తొ ఇరువయపుల నుంచి సంబాషించవచ్చు +Comment[tg]=Мубодилаи паёмҳо барои сӯҳбат бо шахсони ҷудогона ва гурӯҳӣ иҷозат медиҳад. +Comment[th]=โปรแกรมส่งข้อความแบบทันที จะอนุญาตให้มีการพูดคุยสองทาง ทั้งระหว่าง บุคคลและกลุ่ม +Comment[tr]=Anında mesajlaştırıcı iki yollu sohbet sağlar: bireyler ve gruplar. +Comment[tt]=Bu aşığıç xäbärçe aşa keşe-törkemnär arasında ike-yaqlı aralaşu mömkinlegen birä. +Comment[uk]=Програма для миттєвого зв'язку дозволяє розмовляти з іншою людиною чи групою людей. +Comment[vi]=Bộ tin nhắn tức khắc cho phép trò chuyện hai chiều giữa người riêng và nhóm. +Comment[wa]=Li messaedjreye sol moumint permete di berdeler dins les deus sinses etur deus djins ou e groupe. +Comment[zh_CN]=允许在个人和群组之间双向聊天的即时通讯程序。 +Comment[zh_HK]=即時通訊軟件可以讓用戶和別的用戶或羣組通訊。 +Comment[zh_TW]=即時通訊系統允許兩個人或兩個群組間的聊天與對話 +ServiceTypeToConfigure=DCOP/InstantMessenger +MimeTypeOfInterest=DCOP/InstantMessenger +defaultImplementation=kopete +storeInFile=default_components +valueSection=InstantMessenger +valueName=imClient +configurationType=component diff --git a/interfaces/tdeimproxy/interface/kimiface.h b/interfaces/tdeimproxy/interface/kimiface.h new file mode 100644 index 000000000..f3212df6d --- /dev/null +++ b/interfaces/tdeimproxy/interface/kimiface.h @@ -0,0 +1,500 @@ +/* + 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 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( 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: + |