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): ______________________________________.
 */

#ifndef OPAL_IM_PRES_ENT_H
#define OPAL_IM_PRES_ENT_H

#include <ptlib.h>
#include <opal_config.h>

#if OPAL_HAS_PRESENCE

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

#ifdef P_VCARD
  #include <ptclib/vcard.h>
#endif

#include <im/im.h>

#include <list>
#include <queue>

class OpalManager;
class OpalPresentityCommand;



class OpalPresenceInfo : public PObject
{
    PCLASSINFO_WITH_CLONE(OpalPresenceInfo, PObject);
  public:
    P_DECLARE_STREAMABLE_ENUM_EX(State,StateCount,
      UnknownUser,-4,     
      InternalError,      
      Forbidden,          
      NoPresence,         
      Unchanged,          
      Available,          
      Unavailable         
    );

    State      m_state;        
    PStringSet m_activities;   
    PString    m_note;         
    PTime      m_when;         

    PURL       m_entity;       
    PURL       m_target;       
    PString    m_service;      
    PString    m_contact;      
    PStringSet m_capabilities; 

    PString    m_infoType;     
    PString    m_infoData;     

    OpalPresenceInfo(State state = Unchanged);
    OpalPresenceInfo(const PString & str);

    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();

    virtual bool IsOpen() const { return m_open; }

    virtual bool Close();

    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     
    );

    bool SetLocalPresence(
      const OpalPresenceInfo & info   
    );

    // For backward compatibility
    bool SetLocalPresence(
      OpalPresenceInfo::State state,            
      const PString & note = PString::Empty()  
    );

    bool GetLocalPresence(
      OpalPresenceInfo & info   
    );

    // For backward compatibility
    bool GetLocalPresence(
      OpalPresenceInfo::State & state, 
      PString & note
    );


    template <class cls> __inline cls * CreateCommand();

    virtual bool SendCommand(
      OpalPresentityCommand * cmd   
    );

    struct AuthorisationRequest
    {
      PURL    m_presentity; 
      PString m_note;       
    };

    virtual void OnAuthorisationRequest(
      const AuthorisationRequest & request  
    );

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

    void SetAuthorisationRequestNotifier(
      const AuthorisationRequestNotifier & notifier   
    );

    virtual void OnPresenceChange(
      const OpalPresenceInfo & info 
    );

    typedef PNotifierTemplate< PAutoPtr<OpalPresenceInfo> > PresenceChangeNotifier;
    #define PDECLARE_PresenceChangeNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalPresentity, cls, fn, PAutoPtr<OpalPresenceInfo>)
    #define PDECLARE_ASYNC_PresenceChangeNotifier(cls, fn) PDECLARE_ASYNC_NOTIFIER2(OpalPresentity, cls, fn, PAutoPtr<OpalPresenceInfo>)
    #define PCREATE_PresenceChangeNotifier(fn) PCREATE_NOTIFIER2(fn, PAutoPtr<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
#ifdef P_VCARD
      PvCard  m_vCard;        
#endif
      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; }
  
  
#if OPAL_HAS_IM

    virtual bool SendMessageTo(
      const OpalIM & message
    );

    virtual void OnReceivedMessage(
      const OpalIM & message 
    );

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

    void SetReceivedMessageNotifier(
      const ReceivedMessageNotifier & notifier   
    );

    void Internal_SendMessageToCommand(const OpalSendMessageToCommand & cmd);
#endif // OPAL_HAS_IM

    virtual void SetAOR(
      const PURL & aor
    );

    OpalManager & GetManager() const { return *m_manager; }

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

    AuthorisationRequestNotifier m_onAuthorisationRequestNotifier;
    PresenceChangeNotifier       m_onPresenceChangeNotifier;
#if OPAL_HAS_IM
    ReceivedMessageNotifier      m_onReceivedMessageNotifier;
#endif // OPAL_HAS_IM

    atomic<bool> m_open;
    PDECLARE_MUTEX(m_notificationMutex);
    bool m_temporarilyUnavailable;
    OpalPresenceInfo m_localInfo;
};



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

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

  public:
    ~OpalPresentityWithCommandThread();

    virtual bool Close();

    virtual bool SendCommand(
      OpalPresentityCommand * cmd   
    );

  protected:
    struct WorkItem
    {
      OpalPresentity & m_owner;
      OpalPresentityCommand * m_command;
      WorkItem(OpalPresentityWithCommandThread & owner, OpalPresentityCommand * command);
      ~WorkItem();
      void Work();
    };

    PQueuedThreadPool<WorkItem> m_threadPool;
};


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

    virtual void Process(
      OpalPresentity & presentity
    ) = 0;

    static OpalPresentityCommand * Create(OpalPresentity & presentity, const char * cmdName);
    static PDefaultPFactoryKey MakeKey(const char * className, const char * cmdName);

    typedef uint32_t CmdSeqType;
    CmdSeqType m_sequence;
    bool       m_responseNeeded;
    PURL       m_presentity;
};

#define OPAL_PRESENTITY_COMMAND(command, entity, func) \
  class entity##_##command : public command \
  { \
    public: virtual void Process(OpalPresentity & presentity) { dynamic_cast<entity &>(presentity).func(*this); } \
  }; \
  PFACTORY_CREATE(PFactory<OpalPresentityCommand>, entity##_##command, OpalPresentityCommand::MakeKey(typeid(entity).name(), 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) { }
};


#if OPAL_HAS_IM

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

    OpalIM m_message;
};
#endif // OPAL_HAS_IM



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

template <class cls> __inline cls * OpalPresentity::CreateCommand()
{
  return dynamic_cast<cls *>(OpalPresentityCommand::Create(*this, typeid(cls).name()));
}


#endif // OPAL_HAS_PRESENCE


#endif  // OPAL_IM_PRES_ENT_H