OPAL Version 3.10.4

- Main Page
- Related Pages
- Namespaces
- Data Structures
- Files

- File List
- Globals

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;
49 class OpalPresentityCommand;
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)
66 Unchanged,
67 Available,
68 Unavailable,
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,
73 UnknownExtended = ExtendedBase,
74 Appointment,
75 Away,
76 Breakfast,
77 Busy,
78 Dinner,
79 Holiday,
80 InTransit,
81 LookingForWork,
82 Lunch,
83 Meal,
84 Meeting,
85 OnThePhone,
86 Other,
87 Performance,
88 PermanentAbsence,
89 Playing,
90 Presentation,
91 Shopping,
92 Sleeping,
93 Spectator,
94 Steering,
95 Travel,
96 TV,
97 Vacation,
98 Working,
99 Worship
100 };
101
102 State m_state;
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
121 class OpalSetLocalPresenceCommand;
122 class OpalSubscribeToPresenceCommand;
123 class OpalAuthorisationRequestCommand;
124 class OpalSendMessageToCommand;
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
231 enum Authorisation {
232 AuthorisationPermitted,
233 AuthorisationDenied,
234 AuthorisationDeniedPolitely,
235 AuthorisationConfirming,
236 AuthorisationRemove,
237 NumAuthorisations
238 };
239
250 virtual bool SetPresenceAuthorisation(
251 const PURL & presentity,
252 Authorisation authorisation
253 );
254
262 virtual bool SetLocalPresence(
263 OpalPresenceInfo::State state,
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
303 struct AuthorisationRequest
304 {
305 PURL m_presentity;
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
325 void SetAuthorisationRequestNotifier(
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
346 void SetPresenceChangeNotifier(
347 const PresenceChangeNotifier & notifier
348 );
350
357 struct BuddyInfo {
358 BuddyInfo(
359 const PURL & presentity = PString::Empty(),
360 const PString & displayName = PString::Empty()
361 ) : m_presentity(presentity)
362 , m_displayName(displayName)
363 { }
364
365 PURL m_presentity;
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 {
394 BuddyStatus_GenericFailure = -1,
395 BuddyStatus_OK = 0,
396 BuddyStatus_SpecifiedBuddyNotFound,
397 BuddyStatus_ListFeatureNotImplemented,
398 BuddyStatus_ListTemporarilyUnavailable,
399 BuddyStatus_ListMayBeIncomplete,
400 BuddyStatus_BadBuddySpecification,
401 BuddyStatus_ListSubscribeFailed,
402 BuddyStatus_AccountNotLoggedIn
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
468 virtual BuddyStatus SubscribeBuddyListEx(
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
482 virtual BuddyStatus UnsubscribeBuddyListEx();
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
507 void SetReceivedMessageNotifier(
508 const ReceivedMessageNotifier & notifier
509 );
511
516 virtual void SetAOR(
517 const PURL & aor
518 );
519
520 void Internal_SendMessageToCommand(const OpalSendMessageToCommand & cmd);
521
522 virtual PString GetID() const;
523
524 protected:
525 OpalPresentityCommand * InternalCreateCommand(const char * cmdName);
526
527 OpalManager * m_manager;
528 PGloballyUniqueID m_guid;
529 PURL m_aor;
530 PStringOptions m_attributes;
531
532 AuthorisationRequestNotifier m_onAuthorisationRequestNotifier;
533 PresenceChangeNotifier m_onPresenceChangeNotifier;
534 ReceivedMessageNotifier m_onReceivedMessageNotifier;
535
536 PMutex m_notificationMutex;
537 PAtomicInteger::IntegerType m_idNumber;
538
539 bool m_temporarilyUnavailable;
540 OpalPresenceInfo::State m_localState;
541 PString m_localStateNote;
542 };
543
544
546
550 class OpalPresentityWithCommandThread : public OpalPresentity
551 {
552 PCLASSINFO(OpalPresentityWithCommandThread, OpalPresentity);
553
556 protected:
558 OpalPresentityWithCommandThread();
559 OpalPresentityWithCommandThread(const OpalPresentityWithCommandThread & other);
560
561 public:
565 ~OpalPresentityWithCommandThread();
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;
621 CommandQueue m_commandQueue;
622 PMutex m_commandQueueMutex;
623 PAtomicInteger m_commandSequence;
624 PSyncPoint m_commandQueueSync;
625
626 bool m_threadRunning;
627 bool m_queueRunning;
628 PThread * m_thread;
629 };
630
632
635 class OpalPresentityCommand {
636 public:
637 OpalPresentityCommand(bool responseNeeded = false)
638 : m_responseNeeded(responseNeeded)
639 { }
640 virtual ~OpalPresentityCommand() { }
641
645 virtual void Process(
646 OpalPresentity & presentity
647 ) = 0;
648
649 typedef PAtomicInteger::IntegerType CmdSeqType;
650 CmdSeqType m_sequence;
651 bool m_responseNeeded;
652 PURL m_presentity;
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
668 class OpalSubscribeToPresenceCommand : public OpalPresentityCommand {
669 public:
670 OpalSubscribeToPresenceCommand(bool subscribe = true) : m_subscribe(subscribe) { }
671
672 bool m_subscribe;
673 PString m_note;
674 };
675
676
683 class OpalAuthorisationRequestCommand : public OpalPresentityCommand {
684 public:
685 OpalAuthorisationRequestCommand() : m_authorisation(OpalPresentity::AuthorisationPermitted) { }
686
687 OpalPresentity::Authorisation m_authorisation;
688 PString m_note;
689 };
690
691
697 class OpalSetLocalPresenceCommand : public OpalPresentityCommand, public OpalPresenceInfo {
698 public:
699 OpalSetLocalPresenceCommand(State state = NoPresence) : OpalPresenceInfo(state) { }
700 };
701
702
705 class OpalSendMessageToCommand : public OpalPresentityCommand
706 {
707 public:
708 OpalSendMessageToCommand() { }
709
710 OpalIM m_message;
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