kopete/protocols/groupwise/libgroupwise/eventprotocol.h

   1 /*
   2     Kopete Groupwise Protocol
   3     eventprotocol.h - reads the protocol used by GroupWise for signalling Events
   4
   5     Copyright (c) 2004      SUSE Linux AG                http://www.suse.com
   6
   7     Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
   8
   9     *************************************************************************
  10     *                                                                       *
  11     * This library is free software; you can redistribute it and/or         *
  12     * modify it under the terms of the GNU Lesser General Public            *
  13     * License as published by the Free Software Foundation; either          *
  14     * version 2 of the License, or (at your option) any later version.      *
  15     *                                                                       *
  16     *************************************************************************
  17 */
  18
  19 #ifndef GW_EVENTPROTOCOL_H
  20 #define GW_EVENTPROTOCOL_H
  21
  22 #include "inputprotocolbase.h"
  23
  24 class EventTransfer;
  25 /**
  26  * This class converts incoming event data into EventTransfer objects.  Since it requires knowledge of the binary event format, which
  27  * differs for each event type, it is implemented as a separate class. See also @ref CoreProtocol, which detects event messages in the
  28  * data stream and hands them to this class for processing.
  29  * Event Types
  30  *
  31 @author SUSE AG
  32         Ablauf:
  33         CoreProtocol receives data in addIncomingData, and passes to wireToTransfer.
  34         wireToTransfer detects an event.
  35                 Passes whole chunk to EventProtocol ( as QByteArray )
  36                 In to EventProtocol - QByteArray
  37                 Returned from EventProtocol - EventTransfer *, bytes read, set state?
  38         EventProtocol tries to parse data into eventTransfer
  39         If not complete, sets state to NeedMore and returns 0
  40         If complete, returns number of bytes read for the event
  41         If bytes less than length of chunk, CoreProtocol::addIncomingData places the unread bytes back in m_in and calls wireToTransfer again.
  42         if ResponseProtocol or EventProtocol set state to NeedMore, don't call wireToTransfer again.
  43
  44         What event dependent data does EventTransfer contain?
  45
  46         What if some events contain EXTRA bytes off the end that we don't know about?  Then we will put those bytes back on the buffer, and try and parse those as the start of a new message!!!  Need to react SAFELY then.
  47
  48         What event dependent binary data does each event type contain?
  49
  50         All Events contain an event code, and a source ( a DN )
  51         NOTHANDLED indicates that there is no further data and we don't handle events of that type, because they are not sent by the server
  52         NONE indicates there is no further data
  53         STATUSTEXT, GUID, MESSAGE indicate a string encoded in the usual GroupWise binary string encoding: a UINT32 containing the string length in little-endian, followed by the string itself, as UTF-8 encoded unicode.  The string length value includes a terminating NUL, so when converting to a QString, subtract one from the string length.
  54         FLAGS contains a UINT32 containing the server's flags for this conference.  See gwerror.h for the possible values and meanings of these flags.  Only Logging has been observed in practice.
  55
  56         All events are timestamped with the local time on receipt.
  57
  58         From gwerror.h:
  59         enum Event {            InvalidRecipient                = 101,
  60                                                         NOTHANDLED
  61                                                 UndeliverableStatus     = 102,
  62                                                         NOTHANDLED *
  63                                                 StatusChange                    = 103,
  64                                                         quint16 STATUS
  65                                                         STATUSTEXT
  66                                                 ContactAdd                              = 104,
  67                                                         NOTHANDLED
  68                                                 ConferenceClosed                = 105,
  69                                                         GUID
  70                                                 ConferenceJoined                = 106,
  71                                                         GUID
  72                                                         FLAGS
  73                                                 ConferenceLeft                  = 107,
  74                                                         GUID
  75                                                         FLAGS
  76                                                 ReceiveMessage                  = 108,
  77                                                         GUID
  78                                                         FLAGS
  79                                                         MESSAGE
  80                                                 ReceiveFile                             = 109,
  81                                                         NOTHANDLED
  82                                                 UserTyping                              = 112,
  83                                                         GUID
  84                                                 UserNotTyping                   = 113,
  85                                                         GUID
  86                                                 UserDisconnect                  = 114,
  87                                                         NONE
  88                                                 ServerDisconnect                = 115,
  89                                                         NONE
  90                                                 ConferenceRename                = 116,
  91                                                         NOTHANDLED
  92                                                 ConferenceInvite                = 117,
  93                                                         GUID
  94                                                         MESSAGE
  95                                                 ConferenceInviteNotify  = 118,
  96                                                         GUID
  97                                                 ConferenceReject                = 119,
  98                                                         GUID
  99                                                 ReceiveAutoReply                = 121,
 100                                                         GUID
 101                                                         FLAGS
 102                                                         MESSAGE
 103                                                 Start                                   = InvalidRecipient,
 104                                                 Stop                                    = ReceiveAutoReply
 105                                 };
 106         Therefore we have GUID, FLAGS, MESSAGE, STATUS, STATUSTEXT.  All transfers have TYPE and SOURCE, and a TIMESTAMP is added on receipt.
 107 */
 108
 109 class EventProtocol : public InputProtocolBase
 110 {
 111 Q_OBJECT
 112 public:
 113     EventProtocol(QObject *parent = 0);
 114     ~EventProtocol();
 115         /**
 116          * Attempt to parse the supplied data into an @ref EventTransfer object.
 117          * The exact state of the parse attempt can be read using @ref state.
 118          * @param rawData The unparsed data.
 119          * @param bytes An integer used to return the number of bytes read.
 120          * @return A pointer to an EventTransfer object if successful, otherwise 0.  The caller is responsible for deleting this object.
 121          */
 122         Transfer * parse( QByteArray &, uint & bytes );
 123 protected:
 124         /**
 125          * Reads a conference's flags
 126          */
 127         bool readFlags( quint32 &flags);
 128 };
 129
 130 #endif