OpalLine Class Reference

#include <lid.h>

List of all members.

Public Member Functions
Overrides from PObject
void	PrintOn (ostream &strm) const
Basic operations
virtual BOOL	IsTerminal ()
virtual BOOL	IsPresent (BOOL force=FALSE)
virtual BOOL	IsOffHook ()
virtual BOOL	SetOffHook ()
virtual BOOL	SetOnHook ()
virtual BOOL	HookFlash (unsigned flashTime=200)
virtual BOOL	HasHookFlash ()
virtual BOOL	IsRinging (DWORD *cadence=NULL)
virtual unsigned	GetRingCount (DWORD *cadence=NULL)
virtual BOOL	Ring (PINDEX nCadence, const unsigned *pattern=NULL, unsigned frequency=400)
virtual BOOL	IsDisconnected ()
virtual BOOL	SetReadFormat (const OpalMediaFormat &mediaFormat)
virtual BOOL	SetWriteFormat (const OpalMediaFormat &mediaFormat)
virtual OpalMediaFormat	GetReadFormat ()
virtual OpalMediaFormat	GetWriteFormat ()
virtual BOOL	StopReading ()
virtual BOOL	StopWriting ()
virtual BOOL	SetReadFrameSize (PINDEX frameSize)
virtual BOOL	SetWriteFrameSize (PINDEX frameSize)
virtual PINDEX	GetReadFrameSize ()
virtual PINDEX	GetWriteFrameSize ()
virtual BOOL	ReadFrame (void *buf, PINDEX &count)
virtual BOOL	WriteFrame (const void *buf, PINDEX count, PINDEX &written)
virtual BOOL	ReadBlock (void *buf, PINDEX count)
virtual BOOL	WriteBlock (const void *buf, PINDEX count)
virtual unsigned	GetAverageSignalLevel (BOOL playback)
virtual BOOL	EnableAudio (BOOL enable=TRUE)
BOOL	DisableAudio ()
virtual BOOL	IsAudioEnabled ()
virtual BOOL	SetRecordVolume (unsigned volume)
virtual BOOL	SetPlayVolume (unsigned volume)
virtual BOOL	GetRecordVolume (unsigned &volume)
virtual BOOL	GetPlayVolume (unsigned &volume)
virtual OpalLineInterfaceDevice::AECLevels	GetAEC ()
virtual BOOL	SetAEC (OpalLineInterfaceDevice::AECLevels level)
virtual BOOL	GetVAD ()
virtual BOOL	SetVAD (BOOL enable)
virtual BOOL	GetCallerID (PString &idString, BOOL full=FALSE)
virtual BOOL	SetCallerID (const PString &idString)
virtual BOOL	SendCallerIDOnCallWaiting (const PString &idString)
virtual BOOL	SendVisualMessageWaitingIndicator (BOOL on)
virtual BOOL	PlayDTMF (const char *digits, DWORD onTime=OpalLineInterfaceDevice::DefaultDTMFOnTime, DWORD offTime=OpalLineInterfaceDevice::DefaultDTMFOffTime)
virtual char	ReadDTMF ()
virtual BOOL	GetRemoveDTMF ()
virtual BOOL	SetRemoveDTMF (BOOL removeTones)
virtual unsigned	IsToneDetected ()
virtual OpalLineInterfaceDevice::CallProgressTones	WaitForToneDetect (unsigned timeout=3000)
virtual BOOL	WaitForTone (OpalLineInterfaceDevice::CallProgressTones tone, unsigned timeout=3000)
virtual BOOL	PlayTone (OpalLineInterfaceDevice::CallProgressTones tone)
virtual BOOL	IsTonePlaying ()
virtual BOOL	StopTone ()
virtual OpalLineInterfaceDevice::CallProgressTones	DialOut (const PString &number, BOOL requireTones=FALSE, unsigned uiDialDelay=0)
Member variable access
OpalLineInterfaceDevice &	GetDevice () const
unsigned	GetLineNumber () const
PString	GetToken () const
PString	GetDescription () const
Protected Attributes
OpalLineInterfaceDevice &	device
unsigned	lineNumber
PString	token
PString	description
unsigned	ringCount
PTimeInterval	ringTick
PTimeInterval	ringStoppedTime
PTimeInterval	ringInterCadenceTime

---

Detailed Description

This class describes the LID based codec capability.

---

Constructor & Destructor Documentation

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

Create a new telephone line.

Parameters:

device	Device to make connection with
lineNumber	number of line on LID
description	DEscription string for line

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

Create a new telephone line.

Parameters:

device	Device to make connection with
lineNumber	number of line on LID
description	DEscription string for line

---

Member Function Documentation

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 BOOL 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 BOOL OpalLine::IsPresent

(

BOOL

force = FALSE

)

[inline, virtual]

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

Parameters:

force

Force test, do not optimise

virtual BOOL 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 TRUE indicates that the phone is really off hook. That is hook flashes and winks are masked out.

virtual BOOL 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 BOOL OpalLine::SetOnHook

(

)

[inline, virtual]

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

virtual BOOL 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 BOOL OpalLine::HasHookFlash

(

)

[inline, virtual]

Return TRUE if a hook flash has been detected

virtual BOOL OpalLine::IsRinging

(

DWORD *

cadence = NULL

)

[inline, 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 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 BOOL 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 BOOL OpalLine::IsDisconnected

(

)

[inline, virtual]

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

virtual BOOL OpalLine::SetReadFormat

(

const OpalMediaFormat &

mediaFormat

)

[inline, virtual]

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

Parameters:

mediaFormat

Codec type

virtual BOOL 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 BOOL OpalLine::StopReading

(

)

[inline, virtual]

Stop the read codec.

virtual BOOL OpalLine::StopWriting

(

)

[inline, virtual]

Stop the write codec.

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

(

BOOL

playback

)

[inline, virtual]

Get average signal level in last frame.

Parameters:

playback

Get average playback or record level.

virtual BOOL OpalLine::EnableAudio

(

BOOL

enable = TRUE

)

[inline, virtual]

Enable audio for the line.

BOOL OpalLine::DisableAudio

(

)

[inline]

Disable audio for the line.

virtual BOOL OpalLine::IsAudioEnabled

(

)

[inline, virtual]

Determine if audio is ebabled for the line.

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

(

)

[inline, virtual]

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

virtual BOOL OpalLine::SetAEC

(

OpalLineInterfaceDevice::AECLevels

level

)

[inline, virtual]

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

Parameters:

level

AEC level

virtual BOOL OpalLine::GetVAD

(

)

[inline, virtual]

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

virtual BOOL OpalLine::SetVAD

(

BOOL

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 BOOL OpalLine::GetCallerID	(	PString &	idString,
		BOOL	full = FALSE
	)			[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 of the number field, the time/date and the name field separated by tabs ('').

Parameters:

idString	ID string returned
full	Get full information in idString

virtual BOOL OpalLine::SetCallerID

(

const PString &

idString

)

[inline, virtual]

Set Caller ID for use in next RingLine() call. The full data of the caller ID string consists of the number field, the time/date and the name field separated by tabs ('').

If the date field is missing (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.

Parameters:

idString

ID string to use

virtual BOOL OpalLine::SendCallerIDOnCallWaiting

(

const PString &

idString

)

[inline, virtual]

Send a Caller ID on call waiting command The full data of the caller ID string consists of the number field, the time/date and the name field separated by tabs ('').

If the date field is missing (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.

Parameters:

idString

ID string to use

virtual BOOL OpalLine::SendVisualMessageWaitingIndicator

(

BOOL

on

)

[inline, virtual]

Send a Visual Message Waiting Indicator

virtual BOOL 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 BOOL 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 BOOL OpalLine::SetRemoveDTMF

(

BOOL

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 unsigned 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 BOOL 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 BOOL OpalLine::PlayTone

(

OpalLineInterfaceDevice::CallProgressTones

tone

)

[inline, virtual]

Play a tone.

Parameters:

tone	Tone to be played

virtual BOOL OpalLine::IsTonePlaying

(

)

[inline, virtual]

Determine if a tone is still playing

virtual BOOL OpalLine::StopTone

(

)

[inline, virtual]

Stop playing a tone.

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::DialOut	(	const PString &	number,
		BOOL	requireTones = FALSE,
		unsigned	uiDialDelay = 0
	)			[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 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
requireTones	Require dial/ring tone to be detected
uiDialDelay	time in msec to wait between the dial tone detection and dialing the dtmf

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.

PString OpalLine::GetDescription

(

)

const [inline]

Get the description of this line.

---

Member Data Documentation

OpalLineInterfaceDevice& OpalLine::device [protected]

unsigned OpalLine::lineNumber [protected]

PString OpalLine::token [protected]

PString OpalLine::description [protected]

unsigned OpalLine::ringCount [protected]

PTimeInterval OpalLine::ringTick [protected]

PTimeInterval OpalLine::ringStoppedTime [protected]

PTimeInterval OpalLine::ringInterCadenceTime [protected]

---

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

• lid.h

---