OpalLine Class Reference

`#include <lid.h>`

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

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

inline virtual

Enable audio for the line.

References OpalLineInterfaceDevice::EnableAudio().

Referenced by DisableAudio().

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

inline virtual

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

References OpalLineInterfaceDevice::GetAEC().

virtual unsigned OpalLine::GetAverageSignalLevel | ( | PBoolean | playback | ) |

inline virtual

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

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

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%

References OpalLineInterfaceDevice::GetPlayVolume().

virtual OpalMediaFormat OpalLine::GetReadFormat | ( |  | ) |

inline virtual

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

References OpalLineInterfaceDevice::GetReadFormat().

virtual PINDEX OpalLine::GetReadFrameSize | ( |  | ) |

inline virtual

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

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%

References OpalLineInterfaceDevice::GetRecordVolume().

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

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

inline virtual

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

References OpalLineInterfaceDevice::GetVAD().

virtual OpalMediaFormat OpalLine::GetWriteFormat | ( |  | ) |

inline virtual

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

References OpalLineInterfaceDevice::GetWriteFormat().

virtual PINDEX OpalLine::GetWriteFrameSize | ( |  | ) |

inline virtual

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

References OpalLineInterfaceDevice::GetWriteFrameSize().

virtual PBoolean OpalLine::HasHookFlash | ( |  | ) |

inline virtual

Return true if a hook flash has been detected

References OpalLineInterfaceDevice::HasHookFlash().

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

References OpalLineInterfaceDevice::HookFlash().

virtual PBoolean OpalLine::IsAudioEnabled | ( |  | ) | const

inline virtual

Determine if audio is ebabled for the line.

References OpalLineInterfaceDevice::IsAudioEnabled().

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

References OpalLineInterfaceDevice::IsLineConnected().

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

References OpalLineInterfaceDevice::IsLineDisconnected().

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

inline virtual

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

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.

References OpalLineInterfaceDevice::IsLineTerminal().

Referenced by OpalLineConnection::IsNetworkConnection().

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::IsToneDetected | ( |  | ) |

inline virtual

See if any tone is detected.

References OpalLineInterfaceDevice::IsToneDetected().

virtual PBoolean OpalLine::IsTonePlaying | ( |  | ) |

inline virtual

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

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

References OpalLineInterfaceDevice::PlayDTMF().

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

inline virtual

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

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.

References OpalLineInterfaceDevice::ReadBlock().

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

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

References OpalLineInterfaceDevice::ReadFrame().

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)

References OpalLineInterfaceDevice::RingLine().

virtual PBoolean OpalLine::SendVisualMessageWaitingIndicator | ( | PBoolean | on | ) |

inline virtual

Send a Visual Message Waiting Indicator

References OpalLineInterfaceDevice::SendVisualMessageWaitingIndicator().

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

References OpalLineInterfaceDevice::SetAEC().

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

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.

References OpalLineInterfaceDevice::SetLineConnected().

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.

References OpalLineInterfaceDevice::SetLineOffHook().

virtual PBoolean OpalLine::SetOnHook | ( |  | ) |

inline virtual

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

References OpalLineInterfaceDevice::SetLineOffHook().

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%

References OpalLineInterfaceDevice::SetPlayVolume().

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

inline virtual

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

Parameters

  mediaFormat | Codec type

References OpalLineInterfaceDevice::SetReadFormat().

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

References OpalLineInterfaceDevice::SetReadFrameSize().

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%

References OpalLineInterfaceDevice::SetRecordVolume().

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.

References OpalLineInterfaceDevice::SetRemoveDTMF().

void OpalLine::SetToken | ( | const PString & | t | ) |

inline

Set the token to uniquely identify this line.

References token.

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

References OpalLineInterfaceDevice::SetVAD().

virtual PBoolean OpalLine::SetWriteFormat | ( | const OpalMediaFormat & | mediaFormat | ) |

inline virtual

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

Parameters

  mediaFormat | Codec type

References OpalLineInterfaceDevice::SetWriteFormat().

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

References OpalLineInterfaceDevice::SetWriteFrameSize().

virtual PBoolean OpalLine::StopReading | ( |  | ) |

inline virtual

Stop the read codec.

References OpalLineInterfaceDevice::StopReading().

virtual PBoolean OpalLine::StopTone | ( |  | ) |

inline virtual

Stop playing a tone.

References OpalLineInterfaceDevice::StopTone().

virtual PBoolean OpalLine::StopWriting | ( |  | ) |

inline virtual

Stop the write codec.

References OpalLineInterfaceDevice::StopWriting().

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

References OpalLineInterfaceDevice::WaitForTone().

virtual OpalLineInterfaceDevice::CallProgressTones OpalLine::WaitForToneDetect | ( | unsigned | timeout = `3000` | ) |

inline virtual

See if any tone is detected.

Parameters

  timeout | Milliseconds to wait for

References OpalLineInterfaceDevice::WaitForToneDetect().

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.

References OpalLineInterfaceDevice::WriteBlock().

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

References OpalLineInterfaceDevice::WriteFrame().

## Field Documentation

OpalLineInterfaceDevice& OpalLine::device

protected

Referenced by GetDevice().

bool OpalLine::lastRingState

protected

unsigned OpalLine::lineNumber

protected

Referenced by GetLineNumber().

unsigned OpalLine::ringCount

protected

PTimeInterval OpalLine::ringInterCadenceTime

protected

PTimeInterval OpalLine::ringStoppedTime

protected

PTimeInterval OpalLine::ringTick

protected

PString OpalLine::token

protected

Referenced by GetToken(), and SetToken().

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

- lid.h