pres_ent.h

Go to the documentation of this file.

/*
 * prese_ent.h
 *
 * Presence Entity classes for Opal
 *
 * Open Phone Abstraction Library (OPAL)
 *
 * Copyright (c) 2009 Post Increment
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Post Increment
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 26283 $
 * $Author: rjongbloed $
 * $Date: 2011-08-08 02:41:14 -0500 (Mon, 08 Aug 2011) $
 */

#ifndef OPAL_IM_PRES_ENT_H
#define OPAL_IM_PRES_ENT_H

#include <ptlib.h>
#include <opal/buildopts.h>

#include <ptlib/pfactory.h>
#include <ptlib/safecoll.h>
#include <ptclib/url.h>
#include <ptclib/guid.h>
#include <ptclib/vcard.h>

#include <im/im.h>

#include <list>
#include <queue>

class OpalManager;
class OpalPresentityCommand;



class OpalPresenceInfo : public PObject
{
  public:
    enum State {
      InternalError = -3,    // something bad happened
      Forbidden     = -2,    // access to presence information was specifically forbidden
      NoPresence    = -1,    // remove presence status - not the same as Unavailable or Away

      // basic states (from RFC 3863)
      Unchanged,
      Available,
      Unavailable,

      // extended states (from RFC 4480)
      // if this is changed, also change the tables in sippres.cxx and handlers.cxx - look for RFC 4480
      ExtendedBase    = 100,
      UnknownExtended = ExtendedBase,
      Appointment,
      Away,
      Breakfast,
      Busy,
      Dinner,
      Holiday,
      InTransit,
      LookingForWork,
      Lunch,
      Meal,
      Meeting,
      OnThePhone,
      Other,
      Performance,
      PermanentAbsence,
      Playing,
      Presentation,
      Shopping,
      Sleeping,
      Spectator,
      Steering,
      Travel,
      TV,
      Vacation,
      Working,
      Worship
    };

    State   m_state;    
    PString m_note;     
    PURL    m_entity;   
    PURL    m_target;   
    PTime   m_when;     

    OpalPresenceInfo(State state = Unchanged) : m_state(state) { }

    static PString AsString(State state);
    static State FromString(const PString & str);
    PString AsString() const;

    Comparison Compare(const PObject & other) const;
};

ostream & operator<<(ostream & strm, OpalPresenceInfo::State state);


class OpalSetLocalPresenceCommand;
class OpalSubscribeToPresenceCommand;
class OpalAuthorisationRequestCommand;
class OpalSendMessageToCommand;

class OpalPresentity : public PSafeObject
{
    PCLASSINFO(OpalPresentity, PSafeObject);

  protected:
    OpalPresentity();
    OpalPresentity(const OpalPresentity & other);

  public:
    ~OpalPresentity();

    static OpalPresentity * Create(
      OpalManager & manager, 
      const PURL & url,      
      const PString & scheme = PString::Empty() 
    );

    virtual bool Open() = 0;

    virtual bool IsOpen() const = 0;

    virtual bool Close() = 0;


    PStringOptions & GetAttributes() { return m_attributes; }

    virtual PStringArray GetAttributeNames() const = 0;

    virtual PStringArray GetAttributeTypes() const = 0;

    static const PCaselessString & AuthNameKey();         
    static const PCaselessString & AuthPasswordKey();     
    static const PCaselessString & TimeToLiveKey();       

    const PURL & GetAOR() const { return m_aor; }

    virtual bool SubscribeToPresence(
      const PURL & presentity,      
      bool subscribe = true,        
      const PString & note = PString::Empty() 
    );

    virtual bool UnsubscribeFromPresence(
      const PURL & presentity    
    );

    enum Authorisation {
      AuthorisationPermitted,
      AuthorisationDenied,
      AuthorisationDeniedPolitely,
      AuthorisationConfirming,
      AuthorisationRemove,
      NumAuthorisations
    };

    virtual bool SetPresenceAuthorisation(
      const PURL & presentity,        
      Authorisation authorisation     
    );

    virtual bool SetLocalPresence(
      OpalPresenceInfo::State state,            
      const PString & note = PString::Empty()   
    );

    virtual bool GetLocalPresence(
      OpalPresenceInfo::State & state, 
      PString & note
    );


    template <class cls>
    __inline cls * CreateCommand()
    {
      return dynamic_cast<cls *>(InternalCreateCommand(typeid(cls).name()));
    }

    virtual bool SendCommand(
      OpalPresentityCommand * cmd   
    );

    struct AuthorisationRequest
    {
      PURL    m_presentity; 
      PString m_note;       
    };

    virtual void OnAuthorisationRequest(
      const AuthorisationRequest & request  
    );

    typedef PNotifierTemplate<const AuthorisationRequest &> AuthorisationRequestNotifier;
#define PDECLARE_AuthorisationRequestNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalPresentity::AuthorisationRequest &)
    #define PCREATE_AuthorisationRequestNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalPresentity::AuthorisationRequest &)

    void SetAuthorisationRequestNotifier(
      const AuthorisationRequestNotifier & notifier   
    );

    virtual void OnPresenceChange(
      const OpalPresenceInfo & info 
    );

    typedef PNotifierTemplate<const OpalPresenceInfo &> PresenceChangeNotifier;
    #define PDECLARE_PresenceChangeNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalPresenceInfo &)
    #define PCREATE_PresenceChangeNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalPresenceInfo &)

    void SetPresenceChangeNotifier(
      const PresenceChangeNotifier & notifier   
    );

    struct BuddyInfo {
      BuddyInfo(
        const PURL & presentity = PString::Empty(),
        const PString & displayName = PString::Empty()
      ) : m_presentity(presentity)
        , m_displayName(displayName)
      { }

      PURL    m_presentity;   
      PString m_displayName;  

      // RFC4482 contact fields, note most of these are duplicated
      // in the vCard structure
      PvCard  m_vCard;        
      PURL    m_icon;         
      PURL    m_map;          
      PURL    m_sound;        
      PURL    m_homePage;     

      // Extra field for protocol dependent "get out of gaol" card
      PString m_contentType;  
      PString m_rawXML;       
    };

    typedef std::list<BuddyInfo> BuddyList;

    enum BuddyStatus {
      BuddyStatus_GenericFailure             = -1,
      BuddyStatus_OK                         = 0,
      BuddyStatus_SpecifiedBuddyNotFound,
      BuddyStatus_ListFeatureNotImplemented,
      BuddyStatus_ListTemporarilyUnavailable,
      BuddyStatus_ListMayBeIncomplete,
      BuddyStatus_BadBuddySpecification,
      BuddyStatus_ListSubscribeFailed,
      BuddyStatus_AccountNotLoggedIn
    };

    virtual BuddyStatus GetBuddyListEx(
      BuddyList & buddies   
    );
    virtual bool GetBuddyList(
      BuddyList & buddies   
    )
    { return GetBuddyListEx(buddies) == BuddyStatus_OK; }

    virtual BuddyStatus SetBuddyListEx(
      const BuddyList & buddies   
    );
    virtual bool SetBuddyList(
      const BuddyList & buddies   
    )
    { return SetBuddyListEx(buddies) == BuddyStatus_OK; }


    virtual BuddyStatus DeleteBuddyListEx();
    virtual bool DeleteBuddyList() { return DeleteBuddyListEx() == BuddyStatus_OK; }

    virtual BuddyStatus GetBuddyEx(
      BuddyInfo & buddy
    );
    virtual bool GetBuddy(
      BuddyInfo & buddy
    )
    { return GetBuddyEx(buddy) == BuddyStatus_OK; }

    virtual BuddyStatus SetBuddyEx(
      const BuddyInfo & buddy
    );
    virtual bool SetBuddy(
      const BuddyInfo & buddy
    )
    { return SetBuddyEx(buddy) == BuddyStatus_OK; }

    virtual BuddyStatus DeleteBuddyEx(
      const PURL & presentity
    );
    virtual bool DeleteBuddy(
      const PURL & presentity
    )
    { return DeleteBuddyEx(presentity) == BuddyStatus_OK; }

    virtual BuddyStatus SubscribeBuddyListEx(
      PINDEX & successfulCount,
      bool subscribe = true
    );
    virtual bool SubscribeBuddyList(
      bool subscribe = true
    )
    { PINDEX successfulCount; return SubscribeBuddyListEx(successfulCount, subscribe) == BuddyStatus_OK; }

    virtual BuddyStatus UnsubscribeBuddyListEx();
    virtual bool UnsubscribeBuddyList()
    { return UnsubscribeBuddyListEx() == BuddyStatus_OK; }
  
  
    virtual bool SendMessageTo(
      const OpalIM & message
    );

    virtual void OnReceivedMessage(
      const OpalIM & message 
    );

    typedef PNotifierTemplate<const OpalIM &> ReceivedMessageNotifier;
    #define PDECLARE_ReceivedMessageNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, const OpalIM &)
    #define PCREATE_ReceivedMessageNotifier(fn) PCREATE_NOTIFIER2(fn, const OpalIM &)

    void SetReceivedMessageNotifier(
      const ReceivedMessageNotifier & notifier   
    );

    virtual void SetAOR(
      const PURL & aor
    );

    void Internal_SendMessageToCommand(const OpalSendMessageToCommand & cmd);

    virtual PString GetID() const;

  protected:
    OpalPresentityCommand * InternalCreateCommand(const char * cmdName);

    OpalManager        * m_manager;
    PGloballyUniqueID    m_guid;
    PURL                 m_aor;
    PStringOptions       m_attributes;

    AuthorisationRequestNotifier m_onAuthorisationRequestNotifier;
    PresenceChangeNotifier       m_onPresenceChangeNotifier;
    ReceivedMessageNotifier      m_onReceivedMessageNotifier;

    PMutex m_notificationMutex;
    PAtomicInteger::IntegerType m_idNumber;

    bool m_temporarilyUnavailable;
    OpalPresenceInfo::State m_localState;      
    PString m_localStateNote;                  
};



class OpalPresentityWithCommandThread : public OpalPresentity
{
    PCLASSINFO(OpalPresentityWithCommandThread, OpalPresentity);

  protected:
    OpalPresentityWithCommandThread();
    OpalPresentityWithCommandThread(const OpalPresentityWithCommandThread & other);

  public:
    ~OpalPresentityWithCommandThread();

    virtual bool SendCommand(
      OpalPresentityCommand * cmd   
    );

    void StartThread(
      bool startQueue = true
    );

    void StopThread();

    void StartQueue(
      bool startQueue = true
    );
    

  protected:
    void ThreadMain();

    typedef std::queue<OpalPresentityCommand *> CommandQueue;
    CommandQueue   m_commandQueue;
    PMutex         m_commandQueueMutex;
    PAtomicInteger m_commandSequence;
    PSyncPoint     m_commandQueueSync;

    bool      m_threadRunning;
    bool      m_queueRunning;
    PThread * m_thread;
};


class OpalPresentityCommand {
  public:
    OpalPresentityCommand(bool responseNeeded = false) 
      : m_responseNeeded(responseNeeded)
    { }
    virtual ~OpalPresentityCommand() { }

    virtual void Process(
      OpalPresentity & presentity
    ) = 0;

    typedef PAtomicInteger::IntegerType CmdSeqType;
    CmdSeqType m_sequence;
    bool       m_responseNeeded;
    PURL       m_presentity;
};

#define OPAL_DEFINE_COMMAND(command, entity, func) \
  class entity##_##command : public command \
  { \
    public: virtual void Process(OpalPresentity & presentity) { dynamic_cast<entity &>(presentity).func(*this); } \
  }; \
  static PFactory<OpalPresentityCommand>::Worker<entity##_##command> \
  s_##entity##_##command(PDefaultPFactoryKey(entity::Class())+typeid(command).name())


class OpalSubscribeToPresenceCommand : public OpalPresentityCommand {
  public:
    OpalSubscribeToPresenceCommand(bool subscribe = true) : m_subscribe(subscribe) { }

    bool    m_subscribe;  
    PString m_note;       
};


class OpalAuthorisationRequestCommand : public OpalPresentityCommand {
  public:
    OpalAuthorisationRequestCommand() : m_authorisation(OpalPresentity::AuthorisationPermitted) { }

    OpalPresentity::Authorisation m_authorisation;  
    PString m_note;                                 
};


class OpalSetLocalPresenceCommand : public OpalPresentityCommand, public OpalPresenceInfo {
  public:
    OpalSetLocalPresenceCommand(State state = NoPresence) : OpalPresenceInfo(state) { }
};


class OpalSendMessageToCommand : public OpalPresentityCommand
{
  public:
    OpalSendMessageToCommand() { }

    OpalIM m_message;
};


// Include concrete classes here so the factories are initialised
#if OPAL_SIP && OPAL_PTLIB_EXPAT
PFACTORY_LOAD(SIP_Presentity);
#endif


#endif  // OPAL_IM_PRES_ENT_H