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 
530  AuthorisationRequestNotifier m_onAuthorisationRequestNotifier;
531  PresenceChangeNotifier m_onPresenceChangeNotifier;
532  ReceivedMessageNotifier m_onReceivedMessageNotifier;
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;
618  CommandQueue m_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;
647  CmdSeqType m_sequence;
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 
State m_state
New state for presentity.
Definition: pres_ent.h:102
BuddyInfo(const PURL &presentity=PString::Empty(), const PString &displayName=PString::Empty())
Definition: pres_ent.h:358
Definition: manager.h:74
bool m_temporarilyUnavailable
Definition: pres_ent.h:536
Definition: pres_ent.h:66
ReceivedMessageNotifier m_onReceivedMessageNotifier
Definition: pres_ent.h:532
OpalSubscribeToPresenceCommand(bool subscribe=true)
Definition: pres_ent.h:667
ostream & operator<<(ostream &strm, OpalPresenceInfo::State state)
void Internal_SendMessageToCommand(const OpalSendMessageToCommand &cmd)
void SetReceivedMessageNotifier(const ReceivedMessageNotifier &notifier)
Set the notifier for the OnPresenceChange() function.
Definition: pres_ent.h:61
virtual bool SetBuddy(const BuddyInfo &buddy)
Definition: pres_ent.h:448
virtual bool SendMessageTo(const OpalIM &message)
virtual bool SetLocalPresence(OpalPresenceInfo::State state, const PString &note=PString::Empty())
Definition: pres_ent.h:84
OpalPresentityCommand(bool responseNeeded=false)
Definition: pres_ent.h:634
PURL m_presentity
Other presentity requesting our presence.
Definition: pres_ent.h:305
virtual BuddyStatus DeleteBuddyListEx()
void StartThread(bool startQueue=true)
virtual void Process(OpalPresentity &presentity)=0
virtual bool UnsubscribeFromPresence(const PURL &presentity)
static OpalPresentity * Create(OpalManager &manager, const PURL &url, const PString &scheme=PString::Empty())
Definition: pres_ent.h:81
Definition: pres_ent.h:680
Comparison Compare(const PObject &other) const
Definition: pres_ent.h:96
virtual bool SetPresenceAuthorisation(const PURL &presentity, Authorisation authorisation)
virtual void SetAOR(const PURL &aor)
Definition: pres_ent.h:72
__inline cls * CreateCommand()
Definition: pres_ent.h:280
Definition: pres_ent.h:73
CommandQueue m_commandQueue
Definition: pres_ent.h:618
virtual bool SendCommand(OpalPresentityCommand *cmd)
virtual bool UnsubscribeBuddyList()
Definition: pres_ent.h:483
PvCard m_vCard
Definition: pres_ent.h:370
Definition: pres_ent.h:237
virtual BuddyStatus SetBuddyListEx(const BuddyList &buddies)
virtual bool GetBuddy(BuddyInfo &buddy)
Definition: pres_ent.h:438
PStringOptions & GetAttributes()
< Get the attributes for this presentity.
Definition: pres_ent.h:183
Definition: pres_ent.h:303
const PURL & GetAOR() const
Definition: pres_ent.h:199
BuddyStatus
Definition: pres_ent.h:393
PString m_note
Optional extra note attached to request.
Definition: pres_ent.h:306
Definition: pres_ent.h:76
Definition: pres_ent.h:85
bool m_queueRunning
Definition: pres_ent.h:624
virtual bool Open()
Definition: pres_ent.h:357
PString m_note
Optional extra note attached to subscription request.
Definition: pres_ent.h:685
OpalPresentityWithCommandThread()
Construct the presentity class that uses a command thread.
Definition: pres_ent.h:75
virtual bool SendCommand(OpalPresentityCommand *cmd)
PURL m_homePage
Home page for buddy.
Definition: pres_ent.h:384
PFACTORY_LOAD(OpalPluginCodecManager)
virtual BuddyStatus DeleteBuddyEx(const PURL &presentity)
Definition: im.h:42
Definition: pres_ent.h:74
std::queue< OpalPresentityCommand * > CommandQueue
Definition: pres_ent.h:617
PString m_rawXML
Raw XML of buddy list entry.
Definition: pres_ent.h:388
PString m_note
Optional extra note attached to subscription request.
Definition: pres_ent.h:670
CmdSeqType m_sequence
Definition: pres_ent.h:647
OpalIM m_message
Definition: pres_ent.h:707
Definition: pres_ent.h:86
PString AsString() const
PresenceChangeNotifier m_onPresenceChangeNotifier
Definition: pres_ent.h:531
virtual bool SetBuddyList(const BuddyList &buddies)
Definition: pres_ent.h:420
virtual bool IsOpen() const
Definition: pres_ent.h:173
virtual BuddyStatus GetBuddyEx(BuddyInfo &buddy)
bool m_responseNeeded
Definition: pres_ent.h:648
PURL m_map
Definition: pres_ent.h:378
Definition: pres_ent.h:236
PSyncPoint m_commandQueueSync
Definition: pres_ent.h:621
PString m_displayName
Human readable name.
Definition: pres_ent.h:366
virtual bool Close()
virtual bool GetBuddyList(BuddyList &buddies)
Definition: pres_ent.h:410
Definition: pres_ent.h:233
Definition: pres_ent.h:665
PURL m_presentity
Definition: pres_ent.h:649
Definition: pres_ent.h:77
PAtomicBoolean m_open
Definition: pres_ent.h:534
Definition: pres_ent.h:83
static const PCaselessString & AuthNameKey()
Key for authentication name attribute.
PString m_contentType
MIME type code for XML.
Definition: pres_ent.h:387
Definition: pres_ent.h:135
OpalPresenceInfo::State m_localState
our presentity state
Definition: pres_ent.h:537
Definition: pres_ent.h:62
virtual bool DeleteBuddy(const PURL &presentity)
Definition: pres_ent.h:458
PMutex m_commandQueueMutex
Definition: pres_ent.h:619
OpalSetLocalPresenceCommand(State state=NoPresence)
Definition: pres_ent.h:696
virtual bool DeleteBuddyList()
Definition: pres_ent.h:429
State
Presence states.
Definition: pres_ent.h:60
virtual BuddyStatus GetBuddyListEx(BuddyList &buddies)
Definition: pres_ent.h:92
PString m_note
Additional information about state change.
Definition: pres_ent.h:103
Definition: pres_ent.h:68
PURL m_icon
Definition: pres_ent.h:374
Definition: pres_ent.h:80
virtual BuddyStatus SetBuddyEx(const BuddyInfo &buddy)
Definition: pres_ent.h:547
virtual ~OpalPresentityCommand()
Definition: pres_ent.h:637
virtual BuddyStatus SubscribeBuddyListEx(PINDEX &successfulCount, bool subscribe=true)
Definition: pres_ent.h:90
PURL m_sound
Definition: pres_ent.h:380
Definition: pres_ent.h:79
virtual void OnPresenceChange(const OpalPresenceInfo &info)
PURL m_target
The presentity that is being informed about the state change.
Definition: pres_ent.h:105
Definition: pres_ent.h:694
PMutex m_notificationMutex
Definition: pres_ent.h:535
OpalAuthorisationRequestCommand()
Definition: pres_ent.h:682
void SetPresenceChangeNotifier(const PresenceChangeNotifier &notifier)
Set the notifier for the OnPresenceChange() function.
std::list< BuddyInfo > BuddyList
Definition: pres_ent.h:391
void SetAuthorisationRequestNotifier(const AuthorisationRequestNotifier &notifier)
Set the notifier for the OnAuthorisationRequest() function.
Definition: pres_ent.h:87
Definition: pres_ent.h:99
virtual BuddyStatus UnsubscribeBuddyListEx()
PURL m_presentity
Typicall URI address-of-record.
Definition: pres_ent.h:365
PAtomicInteger::IntegerType CmdSeqType
Definition: pres_ent.h:646
Definition: pres_ent.h:63
Definition: pres_ent.h:78
OpalManager * m_manager
Definition: pres_ent.h:525
static State FromString(const PString &str)
OpalPresentity()
Construct the presentity class.
Definition: pres_ent.h:88
virtual void OnReceivedMessage(const OpalIM &message)
Definition: pres_ent.h:89
PURL m_aor
Definition: pres_ent.h:527
static const PCaselessString & AuthPasswordKey()
Key for authentication password attribute.
Definition: pres_ent.h:232
void StartQueue(bool startQueue=true)
OpalPresentity::Authorisation m_authorisation
Authorisation mode to indicate to remote.
Definition: pres_ent.h:684
PGloballyUniqueID m_guid
Definition: pres_ent.h:526
bool m_subscribe
Flag to indicate subscribing/unsubscribing.
Definition: pres_ent.h:669
virtual PStringArray GetAttributeNames() const =0
Get all attribute types for this presentity class.
virtual bool SubscribeBuddyList(bool subscribe=true)
Definition: pres_ent.h:472
Definition: pres_ent.h:98
PNotifierTemplate< const OpalIM & > ReceivedMessageNotifier
Definition: pres_ent.h:502
OpalPresenceInfo(State state=Unchanged)
Definition: pres_ent.h:108
Definition: pres_ent.h:94
PURL m_entity
The presentity whose state had changed.
Definition: pres_ent.h:104
Definition: pres_ent.h:67
Definition: pres_ent.h:632
Definition: pres_ent.h:235
Definition: pres_ent.h:702
static const PCaselessString & TimeToLiveKey()
Key for Time-To-Live attribute, in seconds for underlying protocol.
Definition: pres_ent.h:56
OpalSendMessageToCommand()
Definition: pres_ent.h:705
virtual bool SubscribeToPresence(const PURL &presentity, bool subscribe=true, const PString &note=PString::Empty())
bool m_threadRunning
Definition: pres_ent.h:623
Definition: pres_ent.h:395
OpalPresentityCommand * InternalCreateCommand(const char *cmdName)
Definition: pres_ent.h:95
PNotifierTemplate< const AuthorisationRequest & > AuthorisationRequestNotifier
Definition: pres_ent.h:320
virtual PStringArray GetAttributeTypes() const =0
virtual bool GetLocalPresence(OpalPresenceInfo::State &state, PString &note)
Authorisation
Authorisation modes for SetPresenceAuthorisation()
Definition: pres_ent.h:231
PStringOptions m_attributes
Definition: pres_ent.h:528
Definition: pres_ent.h:82
PThread * m_thread
Definition: pres_ent.h:625
Definition: pres_ent.h:93
AuthorisationRequestNotifier m_onAuthorisationRequestNotifier
Definition: pres_ent.h:530
PNotifierTemplate< const OpalPresenceInfo & > PresenceChangeNotifier
Definition: pres_ent.h:341
PString m_localStateNote
Additional note attached to the.
Definition: pres_ent.h:538
Definition: pres_ent.h:97
Definition: pres_ent.h:91
PAtomicInteger m_commandSequence
Definition: pres_ent.h:620
PTime m_when
Time/date of state change.
Definition: pres_ent.h:106
virtual void OnAuthorisationRequest(const AuthorisationRequest &request)