OPAL: OpalLine Class Reference

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

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

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

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.

virtual PBoolean OpalLine::IsPresent ( PBoolean force = PFalse ) [inline, virtual]

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

Parameters:

force

Force test, do not optimise

virtual PBoolean OpalLine::IsOffHook ( ) [inline, virtual]

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

virtual PBoolean OpalLine::SetOffHook ( ) [inline, virtual]

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.

virtual PBoolean OpalLine::SetOnHook ( ) [inline, virtual]

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

virtual PBoolean OpalLine::HookFlash ( unsigned flashTime = 200 ) [inline, virtual]

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

virtual PBoolean OpalLine::HasHookFlash ( ) [inline, virtual]

Return PTrue if a hook flash has been detected

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 PTrue 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 unsigned OpalLine::GetRingCount ( DWORD * cadence = NULL ) [virtual]

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

Parameters:

cadence

Cadence of incoming ring

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

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)

virtual PBoolean OpalLine::SetConnected ( ) [inline, virtual]

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.

virtual PBoolean OpalLine::IsConnected ( ) [inline, virtual]

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

virtual PBoolean OpalLine::IsDisconnected ( ) [inline, virtual]

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

virtual PBoolean OpalLine::SetReadFormat ( const OpalMediaFormat & mediaFormat ) [inline, virtual]

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

Parameters:

mediaFormat

Codec type

virtual PBoolean OpalLine::SetWriteFormat ( const OpalMediaFormat & mediaFormat ) [inline, virtual]

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

Parameters:

mediaFormat

Codec type

virtual OpalMediaFormat OpalLine::GetReadFormat ( ) [inline, virtual]

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

virtual OpalMediaFormat OpalLine::GetWriteFormat ( ) [inline, virtual]

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

virtual PBoolean OpalLine::StopReading ( ) [inline, virtual]

Stop the read codec.

virtual PBoolean OpalLine::StopWriting ( ) [inline, virtual]

Stop the write codec.

virtual PBoolean OpalLine::SetReadFrameSize ( PINDEX frameSize ) [inline, virtual]

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

virtual PBoolean OpalLine::SetWriteFrameSize ( PINDEX frameSize ) [inline, virtual]

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

Parameters:

frameSize

New frame size

virtual PINDEX OpalLine::GetReadFrameSize ( ) [inline, virtual]

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

virtual PINDEX OpalLine::GetWriteFrameSize ( ) [inline, virtual]

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

virtual PBoolean OpalLine::ReadFrame	(	void *	buf,
		PINDEX &	count
	)			`[inline, virtual]`

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

virtual PBoolean OpalLine::WriteFrame	(	const void *	buf,
		PINDEX	count,
		PINDEX &	written
	)			`[inline, virtual]`

Low level write frame to the device.

Parameters:

buf	Pointer to a block of memory to write.
count	Number of bytes to write, <= GetWriteFrameSize()
written	Number of bytes written, <= GetWriteFrameSize()

virtual PBoolean OpalLine::ReadBlock	(	void *	buf,
		PINDEX	count
	)			`[inline, virtual]`

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.

virtual PBoolean OpalLine::WriteBlock	(	const void *	buf,
		PINDEX	count
	)			`[inline, virtual]`

High level write audio data to the device.

Parameters:

buf	Pointer to a block of memory to write.
count	Count of bytes to write.

virtual unsigned OpalLine::GetAverageSignalLevel ( PBoolean playback ) [inline, virtual]

Get average signal level in last frame.

Parameters:

playback

Get average playback or record level.

virtual PBoolean OpalLine::EnableAudio ( PBoolean enable = PTrue ) [inline, virtual]

Enable audio for the line.

PBoolean OpalLine::DisableAudio ( ) [inline]

Disable audio for the line.

virtual PBoolean OpalLine::IsAudioEnabled ( ) const [inline, virtual]

Determine if audio is ebabled for the line.

virtual PBoolean OpalLine::SetRecordVolume ( unsigned volume ) [inline, virtual]

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%

virtual PBoolean OpalLine::SetPlayVolume ( unsigned volume ) [inline, virtual]

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%

virtual PBoolean OpalLine::GetRecordVolume ( unsigned & volume ) [inline, virtual]

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%

virtual PBoolean OpalLine::GetPlayVolume ( unsigned & volume ) [inline, virtual]

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%

virtual OpalLineInterfaceDevice::AECLevels OpalLine::GetAEC ( ) const [inline, virtual]

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

virtual PBoolean OpalLine::SetAEC ( OpalLineInterfaceDevice::AECLevels level ) [inline, virtual]

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

Parameters:

level

AEC level

virtual PBoolean OpalLine::GetVAD ( ) const [inline, virtual]

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

virtual PBoolean OpalLine::SetVAD ( PBoolean enable ) [inline, virtual]

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

Parameters:

enable

Flag for enabling VAD

virtual PBoolean OpalLine::GetCallerID	(	PString &	idString,
		PBoolean	full = `PFalse`
	)			`[inline, virtual]`

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

virtual PBoolean OpalLine::SetCallerID ( const PString & idString ) [inline, virtual]

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

virtual PBoolean OpalLine::SendVisualMessageWaitingIndicator ( PBoolean on ) [inline, virtual]

Send a Visual Message Waiting Indicator

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

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

virtual char OpalLine::ReadDTMF ( ) [inline, virtual]

Read a DTMF digit detected. This may be characters from the set 0-9, A-D, * or #. A null ('') 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

virtual PBoolean OpalLine::GetRemoveDTMF ( ) [inline, virtual]

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

virtual PBoolean OpalLine::SetRemoveDTMF ( PBoolean removeTones ) [inline, virtual]

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.

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::IsToneDetected ( ) [inline, virtual]

See if any tone is detected.

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::WaitForToneDetect ( unsigned timeout = 3000 ) [inline, virtual]

See if any tone is detected.

Parameters:

timeout

Milliseconds to wait for

virtual PBoolean OpalLine::WaitForTone	(	OpalLineInterfaceDevice::CallProgressTones	tone,
		unsigned	timeout = `3000`
	)			`[inline, virtual]`

See if a specific tone is detected.

Parameters:

tone	Tone to wait for
timeout	Milliseconds to wait for

virtual PBoolean OpalLine::PlayTone ( OpalLineInterfaceDevice::CallProgressTones tone ) [inline, virtual]

Play a tone.

Parameters:

tone

Tone to be played

virtual PBoolean OpalLine::IsTonePlaying ( ) [inline, virtual]

Determine if a tone is still playing

virtual PBoolean OpalLine::StopTone ( ) [inline, virtual]

Stop playing a tone.

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

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

OpalLineInterfaceDevice& OpalLine::GetDevice ( ) const [inline]

Get the device this line is on.

unsigned OpalLine::GetLineNumber ( ) const [inline]

Get the number of the line on the device.

PString OpalLine::GetToken ( ) const [inline]

Get the token to uniquely identify this line.

void OpalLine::SetToken ( const PString & t ) [inline]

Set the token to uniquely identify this line.

OpalLineInterfaceDevice& OpalLine::device [protected]

unsigned OpalLine::lineNumber [protected]

PString OpalLine::token [protected]

PTimeInterval OpalLine::ringStoppedTime [protected]

PTimeInterval OpalLine::ringInterCadenceTime [protected]

PTimeInterval OpalLine::ringTick [protected]

unsigned OpalLine::ringCount [protected]

bool OpalLine::lastRingState [protected]

OpalLine Class Reference

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation


Public Member Functions
Overrides from PObject
void	PrintOn (ostream &strm) const
Basic operations
virtual PBoolean	IsTerminal ()
virtual PBoolean	IsPresent (PBoolean force=PFalse)
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=PTrue)
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=PFalse)
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