OpalPresentity Class Reference

#include <pres_ent.h>

Inheritance diagram for OpalPresentity:


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.
virtual void	OnPresenceChange (const OpalPresenceInfo &info)
void	SetPresenceChangeNotifier (const PresenceChangeNotifier &notifier)
	Set the notifier for the OnPresenceChange() function.
Buddy Lists
typedef std::list< BuddyInfo >	BuddyList
virtual bool	GetBuddyList (BuddyList &buddies)
virtual bool	SetBuddyList (const BuddyList &buddies)
virtual bool	DeleteBuddyList ()
virtual bool	GetBuddy (BuddyInfo &buddy)
virtual bool	SetBuddy (const BuddyInfo &buddy)
virtual bool	DeleteBuddy (const PURL &presentity)
virtual bool	SubscribeBuddyList (bool subscribe=true)
virtual bool	UnsubscribeBuddyList ()
virtual PString	GetID () const
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())
template<class cls>
__inline cls *	CreateCommand ()
virtual bool	SendCommand (OpalPresentityCommand *cmd)
Attributes
Attributes &	GetAttributes ()
const PURL &	GetAOR () const
static const PString &	AuthNameKey ()
	Key for authentication name attribute.
static const PString &	AuthPasswordKey ()
	Key for authentication password attribute.
static const PString &	FullNameKey ()
	Key for full name attribute.
static const PString &	SchemeKey ()
	Key for scheme used attribute.
static const PString &	TimeToLiveKey ()
	Key for Time-To-Live attribute, in seconds for underlying protocol.
Construction
static OpalPresentity *	Create (OpalManager &manager, const PURL &url, const PString &scheme=PString::Empty())
	OpalPresentity ()
	Construct the presentity class.
Public Member Functions
Initialisation
virtual bool	Open ()=0
virtual bool	IsOpen () const =0
virtual bool	Close ()=0
Protected Member Functions
OpalPresentityCommand *	InternalCreateCommand (const char *cmdName)
Protected Attributes
OpalManager *	m_manager
PGloballyUniqueID	m_guid
PURL	m_aor
Attributes	m_attributes
AuthorisationRequestNotifier	m_onAuthorisationRequestNotifier
PresenceChangeNotifier	m_onPresenceChangeNotifier
PMutex	m_notificationMutex
PAtomicInteger::IntegerType	m_idNumber
Data Structures
class	Attributes
struct	AuthorisationRequest
struct	BuddyInfo

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

typedef PNotifierTemplate<const AuthorisationRequest &> OpalPresentity::AuthorisationRequestNotifier

typedef std::list<BuddyInfo> OpalPresentity::BuddyList

typedef PNotifierTemplate<const OpalPresenceInfo &> OpalPresentity::PresenceChangeNotifier

Member Enumeration Documentation

enum OpalPresentity::Authorisation

Authorisation modes for SetPresenceAuthorisation().

Enumerator:

AuthorisationPermitted
AuthorisationDenied
AuthorisationDeniedPolitely
AuthorisationConfirming
AuthorisationRemove
NumAuthorisations

Constructor & Destructor Documentation

OpalPresentity::OpalPresentity ( ) [protected]

Construct the presentity class.

Member Function Documentation

static const PString& OpalPresentity::AuthNameKey ( ) [static]

Key for authentication name attribute.

static const PString& OpalPresentity::AuthPasswordKey ( ) [static]

Key for authentication password attribute.

virtual bool OpalPresentity::Close ( ) [pure virtual]

Close the presentity.

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:

manager	Manager for presentity
url	URL for presence identity
scheme	Overide the url scheme

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.

virtual bool OpalPresentity::DeleteBuddy ( const PURL & presentity ) [virtual]

Delete a buddy to the buddy list.

virtual bool OpalPresentity::DeleteBuddyList ( ) [virtual]

Delete the buddy list.

static const PString& OpalPresentity::FullNameKey ( ) [static]

Key for full name attribute.

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.

Attributes& OpalPresentity::GetAttributes ( ) [inline]

virtual bool OpalPresentity::GetBuddy ( 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.

virtual bool OpalPresentity::GetBuddyList ( BuddyList & buddies ) [virtual]

Get complete buddy list.

Parameters:

buddies

List of buddies

virtual PString OpalPresentity::GetID ( ) const [virtual]

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

virtual bool OpalPresentity::IsOpen ( ) const [pure virtual]

Indicate if the presentity has been successfully opened.

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:

request

Authorisation request information

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:

info

Info on other presentity that changed state

virtual bool OpalPresentity::Open ( ) [pure 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.

static const PString& OpalPresentity::SchemeKey ( ) [static]

Key for scheme used attribute.

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:

cmd

Command to be processed

Reimplemented in OpalPresentityWithCommandThread.

void OpalPresentity::SetAuthorisationRequestNotifier ( const AuthorisationRequestNotifier & notifier )

Set the notifier for the OnAuthorisationRequest() function.

Parameters:

notifier

Notifier to be called by OnAuthorisationRequest()

virtual bool OpalPresentity::SetBuddy ( const BuddyInfo & buddy ) [virtual]

Set/Add a buddy to the buddy list.

virtual bool OpalPresentity::SetBuddyList ( const BuddyList & buddies ) [virtual]

Set complete buddy list.

Parameters:

buddies

List of buddies

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:

state	New state for our presentity
note	Additional note attached to the state change

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:

presentity	Remote presentity to be authorised
authorisation	Authorisation mode

void OpalPresentity::SetPresenceChangeNotifier ( const PresenceChangeNotifier & notifier )

Set the notifier for the OnPresenceChange() function.

Parameters:

notifier

Notifier to be called by OnPresenceChange()

virtual bool OpalPresentity::SubscribeBuddyList ( 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.

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:

presentity	Other presentity to monitor
subscribe	true if to subscribe, else unsubscribe
note	Optional extra note attached to subscription request

static const PString& OpalPresentity::TimeToLiveKey ( ) [static]

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

virtual bool OpalPresentity::UnsubscribeBuddyList ( ) [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.

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:

presentity

Other presentity to monitor