OpalPresentity Class Referenceabstract

`#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)
Initialisation
virtual bool | Open ()
virtual bool | IsOpen () const
virtual bool | Close ()

## 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
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 OpalPresentity * | Create (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< 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 ()

## 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

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

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.

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

inline virtual

Indicate if the presentity has been successfully opened.

References m_open.

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

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

## Field Documentation

PURL OpalPresentity::m_aor

protected

Referenced by GetAOR().

PStringOptions OpalPresentity::m_attributes

protected

PGloballyUniqueID OpalPresentity::m_guid

protected

OpalPresenceInfo::State OpalPresentity::m_localState

protected

our presentity state

PString OpalPresentity::m_localStateNote

protected

Additional note attached to the.

OpalManager* OpalPresentity::m_manager

protected

PMutex OpalPresentity::m_notificationMutex

protected

AuthorisationRequestNotifier OpalPresentity::m_onAuthorisationRequestNotifier

protected

PresenceChangeNotifier OpalPresentity::m_onPresenceChangeNotifier

protected

ReceivedMessageNotifier OpalPresentity::m_onReceivedMessageNotifier

protected

PAtomicBoolean OpalPresentity::m_open

protected

Referenced by IsOpen().

bool OpalPresentity::m_temporarilyUnavailable

protected

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

- pres_ent.h