OpalLocalEndPoint Class Reference

#include <localep.h>

Inheritance diagram for OpalLocalEndPoint:

[legend]
Collaboration diagram for OpalLocalEndPoint:
[legend]

Customisation call backs

enum  Synchronicity { e_Synchronous, e_Asynchronous, e_SimulateSyncronous }
PSafePtr< OpalLocalConnectionGetLocalConnectionWithLock (const PString &token, PSafetyMode mode=PSafeReadWrite)
virtual OpalLocalConnectionCreateConnection (OpalCall &call, void *userData, unsigned options, OpalConnection::StringOptions *stringOptions)
virtual bool OnOutgoingSetUp (const OpalLocalConnection &connection)
virtual bool OnOutgoingCall (const OpalLocalConnection &connection)
virtual bool OnIncomingCall (OpalLocalConnection &connection)
virtual bool AlertingIncomingCall (const PString &token, OpalConnection::StringOptions *options=NULL, bool withMedia=false)
virtual bool AcceptIncomingCall (const PString &token, OpalConnection::StringOptions *options=NULL)
virtual bool RejectIncomingCall (const PString &token, const OpalConnection::CallEndReason &reason=OpalConnection::EndedByAnswerDenied)
virtual bool OnUserInput (const OpalLocalConnection &connection, const PString &indication)
virtual bool OnReadMediaFrame (const OpalLocalConnection &connection, const OpalMediaStream &mediaStream, RTP_DataFrame &frame)
virtual bool OnWriteMediaFrame (const OpalLocalConnection &connection, const OpalMediaStream &mediaStream, RTP_DataFrame &frame)
virtual bool OnReadMediaData (const OpalLocalConnection &connection, const OpalMediaStream &mediaStream, void *data, PINDEX size, PINDEX &length)
virtual bool OnWriteMediaData (const OpalLocalConnection &connection, const OpalMediaStream &mediaStream, const void *data, PINDEX length, PINDEX &written)
virtual Synchronicity GetSynchronicity (const OpalMediaFormat &mediaFormat, bool isSource) const
Synchronicity GetDefaultAudioSynchronicity () const
void SetDefaultAudioSynchronicity (Synchronicity sync)
Synchronicity GetDefaultVideoSourceSynchronicity () const
void SetDefaultVideoSourceSynchronicity (Synchronicity sync)
bool IsDeferredAlerting () const
void SetDeferredAlerting (bool defer)
bool IsDeferredAnswer () const
void SetDeferredAnswer (bool defer)

Public Member Functions

Construction
 OpalLocalEndPoint (OpalManager &manager, const char *prefix="local")
 ~OpalLocalEndPoint ()
Overrides from OpalEndPoint
virtual OpalMediaFormatList GetMediaFormats () const
virtual PSafePtr< OpalConnectionMakeConnection (OpalCall &call, const PString &party, void *userData=NULL, unsigned int options=0, OpalConnection::StringOptions *stringOptions=NULL)

Protected Attributes

bool m_deferredAlerting
bool m_deferredAnswer
Synchronicity m_defaultAudioSynchronicity
Synchronicity m_defaultVideoSourceSynchronicity

Detailed Description

Local EndPoint. This class represents an endpoint on the local machine that can receive media via virtual functions.


Member Enumeration Documentation

enum OpalLocalEndPoint::Synchronicity

Indicate the synchronous mode for I/O. This indicates that the OnReadMediaXXX and OnWriteMediaXXX functions will execute blocking to the correct real time synchronisation. If GetSynchronicity() returns e_Synchronous, then, for example, when OnWriteMediaData() is sent 320 bytes of PCM data, it will block for 20 milliseconds.

If GetSynchronicity() returns e_SimulateSyncronous, then the system will try and simulate the correct timing using the operating system sleep function. This is not desirable as this function is notoriously inaccurate, and OPAL does it's best to compensate, but very often there is no other choice.

Note, it is important for the correct oeprating of the jitter buffer that one of the above two modes is used for audio.

If GetSynchronicity() returns e_Asynchronous, then the system will indicate that blocking is not required in any way. For example, when playing video, this is done as fast as data comes in from the network and there is no real time pacing required.

Enumerator:
e_Synchronous  Functions will block for correct real time.
e_Asynchronous  Functions will not block, and do not require any real time handling.
e_SimulateSyncronous  Functions wlll not block, but do require real time handling.


Constructor & Destructor Documentation

OpalLocalEndPoint::OpalLocalEndPoint ( OpalManager manager,
const char *  prefix = "local" 
)

Create a new endpoint.

Parameters:
manager  Manager of all endpoints.
prefix  Prefix for URL style address strings

OpalLocalEndPoint::~OpalLocalEndPoint (  ) 

Destroy endpoint.


Member Function Documentation

virtual bool OpalLocalEndPoint::AcceptIncomingCall ( const PString &  token,
OpalConnection::StringOptions options = NULL 
) [virtual]

Accept the incoming connection. Returns false if the connection token does not correspond to a valid connection.

Parameters:
token  Token of connection to accept call
options  Optional string optiosn to apply

virtual bool OpalLocalEndPoint::AlertingIncomingCall ( const PString &  token,
OpalConnection::StringOptions options = NULL,
bool  withMedia = false 
) [virtual]

Indicate alerting for the incoming connection. Returns false if the connection token does not correspond to a valid connection.

Parameters:
token  Token of connection to indicate alerting
options  Optional string optiosn to apply
withMedia  Indicate media should be started

virtual OpalLocalConnection* OpalLocalEndPoint::CreateConnection ( OpalCall call,
void *  userData,
unsigned  options,
OpalConnection::StringOptions stringOptions 
) [virtual]

Create a connection for the PCSS endpoint. The default implementation is to create a OpalLocalConnection.

Parameters:
call  Owner of connection
userData  Arbitrary data to pass to connection
options  Option bit mask to pass to connection
stringOptions  Options to pass to connection

Synchronicity OpalLocalEndPoint::GetDefaultAudioSynchronicity (  )  const [inline]

Get default synchronous mode for audio sources and sinks.

Synchronicity OpalLocalEndPoint::GetDefaultVideoSourceSynchronicity (  )  const [inline]

Get default synchronous mode for video sources.

PSafePtr<OpalLocalConnection> OpalLocalEndPoint::GetLocalConnectionWithLock ( const PString &  token,
PSafetyMode  mode = PSafeReadWrite 
) [inline]

Find a connection that uses the specified token. This searches the endpoint for the connection that contains the token as provided by functions such as MakeConnection(). If not then it attempts to use the token as a OpalCall token and find a connection of the same class.

Parameters:
token  Token to identify connection
mode  Lock mode

virtual OpalMediaFormatList OpalLocalEndPoint::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 returns the most basic media formats, PCM audio and YUV420P video.

Implements OpalEndPoint.

Reimplemented in OpalIVREndPoint, OpalMixerEndPoint, and OpalFaxEndPoint.

virtual Synchronicity OpalLocalEndPoint::GetSynchronicity ( const OpalMediaFormat mediaFormat,
bool  isSource 
) const [virtual]

Indicate the I/O synchronous mode. See Synchronicity for more details.

Default behaviour returns m_defaultAudioSynchronicity (initially e_Synchronous) when is audio source or sink, m_defaultVideoSourceSynchronicity (initially e_Synchronous) when a video source, e_Asynchronous in all other cases.

Parameters:
mediaFormat  Media format for stream being opened.
isSource  Stream is a a source

bool OpalLocalEndPoint::IsDeferredAlerting (  )  const [inline]

Indicate OnAlerting() is be deferred or immediate.

bool OpalLocalEndPoint::IsDeferredAnswer (  )  const [inline]

Indicate AcceptIncomingCall() execution is be deferred or immediate on OnIncomingCall().

virtual PSafePtr<OpalConnection> OpalLocalEndPoint::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 to pass to conneciton
stringOptions  Options to pass to connection

Implements OpalEndPoint.

Reimplemented in OpalIVREndPoint, and OpalFaxEndPoint.

virtual bool OpalLocalEndPoint::OnIncomingCall ( OpalLocalConnection connection  )  [virtual]

Call back to indicate that there is an incoming call. Note this function should not block or it will impede the operation of the stack.

The default implementation returns true;

Returns:
false is returned the call is aborted with status of EndedByLocalBusy.
Parameters:
connection  Connection having event

Reimplemented in OpalPCSSEndPoint.

virtual bool OpalLocalEndPoint::OnOutgoingCall ( const OpalLocalConnection connection  )  [virtual]

Call back to indicate that remote is ringing. If false is returned the call is aborted.

The default implementation does nothing.

Parameters:
connection  Connection having event

Reimplemented in OpalPCSSEndPoint.

virtual bool OpalLocalEndPoint::OnOutgoingSetUp ( const OpalLocalConnection connection  )  [virtual]

Call back just before remote is contacted. If false is returned the call is aborted with EndedByNoAccept.

The default implementation returns true.

Parameters:
connection  Connection having event

virtual bool OpalLocalEndPoint::OnReadMediaData ( const OpalLocalConnection connection,
const OpalMediaStream mediaStream,
void *  data,
PINDEX  size,
PINDEX &  length 
) [virtual]

Call back to get media data for transmission. If false is returned the media stream will be closed.

Care with the handling of real time is rqeuired, see GetSynchronicity for more details.

The default implementation returns false.

Parameters:
connection  Connection for media
mediaStream  Media stream data is required for
data  Data to send
size  Maximum size of data buffer
length  Number of bytes placed in buffer

virtual bool OpalLocalEndPoint::OnReadMediaFrame ( const OpalLocalConnection connection,
const OpalMediaStream mediaStream,
RTP_DataFrame frame 
) [virtual]

Call back to get media data for transmission. If false is returned then OnReadMediaData() is called.

Care with the handling of real time is rqeuired, see GetSynchronicity for more details.

The default implementation returns false.

Parameters:
connection  Connection for media
mediaStream  Media stream data is required for
frame  RTP frame for data

virtual bool OpalLocalEndPoint::OnUserInput ( const OpalLocalConnection connection,
const PString &  indication 
) [virtual]

Call back to indicate that the remote user has indicated something. If false is returned the call is aborted.

The default implementation does nothing.

Parameters:
connection  Connection having event
indication  User input received

Reimplemented in OpalPCSSEndPoint.

virtual bool OpalLocalEndPoint::OnWriteMediaData ( const OpalLocalConnection connection,
const OpalMediaStream mediaStream,
const void *  data,
PINDEX  length,
PINDEX &  written 
) [virtual]

Call back to handle received media data. If false is returned the media stream will be closed.

Note: For audio media, if data is NULL then that indicates there is no incoming audio available from the jitter buffer. The application should output silence for a time. The written value should still contain the bytes of silence emitted, even though it ewill be larger that length.

Also, it is expected that this function be real time. That is if 320 bytes of PCM-16 are written, this function should take 20ms to execute. If not then the jitter buffer will not operate correctly and audio will not be of high quality.

Care with the handling of real time is rqeuired, see GetSynchronicity for more details.

The default implementation returns false.

Parameters:
connection  Connection for media
mediaStream  Media stream data is required for
data  Data received
length  Amount of data available to write
written  Amount of data written

virtual bool OpalLocalEndPoint::OnWriteMediaFrame ( const OpalLocalConnection connection,
const OpalMediaStream mediaStream,
RTP_DataFrame frame 
) [virtual]

Call back to handle received media data. If false is returned then OnWriteMediaData() is called.

Care with the handling of real time is rqeuired, see GetSynchronicity for more details.

The default implementation returns false.

Parameters:
connection  Connection for media
mediaStream  Media stream data is required for
frame  RTP frame for data

virtual bool OpalLocalEndPoint::RejectIncomingCall ( const PString &  token,
const OpalConnection::CallEndReason reason = OpalConnection::EndedByAnswerDenied 
) [virtual]

Reject the incoming connection. Returns false if the connection token does not correspond to a valid connection.

Parameters:
token  Token of connection to accept call
reason  Reason for rejecting the call

void OpalLocalEndPoint::SetDefaultAudioSynchronicity ( Synchronicity  sync  )  [inline]

Set default synchronous mode for audio sources and sinks.

void OpalLocalEndPoint::SetDefaultVideoSourceSynchronicity ( Synchronicity  sync  )  [inline]

Set default synchronous mode for video sources.

void OpalLocalEndPoint::SetDeferredAlerting ( bool  defer  )  [inline]

Indicate OnAlerting() is be deferred or immediate.

void OpalLocalEndPoint::SetDeferredAnswer ( bool  defer  )  [inline]

Indicate AcceptIncomingCall() execution is be deferred or immediate on OnIncomingCall().


Field Documentation

Synchronicity OpalLocalEndPoint::m_defaultAudioSynchronicity [protected]

Synchronicity OpalLocalEndPoint::m_defaultVideoSourceSynchronicity [protected]

bool OpalLocalEndPoint::m_deferredAlerting [protected]

bool OpalLocalEndPoint::m_deferredAnswer [protected]


The documentation for this class was generated from the following file:
Generated on 21 Jun 2013 for OPAL by  doxygen 1.4.7