kopete/protocols/oscar/liboscar/client.h

   1 /*
   2         Kopete Oscar Protocol
   3         client.h - The main interface for the Oscar protocol
   4
   5         Copyright (c) 2004-2005 by Matt Rogers <mattr@kde.org>
   6
   7         Based on code Copyright (c) 2004 SuSE Linux AG <http://www.suse.com>
   8         Based on Iris, Copyright (C) 2003  Justin Karneges
   9
  10         Kopete (c) 2002-2005 by the Kopete developers <kopete-devel@kde.org>
  11
  12         *************************************************************************
  13         *                                                                       *
  14         * This library is free software; you can redistribute it and/or         *
  15         * modify it under the terms of the GNU Lesser General Public            *
  16         * License as published by the Free Software Foundation; either          *
  17         * version 2 of the License, or (at your option) any later version.      *
  18         *                                                                       *
  19         *************************************************************************
  20 */
  21
  22
  23 #ifndef LIBOSCAR_CLIENT_H
  24 #define LIBOSCAR_CLIENT_H
  25
  26 #include <qobject.h>
  27 #include <qstring.h>
  28 #include <QList>
  29 #include <QByteArray>
  30 #include "kopete_export.h"
  31 #include "rtf2html.h"
  32 #include "transfer.h"
  33 #include "icquserinfo.h"
  34 #include "userdetails.h"
  35 #include "oscartypeclasses.h"
  36 #include "oscarmessage.h"
  37 #include "contact.h"
  38
  39 class Connection;
  40 class StageOneLoginTask;
  41 class StageTwoLoginTask;
  42 class ContactManager;
  43 class UserDetails;
  44 class QString;
  45 class Task;
  46 class QTextCodec;
  47 namespace Kopete
  48 {
  49         class Transfer;
  50         class TransferManager;
  51 }
  52
  53 namespace Oscar
  54 {
  55 class Settings;
  56 }
  57
  58 class LIBOSCAR_EXPORT Client : public QObject
  59 {
  60 Q_OBJECT
  61
  62 public:
  63
  64         class CodecProvider {
  65         public:
  66                 virtual ~CodecProvider() {}
  67                 virtual QTextCodec* codecForContact( const QString& contactName ) const = 0;
  68                 virtual QTextCodec* codecForAccount() const = 0;
  69         };
  70
  71         enum ErrorCodes {
  72                 NoError = 0,
  73                 NotConnectedError = 1,
  74                 NonFatalProtocolError = 2,
  75                 FatalProtocolError = 3
  76         };
  77
  78         enum ICQStatusFlags {
  79                 ICQOnline       = 0x00,
  80                 ICQAway         = 0x01,
  81                 ICQNotAvailable = 0x02,
  82                 ICQOccupied     = 0x03,
  83                 ICQDoNotDisturb = 0x04,
  84                 ICQFreeForChat  = 0x05,
  85
  86                 ICQXStatus      = 0x10,
  87                 ICQPluginStatus = 0x20,
  88
  89                 ICQStatusMask   = 0x0F
  90         };
  91         Q_DECLARE_FLAGS(ICQStatus, ICQStatusFlags)
  92
  93         /*************
  94           EXTERNAL API
  95          *************/
  96
  97         Client(QObject *parent=0);
  98         ~Client();
  99
 100         /**
 101          * Get the settings object for this client instance
 102          */
 103         Oscar::Settings* clientSettings() const;
 104
 105         /**
 106          * Start a connection to the server using the supplied @ref ClientStream.
 107          * This is only a transport layer connection.
 108          * @param s initialised connection object to use for the connection.
 109          * @param host the host name of server to connect to
 110          * @param port the port of server to connect to
 111          * @param auth indicate whether we're connecting to the authorizer or the bos server
 112          */
 113         void connectToServer( Connection *c, const QString& host, quint16 port, bool auth = true );
 114
 115         /**
 116          * Start the login process for Oscar
 117          * @param host Used for outgoing tasks to determine destination
 118          * @param user The user name to log in as.
 119          * @param port The port of server to connect to
 120          * @param pass The password to use when logging in
 121          */
 122         void start( const QString &host, const uint port, const QString &userId, const QString &pass );
 123
 124         /** Logout and disconnect */
 125         void close();
 126
 127         /** Set our status
 128          * \param status the oscar status
 129          * \param message the status message or Xtraz status message
 130          * \param xtraz the Xtraz status
 131          * \param description the Xtraz status description
 132          * @note If you want XStatus you have to set status, message, xtraz and description,
 133          * for ExtStatus (ICQ6 status) you have to set status, message and description, xtraz have to be -1.
 134          * If you want normal status than you should set only status and message.
 135          */
 136         void setStatus( Oscar::DWORD status, const QString &message = QString(), int xtraz = -1, const QString &description = QString() );
 137
 138         /** Retrieve our user info */
 139         UserDetails ourInfo() const;
 140
 141         /**
 142          * Remove a group to the contact list
 143          * \param groupName the name of the group to remove
 144          * \return true if the group removal was successful
 145          */
 146         void removeGroup( const QString& groupName );
 147
 148         /**
 149          * Add a group from the contact list
 150          * \param groupName the name of the group to add
 151          * \return true if the group addition was successful
 152          */
 153         void addGroup( const QString& groupName );
 154
 155         /**
 156          * Add a contact to the contact list
 157          * \param contactName the screen name of the new contact to add
 158          * \return true if the contact addition was successful
 159          */
 160         void addContact( const QString& contactName, const QString& groupName );
 161
 162         /**
 163          * Remove a contact from the contact list
 164          * \param contactName the screen name of the contact to remove
 165          * \return true if the contact removal was successful
 166          */
 167         void removeContact( const QString &contactName );
 168
 169         /**
 170          * Rename a group on the contact list
 171          * \param oldGroupName the old group name
 172          * \param newGroupName the new group name
 173          */
 174         void renameGroup( const QString& oldGroupName, const QString& newGroupName );
 175
 176         /**
 177          * Modify an Contact item on the Contact list
 178          * \param item the item to send to the server
 179          */
 180         void modifyContactItem( const OContact& oldItem, const OContact& newItem );
 181
 182         /**
 183          * Change a contact's group on the server
 184          * \param contact the contact to change
 185          * \param newGroup the new group to move the contact to
 186          */
 187         void changeContactGroup( const QString& contact, const QString& newGroupName );
 188
 189         /**
 190          * Send a message to a contact
 191          * \param msg the message to be sent
 192          * \param auto the message is an autoresponse message, default to false
 193          */
 194         void sendMessage( const Oscar::Message& msg, bool isAuto = false );
 195
 196         /**
 197          * Request authorization from a contact
 198          * \param contactid the id of the contact to request auth from
 199          * \param reason the reason for this authorization request
 200          */
 201         void requestAuth( const QString& contactid, const QString& reason );
 202
 203         /**
 204          * Grant or decline authorization to a contact
 205          * \param contactid the id of the contact to grant/decline authorization
 206          * \param reason the reason to grant/decline authorization
 207          * \param auth grant or decline authorization
 208          */
 209         void sendAuth( const QString& contactid, const QString& reason, bool auth=true );
 210
 211         /**
 212          * Request Short/Medium/Long user info from an ICQ contact (new TLV based format)
 213          * \param contactId the UIN of the contact to get info for
 214          * \param metaInfoId the id of the info (TLV 0x015C in SSI)
 215          */
 216         void requestShortTlvInfo( const QString& contactId, const QByteArray &metaInfoId );
 217         void requestMediumTlvInfo( const QString& contactId, const QByteArray &metaInfoId );
 218         void requestLongTlvInfo( const QString& contactId, const QByteArray &metaInfoId );
 219
 220         /**
 221          * Request full user info from an ICQ contact
 222          * \param contactId the UIN of the contact to get info for
 223          */
 224         void requestFullInfo( const QString& contactId );
 225
 226         /**
 227          * Request short info for an ICQ contact
 228          * \param contactId the UIN of the contact to get info for
 229          */
 230         void requestShortInfo( const QString& contactId );
 231
 232         /**
 233          * Send a warning to the OSCAR servers about a contact
 234          * \param contact the contact to send the warning to
 235          * \param anon indicate whether to do it anonymously
 236          */
 237         void sendWarning( const QString& contact, bool anonymous );
 238
 239         /**
 240          * Change ICQ password
 241          * \param password your new password
 242          */
 243         bool changeICQPassword( const QString& password );
 244
 245         /**
 246          * Get the full ICQ info for a client
 247          * \param contact the contact to get info for
 248          */
 249         ICQFullInfo getFullInfo( const QString& contact );
 250
 251         /**
 252          * Get the general ICQ info for a client
 253          * \param contact the contact to get info for
 254          */
 255         ICQGeneralUserInfo getGeneralInfo( const QString& contact );
 256
 257         /**
 258          * Get the work info for a contact
 259          * \param contact the contact to get info for
 260          */
 261         ICQWorkUserInfo getWorkInfo( const QString& contact );
 262
 263         /**
 264          * Get the email info for a contact
 265          * \param contact the contact to get info for
 266          */
 267         ICQEmailInfo getEmailInfo( const QString& contact );
 268
 269         /**
 270          * Get the notes info for a contact
 271          * \param contact the contact to get info for
 272          */
 273         ICQNotesInfo getNotesInfo( const QString& contact );
 274
 275         /**
 276          * Get the additional info available for a contact
 277          * \param contact the contact to get info for
 278          */
 279         ICQMoreUserInfo getMoreInfo( const QString& contact );
 280
 281         /**
 282          * Get the interest info available for a contact
 283          * \param contact the contact to get info for
 284          */
 285         ICQInterestInfo getInterestInfo( const QString& contact );
 286
 287         /**
 288          * Get the organization and affiliation interest info available for a contact
 289          * \param contact the contact to get info for
 290          */
 291         ICQOrgAffInfo getOrgAffInfo( const QString& contact );
 292
 293         /**
 294          * Get the short info available for an icq contact
 295          * \param contact the contact to get info for
 296          */
 297         ICQShortInfo getShortInfo( const QString& contact );
 298
 299     /**
 300      * Get the list of chat room exchanges we have
 301      */
 302     QList<int> chatExchangeList() const;
 303
 304         /**
 305          * Request the aim profile
 306          * \param contact the contact to get info for
 307          */
 308         void requestAIMProfile( const QString& contact );
 309
 310         /**
 311          * Request the aim away message
 312          * \param contact the contact to get info for
 313          */
 314         void requestAIMAwayMessage( const QString& contact );
 315
 316         /**
 317          * Add the icq away message request to queue
 318          * \param contact the contact to get info for
 319          */
 320         void addICQAwayMessageRequest( const QString& contact, ICQStatus contactStatus );
 321
 322         /**
 323          * Remove the icq away message request from queue
 324          * \param contact the contact to get info for
 325          */
 326         void removeICQAwayMessageRequest( const QString& contact );
 327
 328         /** Request the extended status info */
 329         void requestStatusInfo( const QString& contact );
 330
 331         //! Run a whitepages search
 332         void whitePagesSearch( const ICQWPSearchInfo& info );
 333
 334         //! Run a UIN search
 335         void uinSearch( const QString& uin );
 336
 337         //! Update the user's AIM profile
 338         void updateProfile( const QString& profile );
 339
 340         //! Update the user's ICQ profile
 341         bool updateProfile( const QList<ICQInfoBase*>& infoList );
 342
 343         //! Get buddy icon information for a person
 344         void requestBuddyIcon( const QString& user, const QByteArray& hash, Oscar::BYTE hashType );
 345
 346         //! Start a server redirect for a different service
 347         void requestServerRedirect( Oscar::WORD family, Oscar::WORD e = 0, QByteArray c = QByteArray(),
 348                                 Oscar::WORD instance = 0, const QString& room = QString() );
 349
 350         //! Start uploading a buddy icon
 351         void sendBuddyIcon( const QByteArray& imageData );
 352
 353     void joinChatRoom( const QString& roomName, int exchange );
 354
 355         void setIgnore( const QString& user, bool ignore );
 356
 357         void setVisibleTo( const QString& user, bool visible );
 358
 359         void setInvisibleTo( const QString& user, bool invisible );
 360
 361         /** Accessors needed for login */
 362         QString host();
 363         int port();
 364
 365         /** Send a typing notification */
 366         void sendTyping( const QString & contact, bool typing );
 367
 368         /** Make a connection to the icon server */
 369         void connectToIconServer();
 370
 371         bool hasIconConnection() const;
 372
 373     /** We've finished chatting in a chat room, disconnect from it */
 374     void disconnectChatRoom( Oscar::WORD exchange, const QString& room );
 375
 376         /** Set codec provider */
 377         void setCodecProvider( CodecProvider* codecProvider );
 378
 379         /** Set pointer to version info */
 380         void setVersion( const Oscar::ClientVersion* version );
 381
 382         /** start a filetransfer task */
 383         void sendFiles( const QString& contact, const QStringList& files, Kopete::Transfer *t );
 384
 385         /*************
 386           INTERNAL (FOR USE BY TASKS OR CONNECTIONS) METHODS
 387          *************/
 388         /**
 389          * Print a debug statement
 390          */
 391         void debug( const QString &str );
 392
 393         /** Have we logged in yet? */
 394         bool isActive() const;
 395
 396         /** Accessor for the Contact Manager */
 397         ContactManager* ssiManager() const;
 398
 399         /** Return version info */
 400         const Oscar::ClientVersion* version() const;
 401
 402         /** The current user's user ID */
 403         QString userId() const;
 404
 405         /** The current user's password */
 406         QString password() const;
 407
 408         /** The current Xtraz status */
 409         int statusXtraz() const;
 410
 411         /** The current Xtraz status description */
 412         QString statusDescription() const;
 413
 414         /** The current status message (a.k.a. away message or Xtraz message) */
 415         QString statusMessage() const;
 416
 417         /** Change the current status message w/o changing status */
 418         void setStatusMessage( const QString &message );
 419
 420         /** ICQ Settings */
 421         bool isIcq() const;
 422         void setIsIcq( bool isIcq );
 423
 424         /** Host's IP address */
 425         QByteArray ipAddress() const;
 426
 427         /** Notify that a task error was received */
 428         void notifyTaskError( const Oscar::SNAC& s, int errCode, bool fatal );
 429
 430         /** Notify that a socket error has occurred */
 431         void notifySocketError( int errCode, const QString& msg );
 432
 433 signals:
 434         /** CONNECTION EVENTS */
 435
 436         /** Notifies that the login process has succeeded. */
 437         void loggedIn();
 438
 439         /** Notifies that the login process has failed */
 440         void loginFailed();
 441
 442         /** Notifies tasks and account so they can react properly */
 443         void disconnected();
 444
 445         /** We were disconnected because we connected elsewhere */
 446         void connectedElsewhere();
 447
 448         /** We have our own user info */
 449         void haveOwnInfo();
 450
 451         /** We have our Contact list */
 452         void haveContactList();
 453
 454         /** a user is online. */
 455         void userIsOnline( const QString& );
 456
 457         /** a user is offline. */
 458         void userIsOffline( const QString& );
 459
 460         /** we've received a message */
 461         void messageReceived( const Oscar::Message& );
 462
 463         /** we've received an authorization request */
 464         void authRequestReceived( const QString& contact, const QString& reason );
 465
 466         /** we've received an authorization reply */
 467         void authReplyReceived( const QString& contact, const QString& reason, bool auth );
 468
 469         /** we've received a ICQ password change reply */
 470         void icqPasswordChanged( bool error );
 471
 472         /**
 473          * we've received an error from a task and need to notify somebody
 474          */
 475         void taskError( const Oscar::SNAC& s, int errCode, bool fatal );
 476
 477         /**
 478          * we've received a socket error and need to notify somebody
 479          */
 480         void socketError( int errCode, const QString& msg );
 481
 482         void receivedIcqShortInfo( const QString& contact );
 483         void receivedIcqLongInfo( const QString& contact );
 484         void receivedIcqTlvInfo( const QString& contact );
 485
 486         void receivedProfile( const QString& contact, const QString& profile );
 487         void receivedAwayMessage( const QString& contact, const QString& message );
 488         void receivedXStatusMessage( const QString& contact, int icon, const QString& description, const QString& message );
 489         void receivedUserInfo( const QString& contact, const UserDetails& details );
 490         void userReadsStatusMessage( const QString& contact );
 491
 492         /** We warned a user */
 493         void userWarned( const QString& contact, quint16 increase, quint16 newLevel );
 494
 495         /** Search signals */
 496         void gotSearchResults( const ICQSearchResult& );
 497         void endOfSearch( int);
 498
 499         /* Typing signals */
 500         void userStartedTyping( const QString& contact );
 501         void userStoppedTyping( const QString& contact );
 502
 503         /* Buddy icons */
 504         void haveIconForContact( const QString&, QByteArray iconData );
 505         void iconServerConnected();
 506         void iconNeedsUploading();
 507
 508         /* Chat rooms */
 509         void chatNavigationConnected();
 510     void chatRoomConnected( Oscar::WORD, const QString& );
 511     void userJoinedChat( Oscar::WORD, const QString& room, const QString& contact );
 512     void userLeftChat( Oscar::WORD, const QString& room, const QString& contact );
 513
 514         /* service redirection */
 515         void redirectionFinished( Oscar::WORD );
 516
 517         /** incoming filetransfer */
 518         void askIncoming( QString c, QString f, Oscar::DWORD s, QString d, QString i );
 519
 520         void getTransferManager( Kopete::TransferManager ** );
 521
 522 protected slots:
 523         // INTERNAL, FOR USE BY TASKS' finished() SIGNALS //
 524
 525         /** Singleshot timer to start stage two login */
 526         void startStageTwo();
 527
 528         /**
 529          * A login task finished. For stage one, this means we've either errored
 530          * out, or gotten a cookie. For stage two, this means we've either done
 531          * something wrong, or we're successfully connected
 532          */
 533         void lt_loginFinished();
 534
 535         /** Stream connected for stage two login */
 536         void streamConnected();
 537
 538         /** We have our own user info */
 539         void haveOwnUserInfo();
 540
 541         /** Service setup finished */
 542         void serviceSetupFinished();
 543
 544         /** we have icq info for a contact */
 545         void receivedIcqInfo( const QString& contact, unsigned int type );
 546
 547         /** we have normal user info for a contact */
 548         void receivedInfo( quint16 sequence );
 549
 550         /** received a message of some kind */
 551         void receivedMessage( const Oscar::Message& msg );
 552
 553         /** filetransfer message needs sending */
 554         void fileMessage( const Oscar::Message& msg );
 555
 556         /** rendezvous message for a filetransfer task */
 557         void gotFileMessage( int, const QString, const QByteArray, Buffer );
 558
 559         void offlineUser( const QString&, const UserDetails& );
 560
 561         void haveServerForRedirect( const QString& host, const QByteArray& cookie, Oscar::WORD family );
 562         void serverRedirectFinished();
 563         void checkRedirectionQueue( Oscar::WORD );
 564
 565         void requestChatNavLimits();
 566     /**
 567      * Set the list of chat room exchanges we have
 568      */
 569     void setChatExchangeList( const QList<int>& exchanges );
 570
 571     /**
 572      * set up the connection to a chat room
 573      */
 574     void setupChatConnection( Oscar::WORD, QByteArray, Oscar::WORD, const QString& );
 575
 576     void determineDisconnection( int, const QString& );
 577
 578         void nextICQAwayMessageRequest();
 579
 580         /** Change ICQ password finished */
 581         void changeICQPasswordFinished();
 582
 583 private:
 584
 585         /** Initialize some static tasks */
 586         void initializeStaticTasks();
 587
 588         /** Delete the static tasks */
 589         void deleteStaticTasks();
 590
 591         Connection* createConnection();
 592
 593         /**
 594          * Request the icq away message
 595          * \param contact the contact to get info for
 596          */
 597         //TODO only made a default for testing w/o frontend
 598         void requestICQAwayMessage( const QString& contact, ICQStatus contactStatus = ICQAway );
 599
 600 private:
 601         class ClientPrivate;
 602         ClientPrivate* d;
 603
 604         StageOneLoginTask* m_loginTask;
 605         StageTwoLoginTask* m_loginTaskTwo;
 606 };
 607 Q_DECLARE_OPERATORS_FOR_FLAGS(Client::ICQStatus)
 608
 609 #endif
 610
 611 //kate: tab-width 4; indent-mode csands;
 612
 613