OPAL  Version 3.10.4
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: 26283 $
27  * $Author: rjongbloed $
28  * $Date: 2011-08-08 02:41:14 -0500 (Mon, 08 Aug 2011) $
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() = 0;
170 
173  virtual bool IsOpen() const = 0;
174 
177  virtual bool Close() = 0;
179 
182 
183  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  virtual PString GetID() const;
523 
524  protected:
525  OpalPresentityCommand * InternalCreateCommand(const char * cmdName);
526 
528  PGloballyUniqueID m_guid;
529  PURL m_aor;
530  PStringOptions m_attributes;
531 
535 
537  PAtomicInteger::IntegerType m_idNumber;
538 
542 };
543 
544 
546 
551 {
553 
556  protected:
560 
561  public:
567 
581  virtual bool SendCommand(
582  OpalPresentityCommand * cmd
583  );
585 
598  void StartThread(
599  bool startQueue = true
600  );
601 
607  void StopThread();
608 
611  void StartQueue(
612  bool startQueue = true
613  );
614 
616 
617  protected:
618  void ThreadMain();
619 
620  typedef std::queue<OpalPresentityCommand *> CommandQueue;
623  PAtomicInteger m_commandSequence;
624  PSyncPoint m_commandQueueSync;
625 
628  PThread * m_thread;
629 };
630 
632 
636  public:
637  OpalPresentityCommand(bool responseNeeded = false)
638  : m_responseNeeded(responseNeeded)
639  { }
641 
645  virtual void Process(
646  OpalPresentity & presentity
647  ) = 0;
648 
649  typedef PAtomicInteger::IntegerType CmdSeqType;
653 };
654 
657 #define OPAL_DEFINE_COMMAND(command, entity, func) \
658  class entity##_##command : public command \
659  { \
660  public: virtual void Process(OpalPresentity & presentity) { dynamic_cast<entity &>(presentity).func(*this); } \
661  }; \
662  static PFactory<OpalPresentityCommand>::Worker<entity##_##command> \
663  s_##entity##_##command(PDefaultPFactoryKey(entity::Class())+typeid(command).name())
664 
665 
669  public:
670  OpalSubscribeToPresenceCommand(bool subscribe = true) : m_subscribe(subscribe) { }
671 
672  bool m_subscribe;
673  PString m_note;
674 };
675 
676 
684  public:
686 
688  PString m_note;
689 };
690 
691 
698  public:
700 };
701 
702 
706 {
707  public:
709 
711 };
712 
714 
715 // Include concrete classes here so the factories are initialised
716 #if OPAL_SIP && OPAL_PTLIB_EXPAT
717 PFACTORY_LOAD(SIP_Presentity);
718 #endif
719 
720 
721 #endif // OPAL_IM_PRES_ENT_H
722