lib/libopenh323/include/vpblid.h

   1 /*
   2  * vpblid.h
   3  *
   4  * Voicetronix VPB4 line interface device
   5  *
   6  * Copyright (c) 1999-2000 Equivalence Pty. Ltd.
   7  *
   8  * The contents of this file are subject to the Mozilla Public License
   9  * Version 1.0 (the "License"); you may not use this file except in
  10  * compliance with the License. You may obtain a copy of the License at
  11  * http://www.mozilla.org/MPL/
  12  *
  13  * Software distributed under the License is distributed on an "AS IS"
  14  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  15  * the License for the specific language governing rights and limitations
  16  * under the License.
  17  *
  18  * The Original Code is Open H323 Library.
  19  *
  20  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  21  *
  22  * Contributor(s): ______________________________________.
  23  *
  24  * $Log: vpblid.h,v $
  25  * Revision 1.17  2005/11/30 13:05:01  csoutheren
  26  * Changed tags for Doxygen
  27  *
  28  * Revision 1.16  2003/08/13 22:02:03  dereksmithies
  29  * Apply patch from Daniel Bichara to GetOSHandle() for VPB devices. Thanks.
  30  *
  31  * Revision 1.15  2003/03/05 06:26:41  robertj
  32  * Added function to play a WAV file to LID, thanks Pietro Ravasio
  33  *
  34  * Revision 1.14  2002/09/16 01:14:15  robertj
  35  * Added #define so can select if #pragma interface/implementation is used on
  36  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  37  *
  38  * Revision 1.13  2002/09/03 06:19:37  robertj
  39  * Normalised the multi-include header prevention ifdef/define symbol.
  40  *
  41  * Revision 1.12  2002/08/05 10:03:47  robertj
  42  * Cosmetic changes to normalise the usage of pragma interface/implementation.
  43  *
  44  * Revision 1.11  2002/07/02 03:20:37  dereks
  45  * Fix check for line disconnected state.   Remove timer on line ringing.
  46  *
  47  * Revision 1.10  2001/11/19 06:35:59  robertj
  48  * Added tone generation handling
  49  *
  50  * Revision 1.9  2001/09/13 05:27:46  robertj
  51  * Fixed incorrect return type in virtual function, thanks Vjacheslav Andrejev
  52  *
  53  * Revision 1.8  2001/02/09 05:16:24  robertj
  54  * Added #pragma interface for GNU C++.
  55  *
  56  * Revision 1.7  2001/01/25 07:27:14  robertj
  57  * Major changes to add more flexible OpalMediaFormat class to normalise
  58  *   all information about media types, especially codecs.
  59  *
  60  * Revision 1.6  2001/01/24 05:34:49  robertj
  61  * Altered volume control range to be percentage, ie 100 is max volume.
  62  *
  63  * Revision 1.5  2000/11/24 10:50:52  robertj
  64  * Modified the ReadFrame/WriteFrame functions to allow for variable length codecs.
  65  *
  66  * Revision 1.4  2000/11/20 04:35:40  robertj
  67  * Changed tone detection API slightly to allow detection of multiple
  68  * simultaneous tones
  69  *
  70  * Revision 1.3  2000/05/02 04:32:25  robertj
  71  * Fixed copyright notice comment.
  72  *
  73  * Revision 1.2  2000/01/07 08:28:09  robertj
  74  * Additions and changes to line interface device base class.
  75  *
  76  * Revision 1.1  1999/12/23 23:02:35  robertj
  77  * File reorganision for separating RTP from H.323 and creation of LID for VPB support.
  78  *
  79  */
  80
  81 #ifndef __OPAL_VPBLID_H
  82 #define __OPAL_VPBLID_H
  83
  84 #ifdef P_USE_PRAGMA
  85 #pragma interface
  86 #endif
  87
  88
  89 #include "lid.h"
  90 #include <vpbapi.h>
  91
  92
  93 ///////////////////////////////////////////////////////////////////////////////
  94 // DR - this thread is needed to keep tones playing indefinately, as VPB
  95 // tones normally end after a defined period.
  96 class ToneThread : public PThread
  97 {
  98   PCLASSINFO(PThread, ToneThread);
  99
 100   public:
 101     ToneThread(int handle, VPB_TONE tone);
 102     ~ToneThread();
 103     void Main();
 104
 105   private:
 106     int        handle;   // VPB handle to play tone on
 107     VPB_TONE   vpbtone;  // tone parameters of tone to play
 108     PSyncPoint shutdown; // used to signal Main() to finish
 109 };
 110
 111
 112 /**This class describes the Voicetronix line interface device.
 113  */
 114 class OpalVpbDevice : public OpalLineInterfaceDevice
 115 {
 116   PCLASSINFO(OpalVpbDevice, OpalLineInterfaceDevice);
 117
 118   public:
 119     /**Create a new, closed, device for a VPB card.
 120       */
 121     OpalVpbDevice();
 122
 123     /**Destroy line interface device.
 124        This calls Close() on the device.
 125       */
 126     ~OpalVpbDevice() { Close(); }
 127
 128     /**Open the device.
 129       */
 130     virtual BOOL Open(
 131       const PString & device      ///<  Device identifier name.
 132     );
 133
 134     /**Close the device.
 135       */
 136     virtual BOOL Close();
 137
 138     /**Get the device name.
 139       */
 140     virtual PString GetName() const;
 141
 142     /**Get the total number of lines supported by this device.
 143       */
 144     virtual unsigned GetLineCount();
 145
 146
 147     /**Determine if line is currently off hook.
 148        This returns TRUE if GetLineState() is a state that implies the line is
 149        off hook (eg OffHook or LineBusy).
 150       */
 151     virtual BOOL IsLineOffHook(
 152       unsigned line   ///<  Number of line
 153     );
 154
 155     /**Set the state of the line.
 156        Note that not be possible on a given line.
 157       */
 158     virtual BOOL SetLineOffHook(
 159       unsigned line,        ///<  Number of line
 160       BOOL newState = TRUE  ///<  New state to set
 161     );
 162
 163
 164     /**Determine if line is ringing.
 165       */
 166     virtual BOOL IsLineRinging(
 167       unsigned line,          ///<  Number of line
 168       DWORD * cadence = NULL  ///<  Cadence of incoming ring
 169     );
 170
 171     /**Determine if line has been disconnected from a call.
 172        return TRUE if a tone is detected.
 173       */
 174     virtual BOOL IsLineDisconnected(
 175       unsigned line,   ///<  Number of line
 176       BOOL checkForWink = TRUE
 177     );
 178
 179     /**Get the media formats this device is capable of using.
 180       */
 181     virtual OpalMediaFormat::List GetMediaFormats() const;
 182
 183     /**Set the codec for reading.
 184       */
 185     virtual BOOL SetReadFormat(
 186       unsigned line,    ///<  Number of line
 187       const OpalMediaFormat & mediaFormat   ///<  Codec type
 188     );
 189
 190     /**Set the codec for writing.
 191       */
 192     virtual BOOL SetWriteFormat(
 193       unsigned line,    ///<  Number of line
 194       const OpalMediaFormat & mediaFormat   ///<  Codec type
 195     );
 196
 197     /**Get the media format (codec) for reading on the specified line.
 198       */
 199     virtual OpalMediaFormat GetReadFormat(
 200       unsigned line    ///<  Number of line
 201     );
 202
 203     /**Get the media format (codec) for writing on the specified line.
 204       */
 205     virtual OpalMediaFormat GetWriteFormat(
 206       unsigned line    ///<  Number of line
 207     );
 208
 209     /**Stop the read codec.
 210       */
 211     virtual BOOL StopReadCodec(
 212       unsigned line   ///<  Number of line
 213     );
 214
 215     /**Stop the write codec.
 216       */
 217     virtual BOOL StopWriteCodec(
 218       unsigned line   ///<  Number of line
 219     );
 220
 221     /**Set the read frame size in bytes.
 222        Note that a LID may ignore this value so always use GetReadFrameSize()
 223        for I/O.
 224       */
 225     virtual BOOL SetReadFrameSize(
 226       unsigned line,    ///<  Number of line
 227       PINDEX frameSize  ///<  New frame size
 228     );
 229
 230     /**Set the write frame size in bytes.
 231        Note that a LID may ignore this value so always use GetReadFrameSize()
 232        for I/O.
 233       */
 234     virtual BOOL SetWriteFrameSize(
 235       unsigned line,    ///<  Number of line
 236       PINDEX frameSize  ///<  New frame size
 237     );
 238
 239     /**Get the read frame size in bytes.
 240        All calls to ReadFrame() will return this number of bytes.
 241       */
 242     virtual PINDEX GetReadFrameSize(
 243       unsigned line   ///<  Number of line
 244     );
 245
 246     /**Get the write frame size in bytes.
 247        All calls to WriteFrame() must be this number of bytes.
 248       */
 249     virtual PINDEX GetWriteFrameSize(
 250       unsigned line   ///<  Number of line
 251     );
 252
 253     /**Low level read of a frame from the device.
 254      */
 255     virtual BOOL ReadFrame(
 256       unsigned line,    ///<  Number of line
 257       void * buf,   ///<  Pointer to a block of memory to receive the read bytes.
 258       PINDEX & count    ///<  Number of bytes read, <= GetReadFrameSize()
 259     );
 260
 261     /**Low level write frame to the device.
 262      */
 263     virtual BOOL WriteFrame(
 264       unsigned line,    ///<  Number of line
 265       const void * buf, ///<  Pointer to a block of memory to write.
 266       PINDEX count,     ///<  Number of bytes to write, <= GetWriteFrameSize()
 267       PINDEX & written  ///<  Number of bytes written, <= GetWriteFrameSize()
 268     );
 269
 270
 271     /**Set volume level for recording.
 272        A value of 100 is the maximum volume possible for the hardware.
 273        A value of 0 is the minimum volume possible for the hardware.
 274       */
 275     virtual BOOL SetRecordVolume(
 276       unsigned line,    ///<  Number of line
 277       unsigned volume   ///<  Volume level from 0 to 100%
 278     );
 279
 280     /**Set volume level for playing.
 281        A value of 100 is the maximum volume possible for the hardware.
 282        A value of 0 is the minimum volume possible for the hardware.
 283       */
 284     virtual BOOL SetPlayVolume(
 285       unsigned line,    ///<  Number of line
 286       unsigned volume   ///<  Volume level from 0 to 100%
 287     );
 288
 289     /**Return line handle
 290       */
 291     int GetOSHandle(
 292       unsigned line     ///<  Number of line
 293     );
 294
 295     /**Read a DTMF digit detected.
 296        This may be characters from the set 0-9, A-D, * or #. A null ('\0')
 297        character indicates that there are no tones in the queue.
 298
 299       */
 300     virtual char ReadDTMF(
 301       unsigned line   ///<  Number of line
 302     );
 303
 304     /**Play a DTMF digit.
 305        Any characters that are not in the set 0-9, A-D, * or # will be ignored.
 306       */
 307     virtual BOOL PlayDTMF(
 308       unsigned line,            ///<  Number of line
 309       const char * digits,      ///<  DTMF digits to be played
 310       DWORD onTime = 90,        ///<  Number of milliseconds to play each DTMF digit
 311       DWORD offTime = 30        ///<  Number of milliseconds between digits
 312     );
 313
 314
 315     /**See if a tone is detected.
 316       */
 317     virtual unsigned IsToneDetected(
 318       unsigned line   ///<  Number of line
 319     );
 320
 321     virtual BOOL PlayTone(
 322       unsigned line,          ///<  Number of line
 323       CallProgressTones tone  ///<  Tone to be played
 324     );
 325
 326     virtual BOOL StopTone(
 327       unsigned line   ///<  Number of line
 328     );
 329
 330     virtual BOOL PlayAudio(
 331       unsigned line,            ///<  Number of line
 332       const PString & filename  ///<  File Name
 333     );
 334
 335     virtual BOOL StopAudio(
 336       unsigned line   ///Number of line
 337     );
 338
 339   protected:
 340     unsigned cardNumber;
 341     unsigned lineCount;
 342
 343     enum { MaxLineCount = 8 };
 344
 345     struct LineState {
 346       BOOL Open(unsigned cardNumber, unsigned lineNumber);
 347       BOOL SetLineOffHook(BOOL newState);
 348       BOOL IsLineRinging(DWORD *);
 349
 350       int        handle;
 351       BOOL       currentHookState;
 352       PINDEX     readFormat,    writeFormat;
 353       PINDEX     readFrameSize, writeFrameSize;
 354       BOOL       readIdle,      writeIdle;
 355       PMutex     DTMFmutex;
 356       BOOL       DTMFplaying;
 357       ToneThread *myToneThread;
 358     } lineState[MaxLineCount];
 359 };
 360
 361
 362 #endif // __OPAL_VPBLID_H
 363
 364
 365 /////////////////////////////////////////////////////////////////////////////