OpalPresentity Class Reference

#include <pres_ent.h>

Inheritance diagram for OpalPresentity:

Data Structures
struct	AuthorisationRequest
struct	BuddyInfo
Public Member Functions
virtual void	SetAOR (const PURL &aor)
void	Internal_SendMessageToCommand (const OpalSendMessageToCommand &cmd)
virtual PString	GetID () const
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
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
	our presentity state
PString	m_localStateNote
	Additional note attached to the.
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)
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< BuddyInfo >	BuddyList
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 ()
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.
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.
Construction

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

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

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

typedef PNotifierTemplate<const OpalIM &> OpalPresentity::ReceivedMessageNotifier

Member Enumeration Documentation

enum OpalPresentity::Authorisation

Authorisation modes for SetPresenceAuthorisation().

Enumerator:

AuthorisationPermitted
AuthorisationDenied
AuthorisationDeniedPolitely
AuthorisationConfirming
AuthorisationRemove
NumAuthorisations

enum OpalPresentity::BuddyStatus

Enumerator:

BuddyStatus_GenericFailure
BuddyStatus_OK
BuddyStatus_SpecifiedBuddyNotFound
BuddyStatus_ListFeatureNotImplemented
BuddyStatus_ListTemporarilyUnavailable
BuddyStatus_ListMayBeIncomplete
BuddyStatus_BadBuddySpecification
BuddyStatus_ListSubscribeFailed
BuddyStatus_AccountNotLoggedIn

Constructor & Destructor Documentation

OpalPresentity::OpalPresentity ( ) [protected]

Construct the presentity class.

OpalPresentity::OpalPresentity ( const OpalPresentity & other ) [protected]

OpalPresentity::~OpalPresentity ( )

Member Function Documentation

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

Key for authentication name attribute.

static const PCaselessString& 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.

References InternalCreateCommand().

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

References BuddyStatus_OK, and DeleteBuddyEx().

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

Delete a buddy to the buddy list.

Referenced by DeleteBuddy().

virtual bool OpalPresentity::DeleteBuddyList ( ) [inline, virtual]

References BuddyStatus_OK, and DeleteBuddyListEx().

virtual BuddyStatus OpalPresentity::DeleteBuddyListEx ( ) [virtual]

Delete the buddy list.

Referenced by DeleteBuddyList().

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.

References m_aor.

virtual PStringArray OpalPresentity::GetAttributeNames ( ) const [pure virtual]

Get all attribute types for this presentity class.

PStringOptions& OpalPresentity::GetAttributes ( ) [inline]

< Get the attributes for this presentity.

Get all attribute names for this presentity class.

References m_attributes.

virtual PStringArray OpalPresentity::GetAttributeTypes ( ) const [pure virtual]

virtual bool OpalPresentity::GetBuddy ( BuddyInfo & buddy ) [inline, virtual]

References BuddyStatus_OK, and 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.

Referenced by GetBuddy().

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

Parameters:

buddies

List of buddies

References BuddyStatus_OK, and GetBuddyListEx().

virtual BuddyStatus OpalPresentity::GetBuddyListEx ( BuddyList & buddies ) [virtual]

Get complete buddy list.

Parameters:

buddies

List of buddies

Referenced by GetBuddyList().

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

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

Get our presence state

void OpalPresentity::Internal_SendMessageToCommand ( const OpalSendMessageToCommand & cmd )

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

Referenced by CreateCommand().

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 void OpalPresentity::OnReceivedMessage ( const OpalIM & message ) [virtual]

Callback when presentity receives a message

Default implementation calls m_onReceivedMessageNotifier.

Parameters:

message

incoming message

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.

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.

virtual bool OpalPresentity::SendMessageTo ( const OpalIM & message ) [virtual]

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.

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 ) [inline, virtual]

References BuddyStatus_OK, and SetBuddyEx().

virtual BuddyStatus OpalPresentity::SetBuddyEx ( const BuddyInfo & buddy ) [virtual]

Set/Add a buddy to the buddy list.

Referenced by SetBuddy().

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

Parameters:

buddies

List of buddies

References BuddyStatus_OK, and SetBuddyListEx().

virtual BuddyStatus OpalPresentity::SetBuddyListEx ( const BuddyList & buddies ) [virtual]

Set complete buddy list.

Parameters:

buddies

List of buddies

Referenced by SetBuddyList().

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

void OpalPresentity::SetReceivedMessageNotifier ( const ReceivedMessageNotifier & notifier )

Set the notifier for the OnPresenceChange() function.

Parameters:

notifier

Notifier to be called by OnReceivedMessage()

virtual bool OpalPresentity::SubscribeBuddyList ( bool subscribe = true ) [inline, virtual]

References BuddyStatus_OK, and 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.

Referenced by SubscribeBuddyList().

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 PCaselessString& OpalPresentity::TimeToLiveKey ( ) [static]

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

virtual bool OpalPresentity::UnsubscribeBuddyList ( ) [inline, virtual]

References BuddyStatus_OK, and 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.

Referenced by UnsubscribeBuddyList().

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