# OpalIMEndPoint Class Reference

`#include <im_ep.h>`

Inheritance diagram for OpalIMEndPoint:

[legend]
Collaboration diagram for OpalIMEndPoint:
[legend]

## Conversation notification

typedef PNotifierTemplate< OpalIMContext::ConversationInfo > | ConversationNotifier
| Type for converstaion notifiers.
virtual void | OnConversation (const OpalIMContext::ConversationInfo &info)
void | AddNotifier (const ConversationNotifier &notifier, const PString &scheme)
bool | RemoveNotifier (const ConversationNotifier &notifier, const PString &scheme)

## Public Member Functions

OpalIMContext::MessageDisposition | OnRawMessageReceived (OpalIM &message, OpalConnection *connnection, PString &errorInfo)
OpalManager & | GetManager () const
Construction
| OpalIMEndPoint (OpalManager &manager)
| ~OpalIMEndPoint ()
Overrides from OpalEndPoint
virtual PSafePtr< OpalConnection > | MakeConnection (OpalCall &call, const PString &party, void *userData=NULL, unsigned int options=0, OpalConnection::StringOptions *stringOptions=NULL)
virtual OpalMediaFormatList | GetMediaFormats () const
virtual PBoolean | GarbageCollection ()
virtual void | ShutDown ()
Context management
PSafePtr< OpalIMContext > | CreateContext (const PURL &localURL, const PURL &remoteURL, const char *scheme=NULL)
PSafePtr< OpalIMContext > | CreateContext (OpalCall &call)
void | RemoveContext (OpalIMContext *context, bool byRemote)
PSafePtr< OpalIMContext > | FindContextByIdWithLock (const PString &key, PSafetyMode mode=PSafeReadWrite)
PSafePtr< OpalIMContext > | FindContextByNamesWithLock (const PURL &local, const PURL &remote, PSafetyMode mode=PSafeReadWrite)
PSafePtr< OpalIMContext > | FindContextForMessageWithLock (OpalIM &im, OpalConnection *conn=NULL)

## Static Public Member Functions

static const PCaselessString & | Prefix ()

## Protected Types

typedef PSafeDictionary< PString, OpalIMContext > | ContextsByConversationId
typedef std::multimap< PString, PString > | ContextsByNames
typedef std::multimap< PString, ConversationNotifier > | ConversationMap

## Protected Member Functions

PSafePtr< OpalIMContext > | InternalCreateContext (const PURL &localURL, const PURL &remoteURL, const char *scheme, bool byRemote, OpalCall *call, const char *conversationID)

## Protected Attributes

OpalManager & | m_manager
ContextsByConversationId | m_contextsByConversationId
PMutex | m_contextsByNamesMutex
ContextsByNames | m_contextsByNames
PMutex | m_notifierMutex
ConversationMap | m_notifiers
PTime | m_lastGarbageCollection
bool | m_deleting

## Detailed Description

Endpoint for IM connections.

## Member Typedef Documentation

typedef PSafeDictionary<PString, OpalIMContext> OpalIMEndPoint::ContextsByConversationId `[protected]`

typedef std::multimap<PString, PString> OpalIMEndPoint::ContextsByNames `[protected]`

typedef std::multimap<PString, ConversationNotifier> OpalIMEndPoint::ConversationMap `[protected]`

typedef PNotifierTemplate<OpalIMContext::ConversationInfo> OpalIMEndPoint::ConversationNotifier

Type for converstaion notifiers.

## Constructor & Destructor Documentation

OpalIMEndPoint::OpalIMEndPoint | ( | OpalManager & | manager | ) |

OpalIMEndPoint::~OpalIMEndPoint | ( |  | ) |

## Member Function Documentation

void OpalIMEndPoint::AddNotifier | ( | const ConversationNotifier & | notifier,
|  | const PString & | scheme |
| ) |  |  |

Set the notifier for the OnConversation() function. The notifier can be called only for when a specific scheme is being used. If `scheme` is "*" then all scemes will call that notifier.

More than one notifier can be applied and all are called.

Parameters:

  notifier | New notifier to add
  scheme | Scheme to be notified about

PSafePtr<OpalIMContext> OpalIMEndPoint::CreateContext | ( | OpalCall & | call | ) |

Create a Instant Messaging context based on an existing call.

PSafePtr<OpalIMContext> OpalIMEndPoint::CreateContext | ( | const PURL & | localURL,
|  | const PURL & | remoteURL,
|  | const char * | scheme = `NULL` |
| ) |  |  | `[inline]`

Create a Instant Messaging context based on URL scheme. This uses a factory to create an approriate concrete type for the protocol indicated by the scheme of the `remoteURL`.

The `localURL` may be empty and will be derived from the `remoteURL` and the default user name from the manager.

Parameters:

  localURL | Local URL for conversation
  remoteURL | Remote URL for conversation
  scheme | Scheme to use, default to remoteURL.GetScheme()

PSafePtr<OpalIMContext> OpalIMEndPoint::FindContextByIdWithLock | ( | const PString & | key,
|  | PSafetyMode | mode = `PSafeReadWrite` |
| ) |  |  |

Find a context given a key. Generally only used internally.

PSafePtr<OpalIMContext> OpalIMEndPoint::FindContextByNamesWithLock | ( | const PURL & | local,
|  | const PURL & | remote,
|  | PSafetyMode | mode = `PSafeReadWrite` |
| ) |  |  |

Find a context given a from/to addresses. Generally only used internally.

PSafePtr<OpalIMContext> OpalIMEndPoint::FindContextForMessageWithLock | ( | OpalIM & | im,
|  | OpalConnection * | conn = `NULL` |
| ) |  |  |

Find a context given a message. Generally only used internally.

virtual PBoolean OpalIMEndPoint::GarbageCollection | ( |  | ) | `[virtual]`

Look for old conversations and remove them. Generally only used internally. This will call notifiers indicating converstaion end.

Reimplemented from OpalEndPoint.

OpalManager& OpalIMEndPoint::GetManager | ( |  | ) | const`[inline]`

Get the manager for this endpoint.

Reimplemented from OpalEndPoint.

virtual OpalMediaFormatList OpalIMEndPoint::GetMediaFormats | ( |  | ) | const`[virtual]`

Get the data formats this endpoint is capable of operating. This provides a list of media data format names that may be used by an OpalMediaStream may be created by a connection from this endpoint.

Note that a specific connection may not actually support all of the media formats returned here, but should return no more.

The default behaviour is pure.

Implements OpalEndPoint.

PSafePtr<OpalIMContext> OpalIMEndPoint::InternalCreateContext | ( | const PURL & | localURL,
|  | const PURL & | remoteURL,
|  | const char * | scheme,
|  | bool | byRemote,
|  | OpalCall * | call,
|  | const char * | conversationID |
| ) |  |  | `[protected]`

virtual PSafePtr<OpalConnection> OpalIMEndPoint::MakeConnection | ( | OpalCall & | call,
|  | const PString & | party,
|  | void * | userData = `NULL`,
|  | unsigned int | options = `0`,
|  | OpalConnection::StringOptions * | stringOptions = `NULL` |
| ) |  |  | `[virtual]`

Set up a connection to a remote party. This is called from the OpalManager::MakeConnection() function once it has determined that this is the endpoint for the protocol.

The general form for this party parameter is:

[proto:][alias@][transport$]address[:port]

where the various fields will have meanings specific to the endpoint type. For example, with H.323 it could be "h323:Fred@site.com" which indicates a user Fred at gatekeeper size.com. Whereas for the PSTN endpoint it could be "pstn:5551234" which is to call 5551234 on the first available PSTN line.

The proto field is optional when passed to a specific endpoint. If it is present, however, it must agree with the endpoints protocol name or false is returned.

This function usually returns almost immediately with the connection continuing to occur in a new background thread.

If false is returned then the connection could not be established. For example if a PSTN endpoint is used and the assiciated line is engaged then it may return immediately. Returning a non-NULL value does not mean that the connection will succeed, only that an attempt is being made.

The default behaviour is pure.

Parameters:

  call | Owner of connection
  party | Remote party to call
  userData | Arbitrary data to pass to connection
  options | Options bit mask to pass to conneciton
  stringOptions | Options to pass to connection

Implements OpalEndPoint.

virtual void OpalIMEndPoint::OnConversation | ( | const OpalIMContext::ConversationInfo & | info | ) | `[virtual]`

Called when a context state changes, e.g. openign or closing. Default implementation calls the notifier, if set. If no notifier is set, then the OpalManager::OnConversation() function is called.

OpalIMContext::MessageDisposition OpalIMEndPoint::OnRawMessageReceived | ( | OpalIM & | message,
|  | OpalConnection * | connnection,
|  | PString & | errorInfo |
| ) |  |  |

static const PCaselessString& OpalIMEndPoint::Prefix | ( |  | ) | `[static]`

void OpalIMEndPoint::RemoveContext | ( | OpalIMContext * | context,
|  | bool | byRemote |
| ) |  |  |

Remove a new context. Generally only used internally. This will call notifiers indicating converstaion end.

bool OpalIMEndPoint::RemoveNotifier | ( | const ConversationNotifier & | notifier,
|  | const PString & | scheme |
| ) |  |  |

Remove notifier for the OnConversation() function.

virtual void OpalIMEndPoint::ShutDown | ( |  | ) | `[virtual]`

Shut down all conversations.

Reimplemented from OpalEndPoint.

## Field Documentation

ContextsByConversationId OpalIMEndPoint::m_contextsByConversationId `[protected]`

ContextsByNames OpalIMEndPoint::m_contextsByNames `[protected]`

PMutex OpalIMEndPoint::m_contextsByNamesMutex `[protected]`

bool OpalIMEndPoint::m_deleting `[protected]`

PTime OpalIMEndPoint::m_lastGarbageCollection `[protected]`

OpalManager& OpalIMEndPoint::m_manager `[protected]`

PMutex OpalIMEndPoint::m_notifierMutex `[protected]`

ConversationMap OpalIMEndPoint::m_notifiers `[protected]`

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

- im_ep.h