OPAL  Version 3.10.10
OpalPresentity Class Referenceabstract

#include <pres_ent.h>

Inheritance diagram for OpalPresentity:
OpalPresentityWithCommandThread

Data Structures

struct  AuthorisationRequest
 
struct  BuddyInfo
 

Public Member Functions

virtual void SetAOR (const PURL &aor)
 
void Internal_SendMessageToCommand (const OpalSendMessageToCommand &cmd)
 
Initialisation
virtual bool Open ()
 
virtual bool IsOpen () const
 
virtual bool Close ()
 

Protected Member Functions

OpalPresentityCommandInternalCreateCommand (const char *cmdName)
 

Protected Attributes

OpalManagerm_manager
 
PGloballyUniqueID m_guid
 
PURL m_aor
 
PStringOptions m_attributes
 
AuthorisationRequestNotifier m_onAuthorisationRequestNotifier
 
PresenceChangeNotifier m_onPresenceChangeNotifier
 
ReceivedMessageNotifier m_onReceivedMessageNotifier
 
PAtomicBoolean m_open
 
PMutex m_notificationMutex
 
bool m_temporarilyUnavailable
 
OpalPresenceInfo::State m_localState
 our presentity state More...
 
PString m_localStateNote
 Additional note attached to the. More...
 

Construction

 OpalPresentity ()
 Construct the presentity class. More...
 
 OpalPresentity (const OpalPresentity &other)
 
 ~OpalPresentity ()
 
static OpalPresentityCreate (OpalManager &manager, const PURL &url, const PString &scheme=PString::Empty())
 

Attributes

PStringOptions & GetAttributes ()
 < Get the attributes for this presentity. More...
 
virtual PStringArray GetAttributeNames () const =0
 Get all attribute types for this presentity class. More...
 
virtual PStringArray GetAttributeTypes () const =0
 
const PURL & GetAOR () const
 
static const PCaselessString & AuthNameKey ()
 Key for authentication name attribute. More...
 
static const PCaselessString & AuthPasswordKey ()
 Key for authentication password attribute. More...
 
static const PCaselessString & TimeToLiveKey ()
 Key for Time-To-Live attribute, in seconds for underlying protocol. More...
 

Commands

enum  Authorisation {
  AuthorisationPermitted, AuthorisationDenied, AuthorisationDeniedPolitely, AuthorisationConfirming,
  AuthorisationRemove, NumAuthorisations
}
 Authorisation modes for SetPresenceAuthorisation() More...
 
virtual bool SubscribeToPresence (const PURL &presentity, bool subscribe=true, const PString &note=PString::Empty())
 
virtual bool UnsubscribeFromPresence (const PURL &presentity)
 
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 ()
 
virtual bool SendCommand (OpalPresentityCommand *cmd)
 

Indications (callbacks)

typedef PNotifierTemplate< const AuthorisationRequest & > AuthorisationRequestNotifier
 
typedef PNotifierTemplate< const OpalPresenceInfo & > PresenceChangeNotifier
 
virtual void OnAuthorisationRequest (const AuthorisationRequest &request)
 
void SetAuthorisationRequestNotifier (const AuthorisationRequestNotifier &notifier)
 Set the notifier for the OnAuthorisationRequest() function. More...
 
virtual void OnPresenceChange (const OpalPresenceInfo &info)
 
void SetPresenceChangeNotifier (const PresenceChangeNotifier &notifier)
 Set the notifier for the OnPresenceChange() function. More...
 

Buddy Lists

enum  BuddyStatus {
  BuddyStatus_GenericFailure = -1, BuddyStatus_OK = 0, BuddyStatus_SpecifiedBuddyNotFound, BuddyStatus_ListFeatureNotImplemented,
  BuddyStatus_ListTemporarilyUnavailable, BuddyStatus_ListMayBeIncomplete, BuddyStatus_BadBuddySpecification, BuddyStatus_ListSubscribeFailed,
  BuddyStatus_AccountNotLoggedIn
}
 
typedef std::list< BuddyInfoBuddyList
 
virtual BuddyStatus GetBuddyListEx (BuddyList &buddies)
 
virtual bool GetBuddyList (BuddyList &buddies)
 
virtual BuddyStatus SetBuddyListEx (const BuddyList &buddies)
 
virtual bool SetBuddyList (const BuddyList &buddies)
 
virtual BuddyStatus DeleteBuddyListEx ()
 
virtual bool DeleteBuddyList ()
 
virtual BuddyStatus GetBuddyEx (BuddyInfo &buddy)
 
virtual bool GetBuddy (BuddyInfo &buddy)
 
virtual BuddyStatus SetBuddyEx (const BuddyInfo &buddy)
 
virtual bool SetBuddy (const BuddyInfo &buddy)
 
virtual BuddyStatus DeleteBuddyEx (const PURL &presentity)
 
virtual bool DeleteBuddy (const PURL &presentity)
 
virtual BuddyStatus SubscribeBuddyListEx (PINDEX &successfulCount, bool subscribe=true)
 
virtual bool SubscribeBuddyList (bool subscribe=true)
 
virtual BuddyStatus UnsubscribeBuddyListEx ()
 
virtual bool UnsubscribeBuddyList ()
 

Instant Messaging

typedef PNotifierTemplate< const OpalIM & > ReceivedMessageNotifier
 
virtual bool SendMessageTo (const OpalIM &message)
 
virtual void OnReceivedMessage (const OpalIM &message)
 
void SetReceivedMessageNotifier (const ReceivedMessageNotifier &notifier)
 Set the notifier for the OnPresenceChange() function. More...
 

Detailed Description

Representation of a presence identity. This class contains an abstraction of the functionality for "presence" using a URL string as the "identity". The concrete class depends on the scheme of the identity URL.

The general architecture is that commands will be sent to the preentity concrete class via concrete versions of OpalPresentityCommand class. These may be protocol specific or one of the abstracted versions.

Member Typedef Documentation

◆ AuthorisationRequestNotifier

◆ BuddyList

◆ PresenceChangeNotifier

typedef PNotifierTemplate<const OpalPresenceInfo &> OpalPresentity::PresenceChangeNotifier

◆ ReceivedMessageNotifier

typedef PNotifierTemplate<const OpalIM &> OpalPresentity::ReceivedMessageNotifier

Member Enumeration Documentation

◆ Authorisation

Authorisation modes for SetPresenceAuthorisation()

Enumerator
AuthorisationPermitted 
AuthorisationDenied 
AuthorisationDeniedPolitely 
AuthorisationConfirming 
AuthorisationRemove 
NumAuthorisations 

◆ BuddyStatus

Enumerator
BuddyStatus_GenericFailure 
BuddyStatus_OK 
BuddyStatus_SpecifiedBuddyNotFound 
BuddyStatus_ListFeatureNotImplemented 
BuddyStatus_ListTemporarilyUnavailable 
BuddyStatus_ListMayBeIncomplete 
BuddyStatus_BadBuddySpecification 
BuddyStatus_ListSubscribeFailed 
BuddyStatus_AccountNotLoggedIn 

Constructor & Destructor Documentation

◆ OpalPresentity() [1/2]

OpalPresentity::OpalPresentity ( )
protected

Construct the presentity class.

◆ OpalPresentity() [2/2]

OpalPresentity::OpalPresentity ( const OpalPresentity other)
protected

◆ ~OpalPresentity()

OpalPresentity::~OpalPresentity ( )

Member Function Documentation

◆ AuthNameKey()

static const PCaselessString& OpalPresentity::AuthNameKey ( )
static

Key for authentication name attribute.

◆ AuthPasswordKey()

static const PCaselessString& OpalPresentity::AuthPasswordKey ( )
static

Key for authentication password attribute.

◆ Close()

virtual bool OpalPresentity::Close ( )
virtual

Close the presentity.

◆ Create()

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

Create a concrete class based on the scheme of the URL provided.

Parameters
managerManager for presentity
urlURL for presence identity
schemeOveride the url scheme

◆ CreateCommand()

template<class cls >
__inline cls* OpalPresentity::CreateCommand ( )
inline

Low level function to create a command. As commands have protocol specific implementations, we use a factory to create them.

◆ DeleteBuddy()

virtual bool OpalPresentity::DeleteBuddy ( const PURL &  presentity)
inlinevirtual

◆ DeleteBuddyEx()

virtual BuddyStatus OpalPresentity::DeleteBuddyEx ( const PURL &  presentity)
virtual

Delete a buddy to the buddy list.

◆ DeleteBuddyList()

virtual bool OpalPresentity::DeleteBuddyList ( )
inlinevirtual

◆ DeleteBuddyListEx()

virtual BuddyStatus OpalPresentity::DeleteBuddyListEx ( )
virtual

Delete the buddy list.

◆ GetAOR()

const PURL& OpalPresentity::GetAOR ( ) const
inline

Get the address-of-record for the presentity. This is typically a URL which represents our local identity in the presense system.

◆ GetAttributeNames()

virtual PStringArray OpalPresentity::GetAttributeNames ( ) const
pure virtual

Get all attribute types for this presentity class.

◆ GetAttributes()

PStringOptions& OpalPresentity::GetAttributes ( )
inline

< Get the attributes for this presentity.

Get all attribute names for this presentity class.

◆ GetAttributeTypes()

virtual PStringArray OpalPresentity::GetAttributeTypes ( ) const
pure virtual

◆ GetBuddy()

virtual bool OpalPresentity::GetBuddy ( BuddyInfo buddy)
inlinevirtual

◆ GetBuddyEx()

virtual BuddyStatus OpalPresentity::GetBuddyEx ( BuddyInfo buddy)
virtual

Get a specific buddy from the buddy list. Note the buddy.m_presentity field must be preset to the URI to search the buddy list for.

◆ GetBuddyList()

virtual bool OpalPresentity::GetBuddyList ( BuddyList buddies)
inlinevirtual
Parameters
buddiesList of buddies

◆ GetBuddyListEx()

virtual BuddyStatus OpalPresentity::GetBuddyListEx ( BuddyList buddies)
virtual

Get complete buddy list.

Parameters
buddiesList of buddies

◆ GetLocalPresence()

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

Get our presence state

◆ Internal_SendMessageToCommand()

void OpalPresentity::Internal_SendMessageToCommand ( const OpalSendMessageToCommand cmd)

◆ InternalCreateCommand()

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

◆ IsOpen()

virtual bool OpalPresentity::IsOpen ( ) const
inlinevirtual

Indicate if the presentity has been successfully opened.

◆ OnAuthorisationRequest()

virtual void OpalPresentity::OnAuthorisationRequest ( const AuthorisationRequest request)
virtual

Callback when another presentity requests access to our presence. It is expected that the handler will call SetPresenceAuthorisation with whatever policy is appropriate.

Default implementation calls m_onRequestPresenceNotifier if non-NULL otherwise will authorise the request.

Parameters
requestAuthorisation request information

◆ OnPresenceChange()

virtual void OpalPresentity::OnPresenceChange ( const OpalPresenceInfo info)
virtual

Callback when presentity has changed its state. Note if the m_entity and m_target fields of the OpalPresenceInfo structure are the same, then this indicates that the local presentity itself has successfully "registered" itself with the presence agent server.

Default implementation calls m_onPresenceChangeNotifier.

Parameters
infoInfo on other presentity that changed state

◆ OnReceivedMessage()

virtual void OpalPresentity::OnReceivedMessage ( const OpalIM message)
virtual

Callback when presentity receives a message

Default implementation calls m_onReceivedMessageNotifier.

Parameters
messageincoming message

◆ Open()

virtual bool OpalPresentity::Open ( )
virtual

Open the presentity handler. This will perform whatever is required to allow this presentity to access servers etc for the underlying protocol. It may start open network channels, start threads etc.

Note that a return value of true does not necessarily mean that the presentity has successfully been indicated as "present" on the server only that the underlying system can do so at some time.

◆ SendCommand()

virtual bool OpalPresentity::SendCommand ( OpalPresentityCommand cmd)
virtual

Lowlevel function to send a command to the presentity handler. All commands are asynchronous. They will usually initiate an action for which an indication (callback) will give a result.

Note that the command is typically created by the CreateCommand() function and is subsequently deleted by this function.

Returns true if the command was queued. Note that this does not mean the command succeeded, only that the underlying protocol is processing commands.

Parameters
cmdCommand to be processed

Reimplemented in OpalPresentityWithCommandThread.

◆ SendMessageTo()

virtual bool OpalPresentity::SendMessageTo ( const OpalIM message)
virtual

◆ SetAOR()

virtual void OpalPresentity::SetAOR ( const PURL &  aor)
virtual

Used to set the AOR after the presentity is created This override allows the descendant class to convert the internal URL into a real AOR, usually by changing the scheme.

◆ SetAuthorisationRequestNotifier()

void OpalPresentity::SetAuthorisationRequestNotifier ( const AuthorisationRequestNotifier notifier)

Set the notifier for the OnAuthorisationRequest() function.

Parameters
notifierNotifier to be called by OnAuthorisationRequest()

◆ SetBuddy()

virtual bool OpalPresentity::SetBuddy ( const BuddyInfo buddy)
inlinevirtual

◆ SetBuddyEx()

virtual BuddyStatus OpalPresentity::SetBuddyEx ( const BuddyInfo buddy)
virtual

Set/Add a buddy to the buddy list.

◆ SetBuddyList()

virtual bool OpalPresentity::SetBuddyList ( const BuddyList buddies)
inlinevirtual
Parameters
buddiesList of buddies

◆ SetBuddyListEx()

virtual BuddyStatus OpalPresentity::SetBuddyListEx ( const BuddyList buddies)
virtual

Set complete buddy list.

Parameters
buddiesList of buddies

◆ SetLocalPresence()

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

Set our presence state. This function is a wrapper and the OpalSetLocalPresenceCommand command.

Returns true if the command was queued. Note that this does not mean the command succeeded, only that the underlying protocol is capabable of the action.

Parameters
stateNew state for our presentity
noteAdditional note attached to the state change

◆ SetPresenceAuthorisation()

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

Called to allow/deny another presentity access to our presence information.

This function is a wrapper and the OpalAuthorisationRequestCommand command.

Returns true if the command was queued. Note that this does not mean the command succeeded, only that the underlying protocol is capabable of the action.

Parameters
presentityRemote presentity to be authorised
authorisationAuthorisation mode

◆ SetPresenceChangeNotifier()

void OpalPresentity::SetPresenceChangeNotifier ( const PresenceChangeNotifier notifier)

Set the notifier for the OnPresenceChange() function.

Parameters
notifierNotifier to be called by OnPresenceChange()

◆ SetReceivedMessageNotifier()

void OpalPresentity::SetReceivedMessageNotifier ( const ReceivedMessageNotifier notifier)

Set the notifier for the OnPresenceChange() function.

Parameters
notifierNotifier to be called by OnReceivedMessage()

◆ SubscribeBuddyList()

virtual bool OpalPresentity::SubscribeBuddyList ( bool  subscribe = true)
inlinevirtual

◆ SubscribeBuddyListEx()

virtual BuddyStatus OpalPresentity::SubscribeBuddyListEx ( PINDEX &  successfulCount,
bool  subscribe = true 
)
virtual

Subscribe to buddy list. Send a subscription for the presence of every presentity in the current buddy list. This might cause multiple calls to SubscribeToPresence() or if the underlying protocol allows a single call for all.

◆ SubscribeToPresence()

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

Subscribe to presence state of another presentity. This function is a wrapper and the OpalSubscribeToPresenceCommand command.

Returns true if the command was queued. Note that this does not mean the command succeeded, only that the underlying protocol is capabable of the action.

Parameters
presentityOther presentity to monitor
subscribetrue if to subscribe, else unsubscribe
noteOptional extra note attached to subscription request

◆ TimeToLiveKey()

static const PCaselessString& OpalPresentity::TimeToLiveKey ( )
static

Key for Time-To-Live attribute, in seconds for underlying protocol.

◆ UnsubscribeBuddyList()

virtual bool OpalPresentity::UnsubscribeBuddyList ( )
inlinevirtual

◆ UnsubscribeBuddyListEx()

virtual BuddyStatus OpalPresentity::UnsubscribeBuddyListEx ( )
virtual

Unsubscribe to buddy list. Send an unsubscription for the presence of every presentity in the current buddy list. This might cause multiple calls to UnsubscribeFromPresence() or if the underlying protocol allows a single call for all.

◆ UnsubscribeFromPresence()

virtual bool OpalPresentity::UnsubscribeFromPresence ( const PURL &  presentity)
virtual

Unsubscribe to presence state of another presentity. This function is a wrapper and the OpalSubscribeToPresenceCommand command.

Returns true if the command was queued. Note that this does not mean the command succeeded, only that the underlying protocol is capabable of the action.

Parameters
presentityOther presentity to monitor

Field Documentation

◆ m_aor

PURL OpalPresentity::m_aor
protected

◆ m_attributes

PStringOptions OpalPresentity::m_attributes
protected

◆ m_guid

PGloballyUniqueID OpalPresentity::m_guid
protected

◆ m_localState

OpalPresenceInfo::State OpalPresentity::m_localState
protected

our presentity state

◆ m_localStateNote

PString OpalPresentity::m_localStateNote
protected

Additional note attached to the.

◆ m_manager

OpalManager* OpalPresentity::m_manager
protected

◆ m_notificationMutex

PMutex OpalPresentity::m_notificationMutex
protected

◆ m_onAuthorisationRequestNotifier

AuthorisationRequestNotifier OpalPresentity::m_onAuthorisationRequestNotifier
protected

◆ m_onPresenceChangeNotifier

PresenceChangeNotifier OpalPresentity::m_onPresenceChangeNotifier
protected

◆ m_onReceivedMessageNotifier

ReceivedMessageNotifier OpalPresentity::m_onReceivedMessageNotifier
protected

◆ m_open

PAtomicBoolean OpalPresentity::m_open
protected

◆ m_temporarilyUnavailable

bool OpalPresentity::m_temporarilyUnavailable
protected

The documentation for this class was generated from the following file: