include/ptclib/xmpp.h

   1 /*
   2  * xmpp.h
   3  *
   4  * Extensible Messaging and Presence Protocol (XMPP) Core
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 2004 Reitek S.p.A.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Post Increment
  23  *
  24  * Contributor(s): ______________________________________.
  25  *
  26  * $Log$
  27  * Revision 1.6  2007/04/10 05:08:46  rjongbloed
  28  * Fixed issue with use of static C string variables in DLL environment,
  29  *   must use functional interface for correct initialisation.
  30  *
  31  * Revision 1.5  2005/11/30 12:47:37  csoutheren
  32  * Removed tabs, reformatted some code, and changed tags for Doxygen
  33  *
  34  * Revision 1.4  2004/11/11 07:34:50  csoutheren
  35  * Added #include <ptlib.h>
  36  *
  37  * Revision 1.3  2004/05/09 07:23:46  rjongbloed
  38  * More work on XMPP, thanks Federico Pinna and Reitek S.p.A.
  39  *
  40  * Revision 1.2  2004/04/26 01:51:57  rjongbloed
  41  * More implementation of XMPP, thanks a lot to Federico Pinna & Reitek S.p.A.
  42  *
  43  * Revision 1.1  2004/04/22 12:31:00  rjongbloed
  44  * Added PNotifier extensions and XMPP (Jabber) support,
  45  *   thanks to Federico Pinna and Reitek S.p.A.
  46  *
  47  *
  48  */
  49
  50 #ifndef _XMPP
  51 #define _XMPP
  52
  53 #ifdef P_USE_PRAGMA
  54 #pragma interface
  55 #endif
  56
  57 #include <ptlib.h>
  58
  59 #if P_EXPAT
  60
  61 #include <ptclib/pxml.h>
  62 #include <ptlib/notifier_ext.h>
  63
  64
  65 ///////////////////////////////////////////////////////
  66
  67 namespace XMPP
  68 {
  69   /** Various constant strings
  70    */
  71   extern const PString & LanguageTag();
  72   extern const PString & NamespaceTag();
  73   extern const PString & MessageStanzaTag();
  74   extern const PString & PresenceStanzaTag();
  75   extern const PString & IQStanzaTag();
  76   extern const PString & IQQueryTag();
  77
  78   class JID : public PObject
  79   {
  80     PCLASSINFO(JID, PObject);
  81
  82   public:
  83     JID(const char * jid = 0);
  84     JID(const PString& jid);
  85     JID(const PString& user, const PString& server, const PString& resource = PString::Empty());
  86
  87     virtual Comparison Compare(
  88       const PObject & obj   ///< Object to compare against.
  89       ) const;
  90
  91     JID& operator=(
  92       const PString & jid  ///< New JID to assign.
  93       );
  94
  95     operator const PString&() const;
  96
  97     virtual PObject * Clone() const { return new JID(m_JID); }
  98
  99     PString   GetUser() const         { return m_User; }
 100     PString   GetServer() const       { return m_Server; }
 101
 102     virtual PString GetResource() const { return m_Resource; }
 103
 104     virtual void SetUser(const PString& user);
 105     virtual void SetServer(const PString& server);
 106     virtual void SetResource(const PString& resource);
 107
 108     virtual BOOL IsBare() const       { return m_Resource.IsEmpty(); }
 109     virtual void PrintOn(ostream & strm) const;
 110
 111   protected:
 112     virtual void ParseJID(const PString& jid);
 113     virtual void BuildJID() const;
 114
 115     PString   m_User;
 116     PString   m_Server;
 117     PString   m_Resource;
 118
 119     mutable PString m_JID;
 120     mutable BOOL    m_IsDirty;
 121   };
 122
 123   // A bare jid is a jid with no resource
 124   class BareJID : public JID
 125   {
 126     PCLASSINFO(BareJID, JID);
 127
 128   public:
 129     BareJID(const char * jid = 0) : JID(jid) { }
 130     BareJID(const PString& jid) : JID(jid) { }
 131     BareJID(const PString& user, const PString& server, const PString& resource = PString::Empty())
 132       : JID(user, server, resource) { }
 133
 134     virtual Comparison Compare(
 135       const PObject & obj   ///< Object to compare against.
 136       ) const;
 137
 138     BareJID& operator=(
 139       const PString & jid  ///< New JID to assign.
 140       );
 141
 142     virtual PObject * Clone() const { return new BareJID(m_JID); }
 143     virtual PString GetResource() const { return PString::Empty(); }
 144     virtual void SetResource(const PString&) { }
 145     virtual BOOL IsBare() const { return TRUE; }
 146   };
 147
 148   /** This interface is the base class of each XMPP transport class
 149
 150   Derived classes might include an XMPP TCP transport as well as
 151   classes to handle XMPP incapsulated in SIP messages.
 152   */
 153   class Transport : public PIndirectChannel
 154   {
 155     PCLASSINFO(Transport, PIndirectChannel);
 156
 157   public:
 158     virtual BOOL Open() = 0;
 159     virtual BOOL Close() = 0;
 160   };
 161
 162
 163 /** This class represents a XMPP stream, i.e. a XML message exchange
 164     between XMPP entities
 165  */
 166   class Stream : public PIndirectChannel
 167   {
 168     PCLASSINFO(Stream, PIndirectChannel);
 169
 170   public:
 171     Stream(Transport * transport = 0);
 172     ~Stream();
 173
 174     virtual BOOL        OnOpen()            { return m_OpenHandlers.Fire(*this); }
 175     PNotifierList&      OpenHandlers()      { return m_OpenHandlers; }
 176
 177     virtual BOOL        Close();
 178     virtual void        OnClose()           { m_CloseHandlers.Fire(*this); }
 179     PNotifierList&      CloseHandlers()     { return m_CloseHandlers; }
 180
 181     virtual BOOL        Write(const void * buf, PINDEX len);
 182     virtual BOOL        Write(const PString& data);
 183     virtual BOOL        Write(const PXML& pdu);
 184
 185     /** Read a XMPP stanza from the stream
 186     */
 187     virtual PXML *      Read();
 188
 189     /** Reset the parser. The will delete and re-instantiate the
 190     XML stream parser.
 191     */
 192     virtual void        Reset();
 193     PXMLStreamParser *  GetParser()     { return m_Parser; }
 194
 195   protected:
 196     PXMLStreamParser *  m_Parser;
 197     PNotifierList       m_OpenHandlers;
 198     PNotifierList       m_CloseHandlers;
 199   };
 200
 201
 202   class BaseStreamHandler : public PThread
 203   {
 204     PCLASSINFO(BaseStreamHandler, PThread);
 205
 206   public:
 207     BaseStreamHandler();
 208     ~BaseStreamHandler();
 209
 210     virtual BOOL        Start(Transport * transport = 0);
 211     virtual BOOL        Stop(const PString& error = PString::Empty());
 212
 213     void                SetAutoReconnect(BOOL b = TRUE, long timeout = 1000);
 214
 215     PNotifierList&      ElementHandlers()   { return m_ElementHandlers; }
 216     Stream *            GetStream()         { return m_Stream; }
 217
 218     virtual BOOL        Write(const void * buf, PINDEX len);
 219     virtual BOOL        Write(const PString& data);
 220     virtual BOOL        Write(const PXML& pdu);
 221     virtual void        OnElement(PXML& pdu);
 222
 223     virtual void        Main();
 224
 225   protected:
 226     PDECLARE_NOTIFIER(Stream, BaseStreamHandler, OnOpen);
 227     PDECLARE_NOTIFIER(Stream, BaseStreamHandler, OnClose);
 228
 229     Stream *        m_Stream;
 230     BOOL            m_AutoReconnect;
 231     PTimeInterval   m_ReconnectTimeout;
 232
 233     PNotifierList   m_ElementHandlers;
 234   };
 235
 236
 237   /** XMPP stanzas: the following classes represent the three
 238     stanzas (PDUs) defined by the xmpp protocol
 239    */
 240
 241   class Stanza : public PXML
 242   {
 243     PCLASSINFO(Stanza, PXML)
 244
 245   public:
 246     /** Various constant strings
 247     */
 248     static const PString & IDTag();
 249     static const PString & FromTag();
 250     static const PString & ToTag();
 251
 252     virtual BOOL IsValid() const = 0;
 253
 254     virtual PString GetID() const;
 255     virtual PString GetFrom() const;
 256     virtual PString GetTo() const;
 257
 258     virtual void SetID(const PString& id);
 259     virtual void SetFrom(const PString& from);
 260     virtual void SetTo(const PString& to);
 261
 262     virtual PXMLElement * GetElement(const PString& name, PINDEX i = 0);
 263     virtual void AddElement(PXMLElement * elem);
 264
 265     static PString GenerateID();
 266   };
 267
 268   PLIST(StanzaList, Stanza);
 269
 270
 271   class Message : public Stanza
 272   {
 273     PCLASSINFO(Message, Stanza)
 274
 275   public:
 276     enum MessageType {
 277       Normal,
 278       Chat,
 279       Error,
 280       GroupChat,
 281       HeadLine,
 282       Unknown = 999
 283     };
 284
 285     /** Various constant strings
 286     */
 287     static const PString & TypeTag();
 288     static const PString & SubjectTag();
 289     static const PString & BodyTag();
 290     static const PString & ThreadTag();
 291
 292     /** Construct a new empty message
 293     */
 294     Message();
 295
 296     /** Construct a message from a (received) xml PDU.
 297     The root of the pdu MUST be a message stanza.
 298     NOTE: the root of the pdu is cloned.
 299     */
 300     Message(PXML& pdu);
 301     Message(PXML * pdu);
 302
 303     virtual BOOL IsValid() const;
 304     static BOOL IsValid(const PXML * pdu);
 305
 306     virtual MessageType GetType(PString * typeName = 0) const;
 307     virtual PString     GetLanguage() const;
 308
 309     /** Get the subject for the specified language. The default subject (if any)
 310     is returned in case no language is specified or a matching one cannot be
 311     found
 312     */
 313     virtual PString GetSubject(const PString& lang = PString::Empty());
 314     virtual PString GetBody(const PString& lang = PString::Empty());
 315     virtual PString GetThread();
 316
 317     virtual PXMLElement * GetSubjectElement(const PString& lang = PString::Empty());
 318     virtual PXMLElement * GetBodyElement(const PString& lang = PString::Empty());
 319
 320     virtual void SetType(MessageType type);
 321     virtual void SetType(const PString& type); // custom, possibly non standard, type
 322     virtual void SetLanguage(const PString& lang);
 323
 324     virtual void SetSubject(const PString& subj, const PString& lang = PString::Empty());
 325     virtual void SetBody(const PString& body, const PString& lang = PString::Empty());
 326     virtual void SetThread(const PString& thrd);
 327   };
 328
 329
 330   class Presence : public Stanza
 331   {
 332     PCLASSINFO(Presence, Stanza)
 333
 334   public:
 335     enum PresenceType {
 336       Available,
 337       Unavailable,
 338       Subscribe,
 339       Subscribed,
 340       Unsubscribe,
 341       Unsubscribed,
 342       Probe,
 343       Error,
 344       Unknown = 999
 345     };
 346
 347     enum ShowType {
 348       Online,
 349       Away,
 350       Chat,
 351       DND,
 352       XA,
 353       Other = 999
 354     };
 355
 356     /** Various constant strings
 357     */
 358     static const PString & TypeTag();
 359     static const PString & ShowTag();
 360     static const PString & StatusTag();
 361     static const PString & PriorityTag();
 362
 363     /** Construct a new empty presence
 364     */
 365     Presence();
 366
 367     /** Construct a presence from a (received) xml PDU.
 368     The root of the pdu MUST be a presence stanza.
 369     NOTE: the root of the pdu is cloned.
 370     */
 371     Presence(PXML& pdu);
 372     Presence(PXML * pdu);
 373
 374     virtual BOOL IsValid() const;
 375     static BOOL IsValid(const PXML * pdu);
 376
 377     virtual PresenceType GetType(PString * typeName = 0) const;
 378     virtual ShowType     GetShow(PString * showName = 0) const;
 379     virtual BYTE         GetPriority() const;
 380
 381     /** Get the status for the specified language. The default status (if any)
 382     is returned in case no language is specified or a matching one cannot be
 383     found
 384     */
 385     virtual PString GetStatus(const PString& lang = PString::Empty());
 386     virtual PXMLElement * GetStatusElement(const PString& lang = PString::Empty());
 387
 388     virtual void SetType(PresenceType type);
 389     virtual void SetType(const PString& type); // custom, possibly non standard, type
 390     virtual void SetShow(ShowType show);
 391     virtual void SetShow(const PString& show); // custom, possibly non standard, type
 392     virtual void SetPriority(BYTE priority);
 393
 394     virtual void SetStatus(const PString& status, const PString& lang = PString::Empty());
 395   };
 396
 397
 398   class IQ : public Stanza
 399   {
 400     PCLASSINFO(IQ, Stanza)
 401
 402   public:
 403     enum IQType {
 404       Get,
 405       Set,
 406       Result,
 407       Error,
 408       Unknown = 999
 409     };
 410
 411     /** Various constant strings
 412     */
 413     static const PString & TypeTag();
 414
 415     IQ(IQType type, PXMLElement * body = 0);
 416     IQ(PXML& pdu);
 417     IQ(PXML * pdu);
 418     ~IQ();
 419
 420     virtual BOOL IsValid() const;
 421     static BOOL IsValid(const PXML * pdu);
 422
 423     /** This method signals that the message was taken care of
 424     If the stream handler, after firing all the notifiers finds
 425     that an iq set/get pdu has not being processed, it returns
 426     an error to the sender
 427     */
 428     void SetProcessed()             { m_Processed = TRUE; }
 429     BOOL HasBeenProcessed() const   { return m_Processed; }
 430
 431     virtual IQType        GetType(PString * typeName = 0) const;
 432     virtual PXMLElement * GetBody();
 433
 434     virtual void SetType(IQType type);
 435     virtual void SetType(const PString& type); // custom, possibly non standard, type
 436     virtual void SetBody(PXMLElement * body);
 437
 438     // If the this message is response, returns a pointer to the
 439     // original set/get message
 440     virtual IQ *  GetOriginalMessage() const      { return m_OriginalIQ; }
 441     virtual void  SetOriginalMessage(IQ * iq);
 442
 443     /** Creates a new response iq for this message (that must
 444     be of the set/get type!)
 445     */
 446     virtual IQ *  BuildResult() const;
 447
 448     /** Creates an error response for this message
 449     */
 450     virtual IQ *  BuildError(const PString& type, const PString& code) const;
 451
 452     virtual PNotifierList GetResponseHandlers()   { return m_ResponseHandlers; }
 453
 454   protected:
 455     BOOL            m_Processed;
 456     IQ *            m_OriginalIQ;
 457     PNotifierList   m_ResponseHandlers;
 458   };
 459   /** JEP-0030 Service Discovery classes
 460    */
 461   namespace Disco
 462   {
 463     class Item : public PObject
 464     {
 465       PCLASSINFO(Item, PObject);
 466     public:
 467       Item(PXMLElement * item);
 468       Item(const PString& jid, const PString& node = PString::Empty());
 469
 470       const JID&      GetJID() const    { return m_JID; }
 471       const PString&  GetNode() const   { return m_Node; }
 472
 473       PXMLElement *   AsXML(PXMLElement * parent) const;
 474
 475     protected:
 476       const JID     m_JID;
 477       const PString m_Node;
 478     };
 479
 480     PDECLARE_LIST(ItemList, Item)
 481     public:
 482       ItemList(PXMLElement * list);
 483       PXMLElement * AsXML(PXMLElement * parent) const;
 484     };
 485
 486     class Identity : public PObject
 487     {
 488       PCLASSINFO(Identity, PObject);
 489     public:
 490       Identity(PXMLElement * identity);
 491       Identity(const PString& category, const PString& type, const PString& name);
 492
 493       const PString&  GetCategory() const   { return m_Category; }
 494       const PString&  GetType() const       { return m_Type; }
 495       const PString&  GetName() const       { return m_Name; }
 496
 497       PXMLElement *   AsXML(PXMLElement * parent) const;
 498
 499     protected:
 500       const PString m_Category;
 501       const PString m_Type;
 502       const PString m_Name;
 503     };
 504
 505     PDECLARE_LIST(IdentityList, Identity)
 506     public:
 507       IdentityList(PXMLElement * list);
 508       PXMLElement * AsXML(PXMLElement * parent) const;
 509     };
 510
 511     class Info : public PObject
 512     {
 513       PCLASSINFO(Info, PObject);
 514     public:
 515       Info(PXMLElement * info);
 516
 517       IdentityList&   GetIdentities() { return m_Identities; }
 518       PStringSet&     GetFeatures()   { return m_Features; }
 519
 520       PXMLElement *   AsXML(PXMLElement * parent) const;
 521
 522     protected:
 523       IdentityList  m_Identities;
 524       PStringSet    m_Features;
 525     };
 526   } // namespace Disco
 527
 528 }; // class XMPP
 529
 530
 531 #endif  // P_EXPAT
 532
 533 #endif  // _XMPP
 534
 535 // End of File ///////////////////////////////////////////////////////////////
 536
 537