kopete/protocols/bonjour/bonjourcontactconnection.h

   1 /*
   2     bonjourcontactconnection.h - Kopete Bonjour Protocol
   3
   4     Copyright (c) 2007      by Tejas Dinkar     <tejas@gja.in>
   5     Kopete    (c) 2002-2003 by the Kopete developers <kopete-devel@kde.org>
   6
   7     *************************************************************************
   8     *                                                                       *
   9     * This library is free software; you can redistribute it and/or         *
  10     * modify it under the terms of the GNU General Public                   *
  11     * License as published by the Free Software Foundation; either          *
  12     * version 2 of the License, or (at your option) any later version.      *
  13     *                                                                       *
  14     *************************************************************************
  15 */
  16
  17 #ifndef BONJOURCONTACTCONNECTION_H
  18 #define BONJOURCONTACTCONNECTION_H
  19
  20 #include <QTcpSocket>
  21 #include <QString>
  22 #include <QHostAddress>
  23 #include <QByteArray>
  24 #include <QXmlStreamReader>
  25
  26 #include <kopetemessage.h>
  27
  28 /**
  29  * @brief This Represents a connection to a contact
  30  *
  31  * The BonjourContactConnection contains a @ref socket which has a connection to some contact.
  32  * Data from the @ref socket is parsed by the QXmlStreamReader @ref parser.
  33  * We Get @ref BonjourXmlToken tokens one at a time using the @ref getNextToken() functions
  34  * All Jabber specific code must be here ONLY
  35  *
  36  * There is a protocol document that nobody follows. This can be found here:
  37  * http://www.xmpp.org/extensions/attic/jep-0174-0.5.html
  38  * The standard is totally sucky, and I'm not surprised that there isn't a single client who
  39  * follows it faithfully (that I know of). The standard `we` follow was derived from wireshark
  40  * logs with a machine running Pidgen.
  41  *
  42  * Pass Two Strings for an outgoing connection (second constructor)
  43  *
  44  * @author Tejas Dinkar <tejas\@gja.in>
  45  */
  46 class BonjourContactConnection : public QObject {
  47
  48         Q_OBJECT
  49
  50         /**
  51          * @brief The State of the Connection
  52          *
  53          * @ref connectionState holds this state
  54          */
  55         enum BonjourConnectionState {
  56                 BonjourConnectionNewOutgoing,           // New Outgoing Stream
  57                 BonjourConnectionNewIncoming,           // New Incoming Stream
  58
  59                 BonjourConnectionOutgoingStream,        // Expect a <stream>
  60                 BonjourConnectionToWho,                 // We are Unsure who we connect to
  61
  62                 BonjourConnectionConnected = 50,        // Connected
  63                 BonjourConnectionDisconnected,          // Disconnected
  64
  65                 BonjourConnectionError = 99             // Reserved for Future Use
  66         } connectionState;
  67
  68         // The Actual Connection
  69         QTcpSocket *socket;
  70
  71         // The XML Parser
  72         QXmlStreamReader parser;
  73
  74         // The local and remote names
  75         QString local;
  76
  77         // The local and remote names
  78         QString remote;
  79
  80         // Set the Socket
  81         void setSocket(QTcpSocket *socket);
  82
  83         /**
  84          * @brief Description of A Token
  85          *
  86          * Internally used structures to describe a token as obtained by the parser
  87          * Not all of these names represent valid token names. Some are just provided as a convenient
  88          * way to call @ref getNextToken()
  89         */
  90         enum BonjourXmlTokenName {
  91                 BonjourXmlTokenOther,
  92                 BonjourXmlTokenNone,
  93                 BonjourXmlTokenStream,
  94                 BonjourXmlTokenMessage,
  95                 BonjourXmlTokenBody,
  96                 BonjourXmlTokenHtml,
  97                 BonjourXmlTokenX,
  98                 BonjourXmlTokenIq,
  99                 BonjourXmlTokenQuery,
 100
 101                 BonjourXmlStartElement = 50,            // Simply A Convenient Parameter to getNextToken
 102                 BonjourXmlEndElement,                   // No Token is ever of this type
 103                 BonjourXmlStartOrEndElement,            // Instead see the value of 'type' (QXmlStreamReader::TokenType)
 104
 105                 BonjourXmlTokenError = 99
 106         };
 107
 108         /*
 109          * @brief table to translate between xml tokens and corresponding @BonjourXmlTokenName
 110          *
 111          * This is a Hash Object to Translate a qualified name into a BonjourXmlTokenName quickly
 112          * Only one instance is needed. We derive from QHash and fill it in the constructor
 113          */
 114         static class TokenTable : public QHash <QString, BonjourXmlTokenName>{
 115             public:
 116                 TokenTable();
 117         } tokenTable;
 118
 119         /**
 120          * @brief This Describes a Token
 121          *
 122          * This Describes a Token. It contains a number of useful attributes like type, name, etc..
 123          */
 124         struct BonjourXmlToken {
 125                 QXmlStreamReader::TokenType type;
 126                 BonjourXmlTokenName name;
 127                 QStringRef qualifiedName;
 128                 QXmlStreamAttributes attributes;
 129                 QStringRef text;
 130         };
 131
 132         /**
 133          * @brief Get the Next Token Read in Stream
 134          *
 135          * This Next Function Gets the Next Token in the stream
 136          * This may be of any time. We recommend you pass it a parameter of what type(s)
 137          * of tokens that you expect
 138          *
 139          * @return the token. If error, token.name will be BonjourXmlTokenError
 140          */
 141         const BonjourXmlToken getNextToken();
 142
 143         /**
 144          * @brief Get Next Token Of a Certain Type
 145          *
 146          * This Function returns the next token whose name matches. All tokens before this
 147          * is found are simply thrown away.
 148          * You May Also Search for Next Start Element or End Element (see @ref BonjourXmlTokenName)
 149          *
 150          * @param name The Name of the Next Token We want
 151          * @return the token. If error, token.name will be BonjourXmlTokenError
 152          */
 153         const BonjourXmlToken getNextToken(BonjourXmlTokenName name);
 154
 155         /**
 156          * @brief This is called if we receive an iq packet
 157          *
 158          * iq is only sent by clients like miranda... Who don't care about the reply anyway.
 159          * Later, we may implement support for iq packets. For now we ignore them.
 160          *
 161          * @todo FIXME: Currently we ignore everything between <iq> and </iq>
 162          * @param token The Token Containing the iq. Will be erased
 163          */
 164         void ignoreAllIq(BonjourXmlToken &token);
 165
 166
 167     public:
 168
 169         /**
 170          * @brief Constructor For Incoming Connections
 171          *
 172          * @param aSocket The Socket To Wrap Up
 173          */
 174         explicit BonjourContactConnection(QTcpSocket *aSocket, QObject *parent = NULL);
 175
 176         /**
 177          * @brief Constructor For Outgoing Connection
 178          *
 179          * This is For OutGoing Connections
 180          * We Create a Socket Here, so this may take upto 3 seconds
 181          *
 182          * @param address The Address of the Remote Contact
 183          * @param port The Port the contact is listening on
 184          * @param remote The remoteuser@hostname
 185          * @param local myself@hostname
 186          */
 187         BonjourContactConnection(const QHostAddress &address, short int port, const QString &alocal, const QString &aremote, QObject *parent = NULL);
 188
 189         // Destructor
 190         ~BonjourContactConnection();
 191
 192         /**
 193          * @brief Write <stream:stream> in socket
 194          *
 195          * If the values of remote and local are set, we encode it in the stream as well
 196          */
 197         void sayStream();
 198
 199         /**
 200          * @brief Examine the Next Token, and perform action
 201          *
 202          * This Examines the Data From The Socket and emits a messageReceived (maybe)
 203          * The Parameter is the most recent token.
 204          *
 205          * @param token The Most Recent Token. The value of this token is probably destroyed
 206          */
 207         void readData(BonjourXmlToken &token);
 208
 209         /**
 210          * @brief Called when we expect a stream token
 211          *
 212          * This is Called When a <stream> is expected
 213          * The token should contain <stream>. If it doesn't, then we keep getting new tokens until
 214          * we either get a <stream> or we get an EOF
 215          *
 216          * This emits either a @ref discoveredUserName() or @ref usernameNotInStream()
 217          *
 218          * @param token The token which probably contains the <stream>
 219          */
 220         void getStreamTag(BonjourXmlToken &token);
 221
 222         /**
 223          * @brief Called When we are connected, but don't know to who
 224          *
 225          * This is called when we are waiting for the remote and local values (incoming connections only).
 226          * Honestly, this function is never used, as either signal emitted by @ref getSteam() may be used
 227          * to uniquely identify a contact
 228          *
 229          * @todo FIXME: Currently unimplemented as (at least gaim) says who it is in the <stream>
 230          */
 231         void getWho(BonjourXmlToken &token);
 232
 233         /**
 234          * @brief Gets the Address of the Current Connection
 235          *
 236          * @return The HostAddress of the Remote Contact
 237          */
 238         QHostAddress getHostAddress();
 239
 240         /**
 241          * @brief Create a new Message
 242          *
 243          * This Creates a Message
 244          *
 245          * @param direction The Direction of the Message
 246          * @return The Message
 247          */
 248         Kopete::Message newMessage(Kopete::Message::MessageDirection direction);
 249
 250         /**
 251          * @brief Get a message from stream of tokens
 252          *
 253          * This reads all tokens upto (and including) a </message>, and attempts to assemble
 254          * a message out of the tokens. This emits a @ref messageReceived() signal if a message
 255          * can be read.
 256          *
 257          * @todo FIXME: HTML messages are ignored
 258          *
 259          * @param token A Token which contains a <message>. It's value will be destroyed
 260          */
 261         void readMessage(BonjourXmlToken &token);
 262
 263         /**
 264          * @brief Check if a Connection is ready for general data transfer
 265          * @return @c true if it is connected, @c false otherwise
 266          */
 267         inline bool isConnected()
 268         {
 269                 return connectionState == BonjourConnectionConnected;
 270         }
 271
 272         /**
 273          * @brief Send a </stream>
 274          */
 275         void sayGoodBye();
 276
 277         /**
 278          * @brief Set @ref remote and @ref local strings externally
 279          *
 280          * This function is usually called if the contact is identified via an
 281          * IP lookup, and not via the stream element.
 282          *
 283          * @param remote The Remote User
 284          * @param local The Local User
 285          */
 286         void setRemoteAndLocal(const QString &remote, const QString &local);
 287
 288     signals:
 289
 290         /**
 291          * @brief This Signal is Emitted when there is new data
 292          *
 293          * @todo FIXME: This is unused. Remove it
 294          */
 295         void newData(BonjourContactConnection *);
 296
 297         /**
 298          * @brief Signal Emitted when we discover who the remote user is
 299          *
 300          * This signal is emitted when we discover who we are connected to (unverified)
 301          * Used in Incoming Connections Only
 302          *
 303          * The Username is sent back
 304          */
 305         void discoveredUserName(BonjourContactConnection *, const QString &);
 306
 307         /**
 308          * @brief Send if the stream tag didn't contain a from and to
 309          *
 310          * This signal is sent if we can't figure out who it is
 311          */
 312         void usernameNotInStream(BonjourContactConnection *);
 313
 314         /**
 315          * @brief This signal is sent if the @ref socket is disconnected
 316          *
 317          * This Signal is basically forwarding disconnect signal from socket
 318          */
 319         void disconnected(BonjourContactConnection *);
 320
 321         /**
 322          * @brief Signal Emitted when a new message has been received (already formatted)
 323          */
 324         void messageReceived(Kopete::Message);
 325
 326         /**
 327          * @brief Signal Emitted if we could not connect to an external socket
 328          */
 329         void errorCouldNotConnect();
 330
 331     public slots:
 332
 333         /**
 334          * @brief This slot is called by the socket, to signify new data
 335          */
 336         void dataInSocket();
 337
 338         /**
 339          * @brief This is Called when the socket disconnects
 340          *
 341          * This basically emits @ref disconnected()
 342          */
 343         void socketDisconnected();
 344
 345         /**
 346          * @brief Send a message
 347          */
 348         void sendMessage(const Kopete::Message &message);
 349 };
 350
 351 #endif