OPAL  Version 3.10.10
pres_ent.h
Go to the documentation of this file.
1 /*
2  * prese_ent.h
3  *
4  * Presence Entity classes for Opal
5  *
6  * Open Phone Abstraction Library (OPAL)
7  *
8  * Copyright (c) 2009 Post Increment
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 Open Phone Abstraction Library.
21  *
22  * The Initial Developer of the Original Code is Post Increment
23  *
24  * Contributor(s): ______________________________________.
25  *
26  * $Revision: 28081 $
27  * $Author: rjongbloed $
28  * $Date: 2012-07-22 07:24:14 -0500 (Sun, 22 Jul 2012) $
29  */
30 
31 #ifndef OPAL_IM_PRES_ENT_H
32 #define OPAL_IM_PRES_ENT_H
33 
34 #include <ptlib.h>
35 #include <opal/buildopts.h>
36 
37 #include <ptlib/pfactory.h>
38 #include <ptlib/safecoll.h>
39 #include <ptclib/url.h>
40 #include <ptclib/guid.h>
41 #include <ptclib/vcard.h>
42 
43 #include <im/im.h>
44 
45 #include <list>
46 #include <queue>
47 
48 class OpalManager;
50 
51 
53 
56 class OpalPresenceInfo : public PObject
57 {
58  public:
60  enum State {
61  InternalError = -3, // something bad happened
62  Forbidden = -2, // access to presence information was specifically forbidden
63  NoPresence = -1, // remove presence status - not the same as Unavailable or Away
64 
65  // basic states (from RFC 3863)
69 
70  // extended states (from RFC 4480)
71  // if this is changed, also change the tables in sippres.cxx and handlers.cxx - look for RFC 4480
72  ExtendedBase = 100,
96  TV,
100  };
101 
103  PString m_note;
104  PURL m_entity;
105  PURL m_target;
106  PTime m_when;
107 
108  OpalPresenceInfo(State state = Unchanged) : m_state(state) { }
109 
110  static PString AsString(State state);
111  static State FromString(const PString & str);
112  PString AsString() const;
113 
114  Comparison Compare(const PObject & other) const;
115 };
116 
117 ostream & operator<<(ostream & strm, OpalPresenceInfo::State state);
118 
120 
125 
135 class OpalPresentity : public PSafeObject
136 {
137  PCLASSINFO(OpalPresentity, PSafeObject);
138 
141  protected:
143  OpalPresentity();
144  OpalPresentity(const OpalPresentity & other);
145 
146  public:
147  ~OpalPresentity();
148 
151  static OpalPresentity * Create(
152  OpalManager & manager,
153  const PURL & url,
154  const PString & scheme = PString::Empty()
155  );
157 
169  virtual bool Open();
170 
173  virtual bool IsOpen() const { return m_open; }
174 
177  virtual bool Close();
179 
182  PStringOptions & GetAttributes() { return m_attributes; }
184 
186  virtual PStringArray GetAttributeNames() const = 0;
187 
189  virtual PStringArray GetAttributeTypes() const = 0;
190 
191  static const PCaselessString & AuthNameKey();
192  static const PCaselessString & AuthPasswordKey();
193  static const PCaselessString & TimeToLiveKey();
194 
199  const PURL & GetAOR() const { return m_aor; }
201 
212  virtual bool SubscribeToPresence(
213  const PURL & presentity,
214  bool subscribe = true,
215  const PString & note = PString::Empty()
216  );
217 
226  virtual bool UnsubscribeFromPresence(
227  const PURL & presentity
228  );
229 
238  };
239 
250  virtual bool SetPresenceAuthorisation(
251  const PURL & presentity,
252  Authorisation authorisation
253  );
254 
262  virtual bool SetLocalPresence(
264  const PString & note = PString::Empty()
265  );
266 
269  virtual bool GetLocalPresence(
270  OpalPresenceInfo::State & state,
271  PString & note
272  );
273 
274 
279  template <class cls>
280  __inline cls * CreateCommand()
281  {
282  return dynamic_cast<cls *>(InternalCreateCommand(typeid(cls).name()));
283  }
284 
296  virtual bool SendCommand(
297  OpalPresentityCommand * cmd
298  );
300 
304  {
306  PString m_note;
307  };
308 
316  virtual void OnAuthorisationRequest(
317  const AuthorisationRequest & request
318  );
319 
320  typedef PNotifierTemplate<const AuthorisationRequest &> AuthorisationRequestNotifier;
321 #define PDECLARE_AuthorisationRequestNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalPresentity::AuthorisationRequest &)
322  #define PCREATE_AuthorisationRequestNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalPresentity::AuthorisationRequest &)
323 
326  const AuthorisationRequestNotifier & notifier
327  );
328 
337  virtual void OnPresenceChange(
338  const OpalPresenceInfo & info
339  );
340 
341  typedef PNotifierTemplate<const OpalPresenceInfo &> PresenceChangeNotifier;
342  #define PDECLARE_PresenceChangeNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalPresenceInfo &)
343  #define PCREATE_PresenceChangeNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalPresenceInfo &)
344 
347  const PresenceChangeNotifier & notifier
348  );
350 
357  struct BuddyInfo {
359  const PURL & presentity = PString::Empty(),
360  const PString & displayName = PString::Empty()
361  ) : m_presentity(presentity)
362  , m_displayName(displayName)
363  { }
364 
366  PString m_displayName;
367 
368  // RFC4482 contact fields, note most of these are duplicated
369  // in the vCard structure
370  PvCard m_vCard;
374  PURL m_icon;
378  PURL m_map;
380  PURL m_sound;
384  PURL m_homePage;
385 
386  // Extra field for protocol dependent "get out of gaol" card
387  PString m_contentType;
388  PString m_rawXML;
389  };
390 
391  typedef std::list<BuddyInfo> BuddyList;
392 
393  enum BuddyStatus {
403  };
404 
407  virtual BuddyStatus GetBuddyListEx(
408  BuddyList & buddies
409  );
410  virtual bool GetBuddyList(
411  BuddyList & buddies
412  )
413  { return GetBuddyListEx(buddies) == BuddyStatus_OK; }
414 
417  virtual BuddyStatus SetBuddyListEx(
418  const BuddyList & buddies
419  );
420  virtual bool SetBuddyList(
421  const BuddyList & buddies
422  )
423  { return SetBuddyListEx(buddies) == BuddyStatus_OK; }
424 
425 
428  virtual BuddyStatus DeleteBuddyListEx();
429  virtual bool DeleteBuddyList() { return DeleteBuddyListEx() == BuddyStatus_OK; }
430 
435  virtual BuddyStatus GetBuddyEx(
436  BuddyInfo & buddy
437  );
438  virtual bool GetBuddy(
439  BuddyInfo & buddy
440  )
441  { return GetBuddyEx(buddy) == BuddyStatus_OK; }
442 
445  virtual BuddyStatus SetBuddyEx(
446  const BuddyInfo & buddy
447  );
448  virtual bool SetBuddy(
449  const BuddyInfo & buddy
450  )
451  { return SetBuddyEx(buddy) == BuddyStatus_OK; }
452 
455  virtual BuddyStatus DeleteBuddyEx(
456  const PURL & presentity
457  );
458  virtual bool DeleteBuddy(
459  const PURL & presentity
460  )
461  { return DeleteBuddyEx(presentity) == BuddyStatus_OK; }
462 
469  PINDEX & successfulCount,
470  bool subscribe = true
471  );
472  virtual bool SubscribeBuddyList(
473  bool subscribe = true
474  )
475  { PINDEX successfulCount; return SubscribeBuddyListEx(successfulCount, subscribe) == BuddyStatus_OK; }
476 
483  virtual bool UnsubscribeBuddyList()
484  { return UnsubscribeBuddyListEx() == BuddyStatus_OK; }
486 
487 
490  virtual bool SendMessageTo(
491  const OpalIM & message
492  );
493 
498  virtual void OnReceivedMessage(
499  const OpalIM & message
500  );
501 
502  typedef PNotifierTemplate<const OpalIM &> ReceivedMessageNotifier;
503  #define PDECLARE_ReceivedMessageNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalIM &)
504  #define PCREATE_ReceivedMessageNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalIM &)
505 
508  const ReceivedMessageNotifier & notifier
509  );
511 
516  virtual void SetAOR(
517  const PURL & aor
518  );
519 
521 
522  protected:
523  OpalPresentityCommand * InternalCreateCommand(const char * cmdName);
524 
526  PGloballyUniqueID m_guid;
527  PURL m_aor;
528  PStringOptions m_attributes;
529 
533 
534  PAtomicBoolean m_open;
539 };
540 
541 
543 
548 {
550 
553  protected:
557 
558  public:
564 
578  virtual bool SendCommand(
579  OpalPresentityCommand * cmd
580  );
582 
595  void StartThread(
596  bool startQueue = true
597  );
598 
604  void StopThread();
605 
608  void StartQueue(
609  bool startQueue = true
610  );
611 
613 
614  protected:
615  void ThreadMain();
616 
617  typedef std::queue<OpalPresentityCommand *> CommandQueue;
620  PAtomicInteger m_commandSequence;
621  PSyncPoint m_commandQueueSync;
622 
625  PThread * m_thread;
626 };
627 
629 
633  public:
634  OpalPresentityCommand(bool responseNeeded = false)
635  : m_responseNeeded(responseNeeded)
636  { }
638 
642  virtual void Process(
643  OpalPresentity & presentity
644  ) = 0;
645 
646  typedef PAtomicInteger::IntegerType CmdSeqType;
650 };
651 
654 #define OPAL_DEFINE_COMMAND(command, entity, func) \
655  class entity##_##command : public command \
656  { \
657  public: virtual void Process(OpalPresentity & presentity) { dynamic_cast<entity &>(presentity).func(*this); } \
658  }; \
659  static PFactory<OpalPresentityCommand>::Worker<entity##_##command> \
660  s_##entity##_##command(PDefaultPFactoryKey(entity::Class())+typeid(command).name())
661 
662 
666  public:
667  OpalSubscribeToPresenceCommand(bool subscribe = true) : m_subscribe(subscribe) { }
668 
669  bool m_subscribe;
670  PString m_note;
671 };
672 
673 
681  public:
683 
685  PString m_note;
686 };
687 
688 
695  public:
697 };
698 
699 
703 {
704  public:
706 
708 };
709 
711 
712 // Include concrete classes here so the factories are initialised
713 #if OPAL_SIP && OPAL_PTLIB_EXPAT
714 PFACTORY_LOAD(SIP_Presentity);
715 #endif
716 
717 
718 #endif // OPAL_IM_PRES_ENT_H
719