# OpalLine Class Reference

`#include <lid.h>`

Collaboration diagram for OpalLine:

[legend]

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

PBoolean OpalLine::DisableAudio | ( |  | ) | `[inline]`

Disable audio for the line.

virtual PBoolean OpalLine::EnableAudio | ( | PBoolean | enable = `true` | ) | `[inline, virtual]`

Enable audio for the line.

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

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

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

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 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 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 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::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 PBoolean OpalLine::GetVAD | ( |  | ) | const`[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 PBoolean OpalLine::HasHookFlash | ( |  | ) | `[inline, virtual]`

Return true if a hook flash has been detected

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

Determine if audio is ebabled for the line.

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

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.

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

See if any tone is detected.

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

Determine if a tone is still playing

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

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::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::SendVisualMessageWaitingIndicator | ( | PBoolean | on | ) | `[inline, virtual]`

Send a Visual Message Waiting Indicator

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

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

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

Parameters:

  mediaFormat | Codec type

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

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

Set the token to uniquely identify this line.

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

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

Parameters:

  mediaFormat | Codec type

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 PBoolean OpalLine::StopReading | ( |  | ) | `[inline, virtual]`

Stop the read codec.

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

Stop playing a tone.

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

Stop the write codec.

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

See if any tone is detected.

Parameters:

  timeout | Milliseconds to wait for

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

## Field Documentation

OpalLineInterfaceDevice& OpalLine::device `[protected]`

bool OpalLine::lastRingState `[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:

- lid.h