kopete/protocols/skype/libskype/skype.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2005 Michal Vaner <michal.vaner@kdemail.net>
   3     Copyright (C) 2008-2009 Pali Rohár <pali.rohar@gmail.com>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License version 2 as published by the Free Software Foundation.
   8
   9     This library is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     Library General Public License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to
  16     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17     Boston, MA 02111-1307, USA.
  18
  19 */
  20 #ifndef SKYPE_H
  21 #define SKYPE_H
  22
  23 #include <qobject.h>
  24
  25 class SkypePrivate;
  26 class SkypeAccount;
  27
  28 /**
  29  * @author Kopete Developers
  30  * @author Pali Rohár
  31  * This class is internal backend for skype. It provides slots for such things like "send a IM" and so
  32  */
  33 class Skype : public QObject
  34 {
  35         Q_OBJECT
  36         private:
  37                 ///The d pointer for private things
  38                 SkypePrivate *d;
  39                 /**
  40                  * Will try to hitchhike a message. It will hitchhike it, show it in the proper chat session and so on, but just when it is enabled by hitchhike mode and will maker it as read if enabled
  41                  * @param messageId ID of the message to hitchHike
  42                  */
  43                 void hitchHike(const QString &messageId);
  44         private slots:
  45                 /**
  46                  * Adds new message do be sent to skype (normaly is sent imediatelly).
  47                  * If there is no connection to skype, it is created before it is sent.
  48                  * @param message Message to send to skype
  49                  * @param deleteQueue If this is true, all message waiting to be sent are deleted and only this one stays in the queue
  50                  */
  51                 void queueSkypeMessage(const QString &message, bool deleteQueue);
  52                 /**
  53                  * Listens for closed skype connection
  54                  */
  55                 void closed(int reason);
  56                 /**
  57                  * Listens for finishing the connecting attempt and sending the queue if it was successful
  58                  * @param error - Did it work or was there some error?
  59                  * @param protocolVer - Version of protocol used by this connection
  60                  */
  61                 void connectionDone(int error, int protocolVer);
  62                 /**
  63                  * This one showes an error message
  64                  * @param message What to write on the dialog box
  65                  */
  66                 void error(const QString &message);
  67                 /**
  68                  * This one scans messages from Skype API and acts acordingly to them (changing online status, showing messages....
  69                  * @param message What the skype said
  70                  */
  71                 void skypeMessage(const QString &message);
  72                 /**
  73                  * This one resets the online status showed on the icon in kopete depending on last values from skype.
  74                  * Used when the status changes
  75                  */
  76                 void resetStatus();
  77                 /**
  78                  * Makes the Skype search for something and saves what it was to decide later, what to do with it
  79                  * @param what What are we searching for
  80                  */
  81                 void search(const QString &what);
  82                 /**
  83                  * Fix all contact in groups
  84                  */
  85                 void fixGroups(bool loadOnly = false);
  86         public:
  87                 /**
  88                  * Constructor
  89                  * @param account The account that this connection belongs to
  90                  */
  91                 Skype(SkypeAccount &account);
  92                 /**
  93                  * Destructor
  94                  */
  95                 ~Skype();
  96                 ///Can we comunicate with the skype program right now?
  97                 bool canComunicate();
  98                 /**
  99                  * Enables or disables hitchhake mode of incoming messages
 100                  * @see SkypeAccount::setHitchHike
 101                  */
 102                 void setHitchMode(bool value);
 103                 /**
 104                  * Enables or disables mark read messages mode
 105                  * @see SkypeAccount::setMarkRead
 106                  */
 107                 void setMarkMode(bool value);
 108                 /**
 109                  * Enables/disables scanning for unread messages after login
 110                  * @see SkypeAccount::setScanForUnread
 111                  */
 112                 void setScanForUnread(bool value);
 113                 /**
 114                  * Is that call incoming call?
 115                  * @param callId What call you mean?
 116                  * @return true if the call is incoming
 117                  */
 118                 bool isCallIncoming(const QString &callId);
 119                 /**
 120                  * Returns ID of chat to what given message belongs
 121                  * @param messageId Id of the wanted message
 122                  * @return ID of the chat. For unexisten message the result is not defined.
 123                  */
 124                 QString getMessageChat(const QString &messageId);
 125                 /**
 126                  * Returns list of users in that chat without actual user
 127                  * @param chat ID of that chat you want to know
 128                  */
 129                 QStringList getChatUsers(const QString &chat);
 130                 /**
 131                  * This will return ID of the actual user this one that uses this skype
 132                  */
 133                 QString getMyself();
 134                 /**
 135                  * Create a chat with that members
 136                  * @param users List of users separated by coma (user_1, user_2, user...)
 137                  * @return Id of the new chat
 138                  */
 139                 QString createChat(const QString &users);
 140                 /**
 141                  * Says if the contact should be authorize, not authorized or blocked
 142                  */
 143                 enum AuthorType {
 144                         Author,
 145                         Deny,
 146                         Block
 147                 };
 148                 /**
 149                  * Ask if the user how is the user authorized
 150                  * @param contactId What user are you interested in?
 151                  */
 152                 AuthorType getAuthor(const QString &contactId);
 153                 /**
 154                  * Is this version of protocol able to create conference calls?
 155                  */
 156                 bool ableConference();
 157                 /**
 158                  * Get group name, where is contact
 159                  * @param name Skype contact name
 160                  * @return group id, where is contact
 161                  */
 162                 int getContactGroupID(const QString &name);
 163                 /**
 164                  * Remove user from group
 165                  * @param name Skype contact name
 166                  * @param groupID Skype group id
 167                  */
 168                 void removeFromGroup(const QString &name, int groupID);
 169                 /**
 170                  * Add user to group
 171                  * @param name Skype contact name
 172                  * @param groupID Skype group id
 173                  */
 174                 void addToGroup(const QString &name, int groupID);
 175                 /**
 176                  * Create Skype group
 177                  * @param name Group name
 178                  */
 179                 void createGroup(const QString &name);
 180                 /**
 181                  * Remove Skype group
 182                  * @param groupID Skype group id
 183                  */
 184                 void deleteGroup(int groupID);
 185                 /**
 186                  * Rename Skype group
 187                  * @param groupID Skype group id
 188                  * @param newName New group name
 189                  */
 190                 void renameGroup(int groupID, const QString &newName);
 191                 /**
 192                  * Get group id
 193                  * @param groupname name
 194                  * @return groupID
 195                  */
 196                 int getGroupID(const QString &groupname);
 197                 /**
 198                  * Get group name
 199                  * @param groupID groupID
 200                  * @return group name
 201                  */
 202                 QString getGroupName(int groupID);
 203                 /**
 204                  * Get Skype display name
 205                  * @param name Skype name
 206                  * @return Skype display name
 207                  */
 208                 QString getDisplayName(const QString &name);
 209                 /**
 210                  * Open skype file transfer dilog to send file via skype
 211                  */
 212                 void openFileTransfer(const QString &user, const QString &url = QString::null);
 213         public slots:
 214                 /**
 215                  * Tell the skype to go online
 216                  */
 217                 void setOnline();
 218                 /**
 219                  * Tell the skype to go offline
 220                  */
 221                 void setOffline();
 222                 /**
 223                  * Tell the skype to go offline
 224                  */
 225                 void setAway();
 226                 /**
 227                  * Tell the skype to go not available
 228                  */
 229                 void setNotAvailable();
 230                 /**
 231                  * Tell the skype to go to Do not disturb
 232                  */
 233                 void setDND();
 234                 /**
 235                  * Tell the skype to go to Skype me mode
 236                  */
 237                 void setSkypeMe();
 238                 /**
 239                  * Tell the skype to go invisible
 240                  */
 241                 void setInvisible();
 242                 /**
 243                  * This sets the values of the account.
 244                  * @see SkypeAccount
 245                  */
 246                 void setValues(int launchType, const QString &appName);
 247                 /**
 248                  * Retrieve info of that contact
 249                  * @param contact What contact wants it
 250                  */
 251                 void getContactInfo(const QString &contact);
 252                 /**
 253                  * Asks skype for buddy status of some contact. Buddystatus is some property that ondicates, weather it is in contact list, awaiting authorization, just been mentioned or what exactly happened with it..
 254                  * After skype responses, you will get the response by emiting the received signal
 255                  * @param contact It is the contact id of the user you want to check.
 256                  */
 257                 void getContactBuddy(const QString &contact);
 258                 /**
 259                  * Sends a message trough skype
 260                  * @param user To who it should be sent
 261                  * @param body What to send
 262                  */
 263                 void send(const QString &user, const QString &body);
 264                 /**
 265                  * Send a message to a given chat
 266                  * @param chat What chat to send it in
 267                  * @param body Text of that message
 268                  */
 269                 void sendToChat(const QString &chat, const QString &body);
 270                 /**
 271                  * Begins new call.
 272                  * @param userId ID of user to call (or multiple users separated by comas)
 273                  * @see acceptCall
 274                  * @see hangUp
 275                  * @see holdCall
 276                  * @see callStatus
 277                  * @see callError
 278                  */
 279                 void makeCall(const QString &userId);
 280                 /**
 281                  * Accept an incoming call
 282                  * @param callId ID of call to accept.
 283                  * @see makeCall
 284                  * @see hangUp
 285                  * @see holdCall
 286                  * @see callStatus
 287                  * @see callError
 288                  * @see newCall
 289                  */
 290                 void acceptCall(const QString &callId);
 291                 /**
 292                  * Hang up (finish) call in progress or deny an incoming call
 293                  * @param callId Which one
 294                  * @see makeCall
 295                  * @see acceptCall
 296                  * @see holdCall
 297                  * @see callStatus
 298                  * @see callError
 299                  * @see newCall
 300                  */
 301                 void hangUp(const QString &callId);
 302                 /**
 303                  * Hold call in progress or resume holded call. That call will not finish, you just leave it for later.
 304                  * @param callId Which call
 305                  * @see makeCall
 306                  * @see acceptCall
 307                  * @see hangUp
 308                  * @see callStatus
 309                  * @see callError
 310                  * @see newCall
 311                  */
 312                 void toggleHoldCall(const QString &callId);
 313                 /**
 314                  * Get the skoype out balance
 315                  */
 316                 void getSkypeOut();
 317                 /**
 318                  * Sets if the Skype is checked in short intervals by pings. If you turn that off, you will not know when skype exits.
 319                  * @param enabled Ping or not?
 320                  */
 321                 void enablePings(bool enabled);
 322                 /**
 323                  * Sends one ping and takes actions if it can not be delivered (skype is down)
 324                  */
 325                 void ping();
 326                 /**
 327                  * What DBus bus is used?
 328                  */
 329                 void setBus(int bus);
 330                 /**
 331                  * Set the launch timeout - after that launch of Skype will be considered as unsuccessfull if connection can not be established
 332                  */
 333                 void setLaunchTimeout(int seconds);
 334                 /**
 335                  * Set a command to start skype by
 336                  */
 337                 void setSkypeCommand(const QString &command);
 338                 /**
 339                  * Sets if we wait a bit before connecting to Skype after it's start-up
 340                  */
 341                 void setWaitConnect(int value);
 342                 /**
 343                  * This gets a topic for given chat session
 344                  * @param chat What chat wants that
 345                  */
 346                 void getTopic(const QString &chat);
 347                 /**
 348                  * Invites a user to a chat
 349                  * @param chatId What chat
 350                  * @param userId What user
 351                  */
 352                 void inviteUser(const QString &chatId, const QString &userId);
 353                 /**
 354                  * Closes/leaves a chat
 355                  * @param chatId What chat
 356                  */
 357                 void leaveChat(const QString &chatId);
 358                 /**
 359                  * Removes a contact from the contact list
 360                  * @param contactId Id of the contact you want to remove
 361                  */
 362                 void removeContact(const QString &contactId);
 363                 /**
 364                  * Adds a contact to the list
 365                  * @param contactId Id of the contact to add
 366                  * @param contactId
 367                  */
 368                 void addContact(const QString &contactId);
 369                 /**
 370                  * Sets users authorization
 371                  * @param contactId ID of that user
 372                  * @param author for what is he authorized
 373                  */
 374                 void setAuthor(const QString &contactId, AuthorType author);
 375         signals:
 376                 /**
 377                  * Emitted when the skype changes to online (or says it goes online)
 378                  */
 379                 void wentOnline();
 380                 /**
 381                  * Emitted when the skype goes offline
 382                  */
 383                 void wentOffline();
 384                 /**
 385                  * Emitted when the skype goes away
 386                  */
 387                 void wentAway();
 388                 /**
 389                  * Emitted when the skype goes to Not awailable
 390                  */
 391                 void wentNotAvailable();
 392                 /**
 393                  * Emitted when the skype goes to DND mode
 394                  */
 395                 void wentDND();
 396                 /**
 397                  * Emitted when skype changes to skype me mode
 398                  */
 399                 void wentSkypeMe();
 400                 /**
 401                  * Emitted when skype becomes invisible
 402                  */
 403                 void wentInvisible();
 404                 /**
 405                  * Emitted when atempt to connect started
 406                  */
 407                 void statusConnecting();
 408                 /**
 409                  * Emitted when new user should be added to the list
 410                  * @param name The skype name of the user
 411                  * @param groupID The skype group id, where is user
 412                  */
 413                 void newUser(const QString &name, int groupID);
 414                 /**
 415                  * All contacts should be asked to request update of their information. This is emitted after the connection to skype is made.
 416                  */
 417                 void updateAllContacts();
 418                 /**
 419                  * This is emitted whenever some contact should be notified of info change
 420                  * @param contact What contact is it
 421                  * @param change The change. The syntax is [property (displayname, onlinestatus..)] [value]
 422                  */
 423                 void contactInfo(const QString &contact, const QString &change);
 424                 /**
 425                  * This is emitted when a new message is received
 426                  * @param user Contact ID of user that sent it. It is NOT guaranteed that the user is in list!
 427                  * @param body The message body that was received
 428                  * @param messageId ID of that message
 429                  */
 430                 void receivedIM(const QString &user, const QString &body, const QString &messageId);
 431                 /**
 432                  * This is emitted when a new message from multi-user chat is received
 433                  * @param chat Id of the chat
 434                  * @param body Tect of the message
 435                  * @param messageId Id of this message to get information about it if needed
 436                  * @param user Who sent it to that chat (ID)
 437                  */
 438                 void receivedMultiIM(const QString &chat, const QString &body, const QString &messageId, const QString &user);
 439                 /**
 440                  * This is emitted when an Id of the last outgoing message is known
 441                  * @param id The ID of that message
 442                  */
 443                 void gotMessageId(const QString &id);
 444                 /**
 445                  * This slot notifies about call status (onhold, in progress, routing, finished..)
 446                  * @param callId WHat call is it?
 447                  * @param status New status of the call.
 448                  * @see makeCall
 449                  * @see acceptCall
 450                  * @see hangUp
 451                  * @see holdCall
 452                  * @see callError
 453                  * @see newCall
 454                  */
 455                 void callStatus(const QString &callId, const QString &status);
 456                 /**
 457                  * This slot informs of error that happened to the call. It is translated error and can be directly showed to user.
 458                  * @param callId ID of the call that has an error.
 459                  * @param message The error text
 460                  * @see makeCall
 461                  * @see acceptCall
 462                  * @see hangUp
 463                  * @see holdCall
 464                  * @see callStatus
 465                  * @see newCall
 466                  */
 467                 void callError(const QString &callId, const QString &message);
 468                 /**
 469                  * Indicates a new call is established (is being established, incoming or so). In short, there is some new call.
 470                  * @param callId ID of the new call
 471                  * @param userId ID of the other user, or list of users (if more than one) divided by spaces
 472                  * @see makeCall
 473                  * @see acceptCall
 474                  * @see hangUp
 475                  * @see holdCall]
 476                  * @see callStatus
 477                  * @see callError
 478                  */
 479                 void newCall(const QString &callId, const QString &userId);
 480                 /**
 481                  * Skype out balance info
 482                  * @param balance How much does the user have
 483                  * @param currency And what is it that he has
 484                  */
 485                 void skypeOutInfo(int balance, const QString &currency);
 486                 /**
 487                  * Tells that my name is known or changed
 488                  * @param name The new name
 489                  */
 490                 void setMyselfName(const QString &name);
 491                 /**
 492                  * Some topic has to be set
 493                  * @param chat What chat should change its topic
 494                  * @param topic The new topic
 495                  */
 496                 void setTopic(const QString &chat, const QString &topic);
 497                 /**
 498                  * This is emitted when a new user joins a chat
 499                  * @param chat What chat he joined
 500                  * @param userId ID of the new user
 501                  */
 502                 void joinUser(const QString &chat, const QString &userId);
 503                 /**
 504                  * This is emitted when user leaves a chat
 505                  * @param chat What chat did he leave
 506                  * @param userId ID of that user
 507                  * @param reason Reason why he left
 508                  */
 509                 void leftUser(const QString &chat, const QString &userd, const QString &reason);
 510                 /**
 511                  * Emitted when some message is being sent out right now
 512                  * @param body Text of the message
 513                  * @param chat Id of the chat it has been sent to
 514                  */
 515                 void outgoingMessage(const QString &body, const QString &chat);
 516                 /**
 517                  * Put this call into a group, where other calls are (will be), used with conference calls
 518                  * @param callId Id of the call
 519                  * @param groupId The id of a group
 520                  * Note: the group should be closed when all it's calls are closed
 521                  */
 522                 void groupCall(const QString &callId, const QString &groupId);
 523 };
 524
 525 #endif