#include <lid.h>

Inherits PObject.

Collaboration diagram for OpalLine:

Public Member Functions
Construction
	OpalLine (OpalLineInterfaceDevice &device, unsigned lineNumber, const char *userToken=NULL)

Overrides from PObject
void	PrintOn (ostream &strm) const

Basic operations
virtual PBoolean	IsTerminal ()

virtual PBoolean	IsPresent (PBoolean force=false)

virtual PBoolean	IsOffHook ()

virtual PBoolean	SetOffHook ()

virtual PBoolean	SetOnHook ()

virtual PBoolean	HookFlash (unsigned flashTime=200)

virtual PBoolean	HasHookFlash ()

virtual PBoolean	IsRinging (DWORD *cadence=NULL)

virtual unsigned	GetRingCount (DWORD *cadence=NULL)

virtual PBoolean	Ring (PINDEX nCadence, const unsigned *pattern=NULL, unsigned frequency=400)

virtual PBoolean	SetConnected ()

virtual PBoolean	IsConnected ()

virtual PBoolean	IsDisconnected ()

virtual PBoolean	SetReadFormat (const OpalMediaFormat &mediaFormat)

virtual PBoolean	SetWriteFormat (const OpalMediaFormat &mediaFormat)

virtual OpalMediaFormat	GetReadFormat ()

virtual OpalMediaFormat	GetWriteFormat ()

virtual PBoolean	StopReading ()

virtual PBoolean	StopWriting ()

virtual PBoolean	SetReadFrameSize (PINDEX frameSize)

virtual PBoolean	SetWriteFrameSize (PINDEX frameSize)

virtual PINDEX	GetReadFrameSize ()

virtual PINDEX	GetWriteFrameSize ()

virtual PBoolean	ReadFrame (void *buf, PINDEX &count)

virtual PBoolean	WriteFrame (const void *buf, PINDEX count, PINDEX &written)

virtual PBoolean	ReadBlock (void *buf, PINDEX count)

virtual PBoolean	WriteBlock (const void *buf, PINDEX count)

virtual unsigned	GetAverageSignalLevel (PBoolean playback)

virtual PBoolean	EnableAudio (PBoolean enable=true)

PBoolean	DisableAudio ()

virtual PBoolean	IsAudioEnabled () const

virtual PBoolean	SetRecordVolume (unsigned volume)

virtual PBoolean	SetPlayVolume (unsigned volume)

virtual PBoolean	GetRecordVolume (unsigned &volume)

virtual PBoolean	GetPlayVolume (unsigned &volume)

virtual OpalLineInterfaceDevice::AECLevels	GetAEC () const

virtual PBoolean	SetAEC (OpalLineInterfaceDevice::AECLevels level)

virtual PBoolean	GetVAD () const

virtual PBoolean	SetVAD (PBoolean enable)

virtual PBoolean	GetCallerID (PString &idString, PBoolean full=false)

virtual PBoolean	SetCallerID (const PString &idString)

virtual PBoolean	SendVisualMessageWaitingIndicator (PBoolean on)

virtual PBoolean	PlayDTMF (const char *digits, DWORD onTime=OpalLineInterfaceDevice::DefaultDTMFOnTime, DWORD offTime=OpalLineInterfaceDevice::DefaultDTMFOffTime)

virtual char	ReadDTMF ()

virtual PBoolean	GetRemoveDTMF ()

virtual PBoolean	SetRemoveDTMF (PBoolean removeTones)

virtual OpalLineInterfaceDevice::CallProgressTones	IsToneDetected ()

virtual OpalLineInterfaceDevice::CallProgressTones	WaitForToneDetect (unsigned timeout=3000)

virtual PBoolean	WaitForTone (OpalLineInterfaceDevice::CallProgressTones tone, unsigned timeout=3000)

virtual PBoolean	PlayTone (OpalLineInterfaceDevice::CallProgressTones tone)

virtual PBoolean	IsTonePlaying ()

virtual PBoolean	StopTone ()

virtual OpalLineInterfaceDevice::CallProgressTones	DialOut (const PString &number, const OpalLineInterfaceDevice::DialParams &params=OpalLineInterfaceDevice::DialParams())

Member variable access
OpalLineInterfaceDevice &	GetDevice () const

unsigned	GetLineNumber () const

PString	GetToken () const

void	SetToken (const PString &t)

Protected Attributes
OpalLineInterfaceDevice &	device

unsigned	lineNumber

PString	token

PTimeInterval	ringStoppedTime

PTimeInterval	ringInterCadenceTime

PTimeInterval	ringTick

unsigned	ringCount

bool	lastRingState

Detailed Description

This class describes the LID based codec capability.

Constructor & Destructor Documentation

OpalLine::OpalLine	(	OpalLineInterfaceDevice &	device,
		unsigned	lineNumber,
		const char *	userToken = `NULL`
	)

Create a new telephone line.

Parameters

device	Device to make connection with
lineNumber	number of line on LID
userToken	Unique token string for line

Member Function Documentation

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::DialOut	(	const PString &	number,
		const OpalLineInterfaceDevice::DialParams &	params = `OpalLineInterfaceDevice::DialParams()`
	)

inlinevirtual

Dial a number on network line. The takes the line off hook, waits for dial tone, and transmits the specified number as DTMF tones.

If the requireTones flag is true the call is aborted of the call progress tones are not detected. Otherwise the call proceeds with short delays while it tries to detect the call progress tones.

The return code indicates the following: DialTone No dial tone detected RingTone Dial was successful BusyTone The remote phone was busy ClearTone Dial failed (usually means rang out) NoTone There was an internal error making the call

Parameters

number	Number to dial
params	Optional parameters for dial out.

References OpalLineInterfaceDevice::DialOut().

PBoolean OpalLine::DisableAudio ( )

inline

Disable audio for the line.

References EnableAudio().

virtual PBoolean OpalLine::EnableAudio ( PBoolean enable = true )

inlinevirtual

Enable audio for the line.

References OpalLineInterfaceDevice::EnableAudio().

Referenced by DisableAudio().

virtual OpalLineInterfaceDevice::AECLevels OpalLine::GetAEC ( ) const

inlinevirtual

Get acoustic echo cancellation. Note, not all devices may support this function.

References OpalLineInterfaceDevice::GetAEC().

virtual unsigned OpalLine::GetAverageSignalLevel ( PBoolean playback )

inlinevirtual

Get average signal level in last frame.

Parameters

playback Get average playback or record level.

References OpalLineInterfaceDevice::GetAverageSignalLevel().

virtual PBoolean OpalLine::GetCallerID	(	PString &	idString,
		PBoolean	full = `false`
	)

inlinevirtual

Get Caller ID from the last incoming ring. The idString parameter is either simply the "number" field of the caller ID data, or if full is true, all of the fields in the caller ID data.

The full data of the caller ID string consists fields separated by tab characters ('\t'), the first three are always the Calling Line Identity (CLI or calling number), the date and the Calling Line Name field. Other fields may follow and are the of the form name=value. The values are LID dependent.

A false is returned if there is no Caller ID information available, e.g. if no ring has occurred.

Parameters

idString	ID string returned
full	Get full information in idString

References OpalLineInterfaceDevice::GetCallerID().

OpalLineInterfaceDevice& OpalLine::GetDevice ( ) const

inline

Get the device this line is on.

References device.

unsigned OpalLine::GetLineNumber ( ) const

inline

Get the number of the line on the device.

References lineNumber.

virtual PBoolean OpalLine::GetPlayVolume ( unsigned & volume )

inlinevirtual

Set volume level for playing. A value of 100 is the maximum volume possible for the hardware. A value of 0 is the minimum volume possible for the hardware.

Parameters

volume Volume level from 0 to 100%

References OpalLineInterfaceDevice::GetPlayVolume().

virtual OpalMediaFormat OpalLine::GetReadFormat ( )

inlinevirtual

Get the media format (codec) for reading on the specified line.

References OpalLineInterfaceDevice::GetReadFormat().

virtual PINDEX OpalLine::GetReadFrameSize ( )

inlinevirtual

Get the read frame size in bytes. All calls to ReadFrame() will return this number of bytes.

References OpalLineInterfaceDevice::GetReadFrameSize().

virtual PBoolean OpalLine::GetRecordVolume ( unsigned & volume )

inlinevirtual

Get volume level for recording. A value of 100 is the maximum volume possible for the hardware. A value of 0 is the minimum volume possible for the hardware.

Parameters

volume Volume level from 0 to 100%

References OpalLineInterfaceDevice::GetRecordVolume().

virtual PBoolean OpalLine::GetRemoveDTMF ( )

inlinevirtual

Get DTMF removal mode. When set in this mode the DTMF tones detected are removed from the encoded data stream as returned by ReadFrame().

References OpalLineInterfaceDevice::GetRemoveDTMF().

virtual unsigned OpalLine::GetRingCount ( DWORD * cadence = NULL )

virtual

Get the number of rings. If the line is ringing then

Parameters

cadence Cadence of incoming ring

PString OpalLine::GetToken ( ) const

inline

Get the token to uniquely identify this line.

References token.

virtual PBoolean OpalLine::GetVAD ( ) const

inlinevirtual

Get voice activity detection. Note, not all devices, or selected codecs, may support this function.

References OpalLineInterfaceDevice::GetVAD().

virtual OpalMediaFormat OpalLine::GetWriteFormat ( )

inlinevirtual

Get the media format (codec) for writing on the specified line.

References OpalLineInterfaceDevice::GetWriteFormat().

virtual PINDEX OpalLine::GetWriteFrameSize ( )

inlinevirtual

Get the write frame size in bytes. All calls to WriteFrame() must be this number of bytes.

References OpalLineInterfaceDevice::GetWriteFrameSize().

virtual PBoolean OpalLine::HasHookFlash ( )

inlinevirtual

Return true if a hook flash has been detected

References OpalLineInterfaceDevice::HasHookFlash().

virtual PBoolean OpalLine::HookFlash ( unsigned flashTime = 200 )

inlinevirtual

Set the hook state off then straight back on again. This will only operate if the line is currently off hook.

Parameters

flashTime Time for hook flash in milliseconds

References OpalLineInterfaceDevice::HookFlash().

virtual PBoolean OpalLine::IsAudioEnabled ( ) const

inlinevirtual

Determine if audio is ebabled for the line.

References OpalLineInterfaceDevice::IsAudioEnabled().

virtual PBoolean OpalLine::IsConnected ( )

inlinevirtual

Determine if remote has answered call on line. This uses the hardware (and country) dependent means for determining if the remote end of a PSTN connection has answered. Typically this is a "polarity reversal" but other techniques may be used.

For a POTS port this is equivalent to IsLineOffHook().

References OpalLineInterfaceDevice::IsLineConnected().

virtual PBoolean OpalLine::IsDisconnected ( )

inlinevirtual

Determine if line has been disconnected from a call. This uses the hardware (and country) dependent means for determining

References OpalLineInterfaceDevice::IsLineDisconnected().

virtual PBoolean OpalLine::IsOffHook ( )

inlinevirtual

Determine if line is currently off hook. This function implies that the state is debounced and that a return value of true indicates that the phone is really off hook. That is hook flashes and winks are masked out.

References OpalLineInterfaceDevice::IsLineOffHook().

virtual PBoolean OpalLine::IsPresent ( PBoolean force = false )

inlinevirtual

Determine if a physical line is present on the logical line.

Parameters

force Force test, do not optimise

References OpalLineInterfaceDevice::IsLinePresent().

virtual PBoolean OpalLine::IsRinging ( DWORD * cadence = NULL )

virtual

Determine if line is ringing. This function implies that the state is "debounced" and that a return value of true indicates that the phone is still ringing and it is not simply a pause in the ring cadence.

If cadence is not NULL then it is set with the bit pattern for the incoming ringing. Note that in this case the funtion may take a full sequence to return. If it is NULL it can be assumed that the function will return quickly.

Parameters

cadence Cadence of incoming ring

virtual PBoolean OpalLine::IsTerminal ( )

inlinevirtual

Get the type of the line. A "terminal" line is one where a call may terminate. For example a POTS line with a standard telephone handset on it would be a terminal line. The alternative is a "network" line, that is one connected to switched network eg the standard PSTN.

References OpalLineInterfaceDevice::IsLineTerminal().

Referenced by OpalLineConnection::IsNetworkConnection().

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::IsToneDetected ( )

inlinevirtual

See if any tone is detected.

References OpalLineInterfaceDevice::IsToneDetected().

virtual PBoolean OpalLine::IsTonePlaying ( )

inlinevirtual

Determine if a tone is still playing

References OpalLineInterfaceDevice::IsTonePlaying().

virtual PBoolean OpalLine::PlayDTMF	(	const char *	digits,
		DWORD	onTime = `OpalLineInterfaceDevice::DefaultDTMFOnTime`,
		DWORD	offTime = `OpalLineInterfaceDevice::DefaultDTMFOffTime`
	)

inlinevirtual

Play a DTMF digit. Any characters that are not in the set 0-9, A-D, * or # will be ignored.

Parameters

digits	DTMF digits to be played
onTime	Number of milliseconds to play each DTMF digit
offTime	Number of milliseconds between digits

References OpalLineInterfaceDevice::PlayDTMF().

virtual PBoolean OpalLine::PlayTone ( OpalLineInterfaceDevice::CallProgressTones tone )

inlinevirtual

Play a tone.

Parameters

tone	Tone to be played

References OpalLineInterfaceDevice::PlayTone().

void OpalLine::PrintOn ( ostream & strm ) const

Standard stream print function. The PObject class has a << operator defined that calls this function polymorphically.

Parameters

strm	Stream to output text representation

virtual PBoolean OpalLine::ReadBlock	(	void *	buf,
		PINDEX	count
	)

inlinevirtual

High level read of audio data from the device. This version will allow non-integral number of frames to be read.

Parameters

buf	Pointer to a block of memory to receive the read bytes.
count	Count of bytes to read.

References OpalLineInterfaceDevice::ReadBlock().

virtual char OpalLine::ReadDTMF ( )

inlinevirtual

Read a DTMF digit detected. This may be characters from the set 0-9, A-D, * or #. A null ('\0') character indicates that there are no tones in the queue. Characters E through P indicate the following tones:

E = 800 F = 1000 G = 1250 H = 950 I = 1100 J = 1400 K = 1500 L = 1600 M = 1800 N = 2100 O = 1300 P = 2450

References OpalLineInterfaceDevice::ReadDTMF().

virtual PBoolean OpalLine::ReadFrame	(	void *	buf,
		PINDEX &	count
	)

inlinevirtual

Low level read of a frame from the device.

Parameters

buf	Pointer to a block of memory to receive data.
count	Number of bytes read, <= GetReadFrameSize()

References OpalLineInterfaceDevice::ReadFrame().

virtual PBoolean OpalLine::Ring	(	PINDEX	nCadence,
		const unsigned *	pattern = `NULL`,
		unsigned	frequency = `400`
	)

inlinevirtual

Begin ringing local phone set with specified cadence. If nCadence is zero then stops ringing.

Note that this may not be possible on a given line, for example on a PSTN line the ring state is determined by external hardware and cannot be changed by the software.

Also note that the cadence may be ignored by particular hardware driver so that only the zero or non-zero values are significant.

The ring pattern is an array of millisecond times for on and off parts of the cadence. Thus the Australian ring cadence would be represented by the array unsigned AusRing[] = { 400, 200, 400, 2000 }

If the nCadence in non-zero and the pattern parameter is NULL, then the standard ring pattern for the selected country is used.

Parameters

nCadence	Number of entries in cadence array
pattern	Ring pattern times
frequency	Frequency of ring (if relevant)

References OpalLineInterfaceDevice::RingLine().

virtual PBoolean OpalLine::SendVisualMessageWaitingIndicator ( PBoolean on )

inlinevirtual

Send a Visual Message Waiting Indicator

References OpalLineInterfaceDevice::SendVisualMessageWaitingIndicator().

virtual PBoolean OpalLine::SetAEC ( OpalLineInterfaceDevice::AECLevels level )

inlinevirtual

Set acoustic echo cancellation. Note, not all devices may support this function.

Parameters

level AEC level

References OpalLineInterfaceDevice::SetAEC().

virtual PBoolean OpalLine::SetCallerID ( const PString & idString )

inlinevirtual

Set Caller ID information. The idString must be as a minimum a number fields for the Calling Line Identity.

The full data of the caller ID string consists fields separated by tab characters ('\t'), the first three are always the Calling Line Identity (CLI or calling number), the date and the Calling Line Name field. Other fields may follow and are the of the form name=value. The values are LID dependent.

If the date field is missing (e.g. two consecutive tabs) then the current time and date is used. Using an empty string will clear the caller ID so that no caller ID is sent on the next RingLine() call.

if the line is on hook then this information is sent when the next RingLine() function is called to start a ring cycle. Note that if the Ring cycle had already been started then this function may return false.

If the line is off hook, then a Caller ID on Message Waiting is sent, if supported by the LID, otherwise false is returned.

Parameters

idString ID string to use

References OpalLineInterfaceDevice::SetCallerID().

virtual PBoolean OpalLine::SetConnected ( )

inlinevirtual

Indicate to the POTS handset that the call is connected. This uses the hardware (and country) dependent means to indicate to the remote end of a POTS connection that we have answerd. Typically this is a "polarity reversal" but other techniques may be used.

The "connected" state remains in force till the remote disconnects the call, though hanging up.

Returns true if successful, always returns false for PSTN lines.

References OpalLineInterfaceDevice::SetLineConnected().

virtual PBoolean OpalLine::SetOffHook ( )

inlinevirtual

Set the hook state of the line. Note that not be possible on a given line, for example a POTS line with a standard telephone handset. The hook state is determined by external hardware and cannot be changed by the software.

References OpalLineInterfaceDevice::SetLineOffHook().

virtual PBoolean OpalLine::SetOnHook ( )

inlinevirtual

Set the hook state of the line. This is the complement of SetLineOffHook().

References OpalLineInterfaceDevice::SetLineOffHook().

virtual PBoolean OpalLine::SetPlayVolume ( unsigned volume )

inlinevirtual

Set volume level for playing. A value of 100 is the maximum volume possible for the hardware. A value of 0 is the minimum volume possible for the hardware.

Parameters

volume Volume level from 0 to 100%

References OpalLineInterfaceDevice::SetPlayVolume().

virtual PBoolean OpalLine::SetReadFormat ( const OpalMediaFormat & mediaFormat )

inlinevirtual

Set the media format (codec) for reading on the specified line.

Parameters

mediaFormat Codec type

References OpalLineInterfaceDevice::SetReadFormat().

virtual PBoolean OpalLine::SetReadFrameSize ( PINDEX frameSize )

inlinevirtual

Set the read frame size in bytes. Note that a LID may ignore this value so always use GetReadFrameSize() for I/O.

Parameters

frameSize New frame size

References OpalLineInterfaceDevice::SetReadFrameSize().

virtual PBoolean OpalLine::SetRecordVolume ( unsigned volume )

inlinevirtual

Set volume level for recording. A value of 100 is the maximum volume possible for the hardware. A value of 0 is the minimum volume possible for the hardware.

Parameters

volume Volume level from 0 to 100%

References OpalLineInterfaceDevice::SetRecordVolume().

virtual PBoolean OpalLine::SetRemoveDTMF ( PBoolean removeTones )

inlinevirtual

Set DTMF removal mode. When set in this mode the DTMF tones detected are removed from the encoded data stream as returned by ReadFrame().

Parameters

removeTones Flag for removing DTMF tones.

References OpalLineInterfaceDevice::SetRemoveDTMF().

void OpalLine::SetToken ( const PString & t )

inline

Set the token to uniquely identify this line.