← Back to branch summary

~ubuntu-branches/ubuntu/saucy/kopete/saucy-proposed

« back to all changes in this revision

Viewing changes to kopete/kimiface.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2013-06-21 02:22:39 UTC
  • Revision ID: package-import@ubuntu.com-20130621022239-63l3zc8p0nf26pt6
Tags: upstream-4.10.80
Import upstream version 4.10.80

Show diffs side-by-side

added added

removed removed

Lines of Context:
kopete/kimiface.h
 
1
/*
 
2
    kimiface.h - KDE Instant Messenger DCOP Interface
 
3
        
 
4
        Copyright (c) 2004    Will Stephenson    <wstephenson@kde.org>
 
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
//Added by qt3to4:
 
27
#include <QByteArray>
 
28
#include <dcopobject.h>
 
29
#include <qstringlist.h>
 
30
#include <kurl.h>
 
31
 
 
32
/**
 
33
 * Generic DCOP interface for KDE instant messenger applications
 
34
 * Note one omission of this interface is the lack of control over the range of values used for protocols' names.
 
35
 * @author Will Stephenson <wstephenson@kde.org>
 
36
 */
 
37
class KIMIface : virtual public DCOPObject
 
38
{
 
39
        K_DCOP
 
40
 
 
41
k_dcop:
 
42
// ACCESSORS
 
43
// contact list
 
44
        /**
 
45
         * Obtain a list of IM-contactable entries in the KDE 
 
46
         * address book.
 
47
         * @return a list of KABC uids.
 
48
         */
 
49
        virtual QStringList allContacts() = 0;
 
50
        /**
 
51
         * Obtain a list of  KDE address book entries who are 
 
52
         * currently reachable.
 
53
         * @return a list of KABC uids who can receive a message, even if online.
 
54
         */
 
55
        virtual QStringList reachableContacts() = 0;
 
56
        /**
 
57
         * Obtain a list of  KDE address book entries who are 
 
58
         * currently online.
 
59
         * @return a list of KABC uids who are online with unspecified presence.
 
60
         */
 
61
        virtual QStringList onlineContacts() = 0;
 
62
        /**
 
63
         * Obtain a list of  KDE address book entries who may
 
64
         * receive file transfers.
 
65
         * @return a list of KABC uids capable of file transfer.
 
66
         */
 
67
        virtual QStringList fileTransferContacts() = 0;
 
68
        
 
69
// individual
 
70
        /** 
 
71
         * Confirm if a given KABC uid is known to KIMProxy
 
72
         * @param uid the KABC uid you are interested in.
 
73
         * @return whether one of the chat programs KIMProxy talks to knows of this KABC uid.
 
74
         */
 
75
        virtual bool isPresent( const QString & uid ) = 0;
 
76
        /**
 
77
         * Obtain the IM app's idea of the contact's display name
 
78
         * Useful if KABC lookups may be too slow
 
79
         * @param KABC uid.
 
80
         * @return The corresponding display name.
 
81
         */
 
82
        virtual QString displayName( const QString & uid ) = 0;
 
83
        /**
 
84
         * Obtain the IM presence as a i18ned string for the specified addressee
 
85
         * @param uid the KABC uid you want the presence for.
 
86
         * @return the i18ned string describing presence.
 
87
         */
 
88
        virtual QString presenceString( const QString & uid ) = 0;
 
89
        /**
 
90
         * Obtain the IM presence as a number (see KIMIface) for the specified addressee
 
91
         * @param uid the KABC uid you want the presence for.
 
92
         * @return a numeric representation of presence - currently one of 0 (Unknown), 1 (Offline), 2 (Connecting), 3 (Away), 4 (Online)
 
93
         */
 
94
        virtual int presenceStatus( const QString & uid ) = 0;
 
95
        /**
 
96
         * Indicate if a given uid can receive files 
 
97
         * @param uid the KABC uid you are interested in.
 
98
         * @return Whether the specified addressee can receive files.
 
99
         */
 
100
        virtual bool canReceiveFiles( const QString & uid ) = 0;
 
101
        /** 
 
102
         * Some media are unidirectional (eg, sending SMS via a web interface).
 
103
         * @param uid the KABC uid you are interested in.
 
104
         * @return Whether the specified addressee can respond.
 
105
         */
 
106
        virtual bool canRespond( const QString & uid ) = 0;
 
107
        /**
 
108
         * Get the KABC uid corresponding to the supplied IM address
 
109
         * Protocols should be 
 
110
         * @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
 
111
         * @param protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol", 
 
112
         * @return a KABC uid or null if none found/
 
113
         */
 
114
        virtual QString locate( const QString & contactId, const QString & protocol ) = 0;
 
115
// metadata
 
116
        /**
 
117
         * Obtain the icon representing IM presence for the specified addressee
 
118
         * @param uid the KABC uid you want the presence for.
 
119
         * @return a pixmap representing the uid's presence.
 
120
         */
 
121
        virtual QPixmap icon( const QString & uid ) = 0;
 
122
        /**
 
123
         * Get the supplied addressee's current context (home, work, or any).  
 
124
         * @param uid the KABC uid you want the context for.
 
125
         * @return A QString describing the context, or null if not supported.
 
126
         */
 
127
        virtual QString context( const QString & uid ) = 0;
 
128
// App capabilities
 
129
        /**
 
130
         * Discover what protocols the application supports
 
131
         * @return the set of protocols that the application supports
 
132
         */
 
133
        virtual QStringList protocols() = 0;
 
134
        
 
135
// ACTORS
 
136
        /**
 
137
         * Send a single message to the specified addressee
 
138
         * Any response will be handled by the IM client as a normal 
 
139
         * conversation.
 
140
         * @param uid the KABC uid you want to chat with.
 
141
         * @param message the message to send them.
 
142
         */
 
143
        virtual void messageContact( const QString &uid, const QString& message ) = 0;
 
144
 
 
145
        /**
 
146
         * Open a chat to a contact, and optionally set some initial text
 
147
         */
 
148
        virtual void messageNewContact( const QString &contactId, const QString &protocol ) = 0;
 
149
 
 
150
        /**
 
151
         * Start a chat session with the specified addressee
 
152
         * @param uid the KABC uid you want to chat with.
 
153
         */
 
154
        virtual void chatWithContact( const QString &uid ) = 0;
 
155
 
 
156
        /**
 
157
         * Send the file to the contact
 
158
         * @param uid the KABC uid you are sending to.
 
159
         * @param sourceURL a @ref KUrl to send.
 
160
         * @param altFileName an alternate filename describing the file
 
161
         * @param fileSize file size in bytes
 
162
         */
 
163
        virtual void sendFile(const QString &uid, const KUrl &sourceURL,
 
164
                const QString &altFileName = QString(), uint fileSize = 0) = 0;
 
165
 
 
166
// MUTATORS
 
167
// Contact list
 
168
        /**
 
169
         * Add a contact to the contact list
 
170
         * @param contactId the protocol specific identifier for the contact, eg UIN for ICQ, screenname for AIM, nick for IRC.
 
171
         * @param protocol the protocol, eg one of "AIMProtocol", "MSNProtocol", "ICQProtocol", ...
 
172
         * @return whether the add succeeded.  False may signal already present, protocol not supported, or add operation not supported.
 
173
         */
 
174
        virtual bool addContact( const QString &contactId, const QString &protocol ) = 0;
 
175
// SIGNALS
 
176
k_dcop_signals:
 
177
        /**
 
178
         * Indicates that a contact's presence has changed
 
179
         * @param uid the contact whose presence changed.
 
180
         * @param appId the dcop application id of the program the signal originates from.
 
181
         * @param presence the new numeric presence @ref presenceStatus
 
182
         */
 
183
        void contactPresenceChanged( QString uid, QByteArray appId, int presence );
 
184
};
 
185
 
 
186
#endif
 
187
 
 
188
 
 
189
 
 
190
/*
 
191
 * Local variables:
 
192
 * c-indentation-style: k&r
 
193
 * c-basic-offset: 8
 
194
 * indent-tabs-mode: t
 
195
 * End:
 
196
 */
 
197
// vim: set noet ts=4 sts=4 sw=4:
 
198