OpalLine Class Reference

#include <lid.h>

List of all members.

Public Member Functions

Construction
 OpalLine (OpalLineInterfaceDevice &device, unsigned lineNumber, const char *description=NULL)
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 (BOOL newState=TRUE)
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 (DWORD cadence)
virtual BOOL Ring (PINDEX nCadence, unsigned *pattern)
virtual BOOL IsDisconnected ()
virtual BOOL SetReadFormat (const OpalMediaFormat &mediaFormat)
virtual BOOL SetWriteFormat (const OpalMediaFormat &mediaFormat)
virtual OpalMediaFormat GetReadFormat ()
virtual OpalMediaFormat GetWriteFormat ()
virtual BOOL SetRawCodec ()
virtual BOOL StopReadCodec ()
virtual BOOL StopWriteCodec ()
virtual BOOL StopRawCodec ()
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 unsigned 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)
Member variable access
OpalLineInterfaceDeviceGetDevice () const
unsigned GetLineNumber () const
PString GetToken () const
PString GetDescription () const

Protected Attributes

OpalLineInterfaceDevicedevice
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


Member Function Documentation

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::DialOut ( const PString &  number,
BOOL  requireTones = FALSE 
) [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

BOOL OpalLine::DisableAudio (  )  [inline]

Disable audio for the line.

virtual BOOL OpalLine::EnableAudio ( BOOL  enable = TRUE  )  [inline, virtual]

Enable audio for the line.

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

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

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::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

PString OpalLine::GetDescription (  )  const [inline]

Get the description of this line.

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.

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

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

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

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

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

virtual BOOL OpalLine::GetVAD (  )  [inline, virtual]

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

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

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

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

Return TRUE if a hook flash has been detected

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

Determine if audio is ebabled for the line.

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

See if any tone is detected.

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

Determine if a tone is still playing

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 BOOL OpalLine::PlayTone ( OpalLineInterfaceDevice::CallProgressTones  tone  )  [inline, virtual]

Play a tone.

Parameters:
tone  Tone to be played

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::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 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::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::Ring ( PINDEX  nCadence,
unsigned *  pattern 
) [inline, virtual]

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

Note that 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 }

Parameters:
nCadence  Number of entries in cadence array
pattern  Ring pattern times

virtual BOOL OpalLine::Ring ( DWORD  cadence  )  [inline, virtual]

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

Note that 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.

Parameters:
cadence  Cadence bit map for ring pattern

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::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::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::SetOffHook ( BOOL  newState = TRUE  )  [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.

Parameters:
newState  New state to set

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

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

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

Set the line codec for reading/writing raw PCM data. A descendent may use this to do anything special to the device before beginning special PCM output. For example disabling AEC and set volume levels to standard values. This can then be used for generating standard tones using PCM if the driver is not capable of generating or detecting them directly.

The default behaviour simply does a SetReadCodec and SetWriteCodec for PCM data.

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::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::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::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 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::SetWriteFormat ( const OpalMediaFormat mediaFormat  )  [inline, virtual]

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

Parameters:
mediaFormat  Codec type

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

Stop the raw PCM mode codec.

virtual BOOL OpalLine::StopReadCodec (  )  [inline, virtual]

Stop the read codec.

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

Stop playing a tone.

virtual BOOL OpalLine::StopWriteCodec (  )  [inline, virtual]

Stop the write codec.

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 unsigned OpalLine::WaitForToneDetect ( unsigned  timeout = 3000  )  [inline, virtual]

See if any tone is detected.

Parameters:
timeout  Milliseconds to wait for

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


Member Data Documentation

PString OpalLine::description [protected]

OpalLineInterfaceDevice& OpalLine::device [protected]

unsigned OpalLine::lineNumber [protected]

unsigned OpalLine::ringCount [protected]

PTimeInterval OpalLine::ringInterCadenceTime [protected]

PTimeInterval OpalLine::ringStoppedTime [protected]

PTimeInterval OpalLine::ringTick [protected]

PString OpalLine::token [protected]


The documentation for this class was generated from the following file:
Generated on Mon Sep 25 16:21:51 2006 for OPAL by  doxygen 1.4.7