lid.h

Go to the documentation of this file.

/*
 * lid.h
 *
 * Line Interface Device
 *
 * Open Phone Abstraction Library
 *
 * Copyright (c) 1999-2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions of this code were written with the assisance of funding from 
 * Quicknet Technologies, Inc. http://www.quicknet.net.
 * 
 * Contributor(s): ______________________________________.
 *
 * $Revision: 24178 $
 * $Author: rjongbloed $
 * $Date: 2010-04-06 10:10:56 +1000 (Tue, 06 Apr 2010) $
 */

#ifndef OPAL_LIDS_LID_H
#define OPAL_LIDS_LID_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <opal/mediafmt.h>



class OpalLineInterfaceDevice : public PObject
{
  PCLASSINFO(OpalLineInterfaceDevice, PObject);

  public:
    OpalLineInterfaceDevice();

    virtual PBoolean Open(
      const PString & device      
    ) = 0;

    virtual PBoolean IsOpen() const;

    virtual PBoolean Close();

    virtual PString GetDeviceType() const = 0;

    virtual PString GetDeviceName() const = 0;

    virtual PStringArray GetAllNames() const = 0;

    virtual PString GetDescription() const = 0;

    virtual unsigned GetLineCount() const = 0;

    virtual PBoolean IsLineTerminal(
      unsigned line   
    ) = 0;


    virtual PBoolean IsLinePresent(
      unsigned line,      
      PBoolean force = false  
    );


    virtual PBoolean IsLineOffHook(
      unsigned line   
    ) = 0;

    virtual PBoolean SetLineOffHook(
      unsigned line,        
      PBoolean newState = true  
    ) = 0;

    virtual PBoolean SetLineOnHook(
      unsigned line        
    ) { return SetLineOffHook(line, false); }

    virtual PBoolean HookFlash(
      unsigned line,              
      unsigned flashTime = 200    
    );

    virtual PBoolean HasHookFlash(unsigned line);


    virtual PBoolean IsLineRinging(
      unsigned line,          
      DWORD * cadence = NULL  
    );

    virtual PBoolean RingLine(
      unsigned line,                   
      PINDEX nCadence,                 
      const unsigned * pattern = NULL, 
      unsigned frequency = 400         
    );


    virtual PBoolean SetLineConnected(
      unsigned line   
    );

    virtual PBoolean IsLineConnected(
      unsigned line   
    );


    virtual PBoolean IsLineDisconnected(
      unsigned line,   
      PBoolean checkForWink = true 
    );


    virtual PBoolean SetLineToLineDirect(
      unsigned line1,   
      unsigned line2,   
      PBoolean connect      
    );

    virtual PBoolean IsLineToLineDirect(
      unsigned line1,   
      unsigned line2    
    );


    virtual OpalMediaFormatList GetMediaFormats() const = 0;

    virtual PBoolean SetReadFormat(
      unsigned line,    
      const OpalMediaFormat & mediaFormat   
    ) = 0;

    virtual PBoolean SetWriteFormat(
      unsigned line,    
      const OpalMediaFormat & mediaFormat   
    ) = 0;

    virtual OpalMediaFormat GetReadFormat(
      unsigned line    
    ) = 0;

    virtual OpalMediaFormat GetWriteFormat(
      unsigned line    
    ) = 0;

    virtual PBoolean StopReading(
      unsigned line   
    );

    virtual PBoolean StopWriting(
      unsigned line   
    );

    virtual bool UsesRTP() const;

    virtual PBoolean SetReadFrameSize(
      unsigned line,    
      PINDEX frameSize  
    );

    virtual PBoolean SetWriteFrameSize(
      unsigned line,    
      PINDEX frameSize  
    );

    virtual PINDEX GetReadFrameSize(
      unsigned line   
    );

    virtual PINDEX GetWriteFrameSize(
      unsigned line   
    );

    virtual PBoolean ReadFrame(
      unsigned line,    
      void * buf,       
      PINDEX & count    
    ) = 0;

    virtual PBoolean WriteFrame(
      unsigned line,    
      const void * buf, 
      PINDEX count,     
      PINDEX & written  
    ) = 0;

    virtual PBoolean ReadBlock(
      unsigned line,    
      void * buf,   
      PINDEX count  
    );

    virtual PBoolean WriteBlock(
      unsigned line,    
      const void * buf, 
      PINDEX count      
    );


    virtual unsigned GetAverageSignalLevel(
      unsigned line,  
      PBoolean playback   
    );


    virtual PBoolean EnableAudio(
      unsigned line,      
      PBoolean enable = true 
    );

    PBoolean DisableAudio(
      unsigned line   
    ) { return EnableAudio(line, false); }

    virtual PBoolean IsAudioEnabled(
      unsigned line      
    ) const;


    enum {
      MaxVolume = 100
    };

    virtual PBoolean SetRecordVolume(
      unsigned line,    
      unsigned volume   
    );

    virtual PBoolean SetPlayVolume(
      unsigned line,    
      unsigned volume   
    );

    virtual PBoolean GetRecordVolume(
      unsigned line,      
      unsigned & volume   
    );

    virtual PBoolean GetPlayVolume(
      unsigned line,      
      unsigned & volume   
    );


    enum AECLevels {
      AECOff,
      AECLow,
      AECMedium,
      AECHigh,
      AECAuto,
      AECAGC,
      AECError
    };

    virtual AECLevels GetAEC(
      unsigned line    
    ) const;

    virtual PBoolean SetAEC(
      unsigned line,    
      AECLevels level   
    );

    virtual PBoolean GetVAD(
      unsigned line    
    ) const;

    virtual PBoolean SetVAD(
      unsigned line,    
      PBoolean enable       
    );


    virtual PBoolean GetCallerID(
      unsigned line,      
      PString & idString, 
      PBoolean full = false   
    );

    virtual PBoolean SetCallerID(
      unsigned line,            
      const PString & idString  
    );

    virtual PBoolean SendVisualMessageWaitingIndicator(
      unsigned line,            
      PBoolean on               
    );


    enum {
      DefaultDTMFOnTime = 150,
      DefaultDTMFOffTime = 50
    };

    virtual PBoolean PlayDTMF(
      unsigned line,            
      const char * digits,      
      DWORD onTime = DefaultDTMFOnTime,  
      DWORD offTime = DefaultDTMFOffTime 
    );

    virtual char ReadDTMF(
      unsigned line   
    );

    virtual PBoolean GetRemoveDTMF(
      unsigned line   
    );

    virtual PBoolean SetRemoveDTMF(
      unsigned line,     
      PBoolean removeTones   
    );


    enum CallProgressTones {
      NoTone = -1, // indicates no tones
      DialTone,    // Dial tone
      RingTone,    // Ring indication tone
      BusyTone,    // Line engaged tone
      CongestionTone,// aka fast busy tone
      ClearTone,   // Call failed/disconnected tone (often same as busy tone)
      MwiTone,     // Message Waiting Tone
      RoutingTone, // Call is being routed (not normal for PSTN, but VoIP can take a while)
      CNGTone,     // Fax CNG tone
      CEDTone,     // Fax CED tone
      UserDefinedTone,
      NumTones
    };

    virtual CallProgressTones IsToneDetected(
      unsigned line   
    );

    virtual CallProgressTones WaitForToneDetect(
      unsigned line,          
      unsigned timeout = 3000 
    );

    virtual PBoolean WaitForTone(
      unsigned line,          
      CallProgressTones tone, 
      unsigned timeout = 3000 
    );

    virtual bool SetToneDescription(
      unsigned line,              
      CallProgressTones tone,     
      const PString & description 
    );

    enum ToneMixingModes {
      SimpleTone,
      AddedTone,
      ModulatedTone
    };

    virtual bool SetToneParameters(
      unsigned line,            
      CallProgressTones tone,   
      unsigned frequency1,      
      unsigned frequency2,      
      ToneMixingModes mode,     
      PINDEX numCadences,       
      const unsigned * onTimes, 
      const unsigned * offTimes 
    );

    virtual PBoolean PlayTone(
      unsigned line,          
      CallProgressTones tone  
    );

    virtual PBoolean IsTonePlaying(
      unsigned line   
    );

    virtual PBoolean StopTone(
      unsigned line   
    );


    struct DialParams {
      DialParams()
        : m_requireTones(false)
        , m_dialToneTimeout(2500)
        , m_dialStartDelay(500)
        , m_dialDigitTime(DefaultDTMFOnTime)
        , m_dialInterDigitTime(DefaultDTMFOffTime)
        , m_progressTimeout(5000)
        , m_commaDelay(2000)
      { }

      bool     m_requireTones;      
      unsigned m_dialToneTimeout;   
      unsigned m_dialStartDelay;    
      unsigned m_dialDigitTime;     
      unsigned m_dialInterDigitTime;
      unsigned m_progressTimeout;   
      unsigned m_commaDelay;        
    };

    virtual CallProgressTones DialOut(
      unsigned line,                
      const PString & number,       
      const DialParams & params = DialParams() 
    );


    virtual unsigned GetWinkDuration(
      unsigned line    
    );

    virtual PBoolean SetWinkDuration(
      unsigned line,        
      unsigned winkDuration 
    );


    enum T35CountryCodes {
      Japan, Albania, Algeria, AmericanSamoa, Germany, Anguilla, AntiguaAndBarbuda,
      Argentina, Ascension, Australia, Austria, Bahamas, Bahrain, Bangladesh,
      Barbados, Belgium, Belize, Benin, Bermudas, Bhutan, Bolivia, Botswana,
      Brazil, BritishAntarcticTerritory, BritishIndianOceanTerritory, 
      BritishVirginIslands, BruneiDarussalam, Bulgaria, Myanmar, Burundi,
      Byelorussia, Cameroon, Canada, CapeVerde, CaymanIslands,
      CentralAfricanRepublic, Chad, Chile, China, Colombia, Comoros, Congo,
      CookIslands, CostaRica, Cuba, Cyprus, Czechoslovakia, Cambodia,
      DemocraticPeoplesRepublicOfKorea, Denmark, Djibouti, DominicanRepublic,
      Dominica, Ecuador, Egypt, ElSalvador, EquatorialGuinea, Ethiopia,
      FalklandIslands, Fiji, Finland, France, FrenchPolynesia,
      FrenchSouthernAndAntarcticLands, Gabon, Gambia, Germany2, Angola, Ghana,
      Gibraltar, Greece, Grenada, Guam, Guatemala, Guernsey, Guinea, GuineaBissau,
      Guayana, Haiti, Honduras, Hongkong, Hungary, Iceland, India, Indonesia,
      Iran, Iraq, Ireland, Israel, Italy, CotedIvoire, Jamaica, Afghanistan,
      Jersey, Jordan, Kenya, Kiribati, KoreaRepublic, Kuwait, Lao, Lebanon,
      Lesotho, Liberia, Libya, Liechtenstein, Luxemborg, Macao, Madagascar,
      Malaysia, Malawi, Maldives, Mali, Malta, Mauritania, Mauritius, Mexico,
      Monaco, Mongolia, Montserrat, Morocco, Mozambique, Nauru, Nepal,
      Netherlands, NetherlandsAntilles, NewCaledonia, NewZealand, Nicaragua,
      Niger, Nigeria, Norway, Oman, Pakistan, Panama, PapuaNewGuinea, Paraguay,
      Peru, Philippines, Poland, Portugal, PuertoRico, Qatar, Romania, Rwanda,
      SaintKittsAndNevis, SaintCroix, SaintHelenaAndAscension, SaintLucia,
      SanMarino, SaintThomas, SaoTomeAndPrincipe, SaintVicentAndTheGrenadines,
      SaudiArabia, Senegal, Seychelles, SierraLeone, Singapore, SolomonIslands,
      Somalia, SouthAfrica, Spain, SriLanka, Sudan, Suriname, Swaziland, Sweden,
      Switzerland, Syria, Tanzania, Thailand, Togo, Tonga, TrinidadAndTobago,
      Tunisia, Turkey, TurksAndCaicosIslands, Tuvalu, Uganda, Ukraine,
      UnitedArabEmirates, UnitedKingdom, UnitedStates, BurkinaFaso, Uruguay,
      USSR, Vanuatu, VaticanCityState, Venezuela, VietNam, WallisAndFutuna,
      WesternSamoa, Yemen, Yemen2, Yugoslavia, Zaire, Zambia, Zimbabwe,
      NumCountryCodes,
      UnknownCountry = -1
    };

    T35CountryCodes GetCountryCode() const { return countryCode; }

    PString GetCountryCodeName() const;

    static PString GetCountryCodeName(T35CountryCodes code);
    static T35CountryCodes GetCountryCode(const PString & name);

    virtual PBoolean SetCountryCode(
      T35CountryCodes country   
    );

    virtual PBoolean SetCountryCodeName(
      const PString & countryName   
    );

    virtual PStringList GetCountryCodeNameList() const;


    virtual PBoolean PlayAudio(
      unsigned line,            
      const PString & filename  
    );
    
    virtual PBoolean StopAudio(
      unsigned line   
    );


    virtual PBoolean RecordAudioStart(
      unsigned line,            
      const PString & filename  
    );
    
    virtual PBoolean RecordAudioStop(
      unsigned line            
    );
    

    int GetErrorNumber() const { return osError; }

    PString GetErrorText() const;

    virtual void PrintOn(
      ostream & strm
    ) const;

    static OpalLineInterfaceDevice * Create(
      const PString & type,     
      void * parameters = NULL  
    );

    static OpalLineInterfaceDevice * CreateAndOpen(
      const PString & descriptor,     
      void * parameters = NULL  
    );

    static PStringList GetAllTypes();

    static PStringList GetAllDevices();

        
  protected:
    int               os_handle;
    mutable int       osError;
    T35CountryCodes   countryCode;
    PBYTEArray        m_readDeblockingBuffer, m_writeDeblockingBuffer;
    PINDEX            m_readDeblockingOffset, m_writeDeblockingOffset;
    std::vector<bool> m_LineAudioEnabled;
    PString           m_callProgressTones[NumTones];
#if PTRACING
    friend ostream & operator<<(ostream & o, CallProgressTones t);
#endif
};


PLIST(OpalLIDList, OpalLineInterfaceDevice);



class OpalLine : public PObject
{
    PCLASSINFO(OpalLine, PObject);
  public:
    OpalLine(
      OpalLineInterfaceDevice & device, 
      unsigned lineNumber,              
      const char * userToken = NULL     
    );

    void PrintOn(
      ostream & strm    
    ) const;

    virtual PBoolean IsTerminal() { return device.IsLineTerminal(lineNumber); }


    virtual PBoolean IsPresent(
      PBoolean force = false  
    ) { return device.IsLinePresent(lineNumber, force); }


    virtual PBoolean IsOffHook() { return device.IsLineOffHook(lineNumber); }

    virtual PBoolean SetOffHook() { return device.SetLineOffHook(lineNumber, true); }

    virtual PBoolean SetOnHook() { return device.SetLineOffHook(lineNumber, false); }

    virtual PBoolean HookFlash(
      unsigned flashTime = 200    
    ) { return device.HookFlash(lineNumber, flashTime); }

    virtual PBoolean HasHookFlash() { return device.HasHookFlash(lineNumber); }


    virtual PBoolean IsRinging(
      DWORD * cadence = NULL  
    );

    virtual unsigned GetRingCount(
      DWORD * cadence = NULL  
    );

    virtual PBoolean Ring(
      PINDEX nCadence,                 
      const unsigned * pattern = NULL, 
      unsigned frequency = 400         
    ) { return device.RingLine(lineNumber, nCadence, pattern, frequency); }


    virtual PBoolean SetConnected() { return device.SetLineConnected(lineNumber); }

    virtual PBoolean IsConnected() { return device.IsLineConnected(lineNumber); }


    virtual PBoolean IsDisconnected() { return device.IsLineDisconnected(lineNumber); }

    virtual PBoolean SetReadFormat(
      const OpalMediaFormat & mediaFormat   
    ) { return device.SetReadFormat(lineNumber, mediaFormat); }

    virtual PBoolean SetWriteFormat(
      const OpalMediaFormat & mediaFormat   
    ) { return device.SetWriteFormat(lineNumber, mediaFormat); }

    virtual OpalMediaFormat GetReadFormat() { return device.GetReadFormat(lineNumber); }

    virtual OpalMediaFormat GetWriteFormat() { return device.GetWriteFormat(lineNumber); }

    virtual PBoolean StopReading() { return device.StopReading(lineNumber); }

    virtual PBoolean StopWriting() { return device.StopWriting(lineNumber); }

    virtual PBoolean SetReadFrameSize(
      PINDEX frameSize  
    ) { return device.SetReadFrameSize(lineNumber, frameSize); }

    virtual PBoolean SetWriteFrameSize(
      PINDEX frameSize  
    ) { return device.SetWriteFrameSize(lineNumber, frameSize); }

    virtual PINDEX GetReadFrameSize() { return device.GetReadFrameSize(lineNumber); }

    virtual PINDEX GetWriteFrameSize() { return device.GetWriteFrameSize(lineNumber); }

    virtual PBoolean ReadFrame(
      void * buf,       
      PINDEX & count    
    ) { return device.ReadFrame(lineNumber, buf, count); }

    virtual PBoolean WriteFrame(
      const void * buf, 
      PINDEX count,     
      PINDEX & written  
    ) { return device.WriteFrame(lineNumber, buf, count, written); }

    virtual PBoolean ReadBlock(
      void * buf,   
      PINDEX count  
    ) { return device.ReadBlock(lineNumber, buf, count); }

    virtual PBoolean WriteBlock(
      const void * buf, 
      PINDEX count      
    ) { return device.WriteBlock(lineNumber, buf, count); }


    virtual unsigned GetAverageSignalLevel(
      PBoolean playback   
    ) { return device.GetAverageSignalLevel(lineNumber, playback); }


    virtual PBoolean EnableAudio(
      PBoolean enable = true
    ) { return device.EnableAudio(lineNumber, enable); }

    PBoolean DisableAudio() { return EnableAudio(false); }

    virtual PBoolean IsAudioEnabled() const { return device.IsAudioEnabled(lineNumber); }


    virtual PBoolean SetRecordVolume(
      unsigned volume   
    ) { return device.SetRecordVolume(lineNumber, volume); }

    virtual PBoolean SetPlayVolume(
      unsigned volume   
    ) { return device.SetPlayVolume(lineNumber, volume); }

    virtual PBoolean GetRecordVolume(
      unsigned & volume   
    ) { return device.GetRecordVolume(lineNumber, volume); }

    virtual PBoolean GetPlayVolume(
      unsigned & volume   
    ) { return device.GetPlayVolume(lineNumber, volume); }


    virtual OpalLineInterfaceDevice::AECLevels GetAEC() const { return device.GetAEC(lineNumber); }

    virtual PBoolean SetAEC(
      OpalLineInterfaceDevice::AECLevels level  
    ) { return device.SetAEC(lineNumber, level); }


    virtual PBoolean GetVAD() const { return device.GetVAD(lineNumber); }

    virtual PBoolean SetVAD(
      PBoolean enable       
    ) { return device.SetVAD(lineNumber, enable); }


    virtual PBoolean GetCallerID(
      PString & idString, 
      PBoolean full = false   
    ) { return device.GetCallerID(lineNumber, idString, full); }

    virtual PBoolean SetCallerID(
      const PString & idString  
    ) { return device.SetCallerID(lineNumber, idString); }

    virtual PBoolean SendVisualMessageWaitingIndicator(
      PBoolean on
    ) { return device.SendVisualMessageWaitingIndicator(lineNumber, on); }


    virtual PBoolean PlayDTMF(
      const char * digits,      
      DWORD onTime = OpalLineInterfaceDevice::DefaultDTMFOnTime,  
      DWORD offTime = OpalLineInterfaceDevice::DefaultDTMFOffTime 
    ) { return device.PlayDTMF(lineNumber, digits, onTime, offTime); }

    virtual char ReadDTMF() { return device.ReadDTMF(lineNumber); }

    virtual PBoolean GetRemoveDTMF() { return device.GetRemoveDTMF(lineNumber); }

    virtual PBoolean SetRemoveDTMF(
      PBoolean removeTones   
    ) { return device.SetRemoveDTMF(lineNumber, removeTones); }


    virtual OpalLineInterfaceDevice::CallProgressTones IsToneDetected() { return device.IsToneDetected(lineNumber); }

    virtual OpalLineInterfaceDevice::CallProgressTones WaitForToneDetect(
      unsigned timeout = 3000 
    ) { return device.WaitForToneDetect(lineNumber, timeout); }

    virtual PBoolean WaitForTone(
      OpalLineInterfaceDevice::CallProgressTones tone, 
      unsigned timeout = 3000 
    ) { return device.WaitForTone(lineNumber, tone, timeout); }

    virtual PBoolean PlayTone(
      OpalLineInterfaceDevice::CallProgressTones tone  
    ) { return device.PlayTone(lineNumber, tone); }

    virtual PBoolean IsTonePlaying() { return device.IsTonePlaying(lineNumber); }

    virtual PBoolean StopTone() { return device.StopTone(lineNumber); }


    virtual OpalLineInterfaceDevice::CallProgressTones DialOut(
      const PString & number,       
      const OpalLineInterfaceDevice::DialParams & params = OpalLineInterfaceDevice::DialParams() 
    ) { return device.DialOut(lineNumber, number, params); }

    OpalLineInterfaceDevice & GetDevice() const { return device; }

    unsigned GetLineNumber() const { return lineNumber; }

    PString GetToken() const { return token; }

    void SetToken(const PString & t) { token = t; }

  protected:
    OpalLineInterfaceDevice & device;
    unsigned                  lineNumber;
    PString                   token;
    PTimeInterval             ringStoppedTime;
    PTimeInterval             ringInterCadenceTime;

    PTimeInterval             ringTick;
    unsigned                  ringCount;
    bool                      lastRingState;
};


PLIST(OpalLineList, OpalLine);


class OpalLIDRegistration : public PCaselessString
{
    PCLASSINFO(OpalLIDRegistration, PCaselessString);
  public:
    OpalLIDRegistration(
      const char * name  
    );

    ~OpalLIDRegistration();

    virtual OpalLineInterfaceDevice * Create(
      void * parameters   
    ) const = 0;

  protected:
    OpalLIDRegistration * link;
    bool                  duplicate;

  friend class OpalLineInterfaceDevice;
};


#define OPAL_REGISTER_LID_FUNCTION(cls, type, param) \
static class cls##_Registration : public OpalLIDRegistration { \
  public: \
    cls##_Registration() : OpalLIDRegistration(type) { } \
    OpalLineInterfaceDevice * Create(void * param) const; \
} instance_##cls##_Registration; \
OpalLineInterfaceDevice * cls##_Registration::Create(void * param) const

#ifndef OPAL_NO_PARAM
#define OPAL_NO_PARAM
#endif

#define OPAL_REGISTER_LID(cls, type) \
  OPAL_REGISTER_LID_FUNCTION(cls, type, OPAL_NO_PARAM) \
  { return new cls; }

#define OPAL_REGISTER_LID_PARAM(cls, type) \
  OPAL_REGISTER_LID_FUNCTION(cls, type, parameter) \
  { return new cls(parameter); }


#endif // OPAL_LIDS_LID_H


// End of File ///////////////////////////////////////////////////////////////