include/vblasterlid.h

   1 /*
   2  * vblasterlid.h
   3  *
   4  * Creative Labs VOIP Blaster codec interface
   5  *
   6  * Open H323 Library
   7  *
   8  * Copyright (c) 2001 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Open H323 Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Contributor(s): ______________________________________.
  25  *
  26  * $Log$
  27  * Revision 1.8  2005/11/30 13:05:01  csoutheren
  28  * Changed tags for Doxygen
  29  *
  30  * Revision 1.7  2003/12/03 06:58:30  csoutheren
  31  * More vblaster implementation
  32  *
  33  * Revision 1.6  2003/11/10 12:37:46  csoutheren
  34  * Additional fixes for Fobbit Windows driver
  35  *
  36  * Revision 1.5  2002/09/16 01:14:15  robertj
  37  * Added #define so can select if #pragma interface/implementation is used on
  38  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  39  *
  40  * Revision 1.4  2002/09/03 06:19:37  robertj
  41  * Normalised the multi-include header prevention ifdef/define symbol.
  42  *
  43  * Revision 1.3  2002/08/05 10:03:47  robertj
  44  * Cosmetic changes to normalise the usage of pragma interface/implementation.
  45  *
  46  * Revision 1.2  2002/01/15 07:23:24  craigs
  47  * Added IsDevicePresent command
  48  *
  49  * Revision 1.1  2002/01/15 04:16:32  craigs
  50  * Initial version
  51  *
  52  *
  53  */
  54
  55 #ifndef __OPAL_VBLASTERLID_H
  56 #define __OPAL_VBLASTERLID_H
  57
  58 #ifdef P_USE_PRAGMA
  59 #pragma interface
  60 #endif
  61
  62
  63 #define HAS_VBLASTER
  64
  65 #include "lid.h"
  66 #include "h323caps.h"
  67
  68 #include <ptclib/delaychan.h>
  69
  70
  71
  72 ///////////////////////////////////////////////////////////////////////////////
  73
  74 class VoipBlasterInterface : public PObject
  75 {
  76   PCLASSINFO(VoipBlasterInterface, PObject)
  77   public:
  78     enum Command {
  79       Command_PHONE_OFF  = 0x01, // drop loop current
  80       Command_PHONE_ON   = 0x02, // used on startup
  81       Command_RING_ON    = 0x03, // start ringing
  82       Command_RING_OFF   = 0x04, // used on startup & to stop ringing
  83       Command_VOUT_START = 0x05, // start audio output
  84       Command_VOUT_STOP  = 0x06, // stop audio output
  85       Command_VINP_START = 0x07, // start audio input
  86       Command_VINP_STOP  = 0x08, // stop audio input
  87       Command_UNKNOWN_1  = 0x09, // Unknown (TESTSTART)
  88       Command_UNKNOWN_2  = 0x0a, // Unknown (TESTSTOP)
  89       Command_UNKNOWN_3  = 0x0b, // Unknown (SENDFAXTONE)
  90       Command_HS_OFFHOOK = 0x0c, // Go offhook for headset
  91       Command_HS_ONHOOK  = 0x0d, // Go onhook for headset
  92       Command_SETUP_MODE = 0x0e, // Unknown(goto setup mode)
  93       Command_VOUT_DONE  = 0x0f, // voice in/out off, report output drained
  94       Command_0x10       = 0x10, // Unknown (used in file output, seems ok without)
  95       Command_0x11       = 0x11, // Unknown (used in file output, seems ok without)
  96       Command_MUTE_ON    = 0x12, // Audio mute on
  97       Command_MUTE_OFF   = 0x13, // Audio mute off
  98       Command_VOL_0      = 0x34, // Set volume (min)
  99       Command_VOL_1      = 0x35, // Set volume
 100       Command_VOL_2      = 0x36, // Set volume
 101       Command_VOL_3      = 0x37, // Set volume (default)
 102       Command_VOL_4      = 0x38, // Set volume
 103       Command_VOL_5      = 0x39, // Set volume
 104       Command_VOL_6      = 0x3a, // Set volume (max)
 105     };
 106
 107     enum Status {
 108       //Status_NONE        = 0x00, // No status
 109       Status_HOOK_OFF    = 0x01, // Offhook
 110       Status_HOOK_ON     = 0x02, // Onhook
 111       //Status_DEBUG       = 0x03, // Not used (DEBUG)
 112       //Status_RINGDETECT  = 0x04, // Not used (RINGDETECT)
 113       Status_RINGING_ON  = 0x05, // Ring started
 114       Status_RINGING_OFF = 0x06, // Ring stopped
 115       Status_HEADSET_IN  = 0x08, // Headset plugged in
 116       Status_HEADSET_OUT = 0x09, // Headset unplugged
 117       Status_0x0a        = 0x0a, // Unknown (setup accepted?)
 118       Status_VOUT_DONE   = 0x0c, // Voice output done
 119       Status_Empty
 120     };
 121
 122     VoipBlasterInterface();
 123
 124     BOOL IsDevicePresent(PINDEX deviceIndex);
 125
 126     BOOL OpenCommand(PINDEX deviceIndex);
 127     BOOL WriteCommand(Command cmd);
 128     Status ReadStatus(const PTimeInterval dur = 0);
 129     BOOL CloseCommand();
 130
 131     BOOL OpenData();
 132     BOOL WriteData(const void * data, PINDEX len);
 133     int  ReadData (void * data,       PINDEX len, const PTimeInterval dur = 0);
 134     void Flush(const PTimeInterval wait = 500);
 135     BOOL CloseData();
 136
 137     PDECLARE_NOTIFIER(PTimer, VoipBlasterInterface, CloseTimeout);
 138
 139   protected:
 140     PINDEX deviceIndex;
 141
 142 // Linux specific defines are included here
 143 #ifdef P_LINUX
 144 #endif
 145
 146 // Windows specific defines are included here
 147 #ifdef _WIN32
 148     enum Pipe {
 149       VoiceOutPipe = 0,
 150       VoiceInPipe  = 1,
 151       CommandPipe  = 2,
 152       StatusPipe   = 3,
 153       NumPipes
 154     };
 155
 156   protected:
 157     int WritePipe(HANDLE fd, const void *bp, DWORD len);
 158     int ReadPipe (HANDLE fd, void *bp,       DWORD len, const PTimeInterval dur = 0);
 159     BOOL OpenVOIPPipe(Pipe pipeIndex);
 160
 161     HANDLE pipes[4];
 162 #endif
 163 };
 164
 165 ///////////////////////////////////////////////////////////////////////////////
 166
 167 /**This class describes the VoIPBlaster line interface device.
 168  */
 169 class OpalVoipBlasterDevice : public OpalLineInterfaceDevice
 170 {
 171   PCLASSINFO(OpalVoipBlasterDevice, OpalLineInterfaceDevice);
 172
 173   public:
 174
 175     enum { DTMFQueueSize = 10 };
 176
 177     class ByteQueue : public PObject {
 178       PCLASSINFO(ByteQueue, PObject);
 179       public:
 180         ByteQueue(PINDEX size);
 181         int Dequeue();
 182         BOOL Enqueue(BYTE ch);
 183
 184       protected:
 185         PBYTEArray queue;
 186         PINDEX qLen, qOut, qMax;
 187         PMutex mutex;
 188     };
 189
 190     /**Create a new, closed, device for a VoipBlaster device.
 191       */
 192     OpalVoipBlasterDevice();
 193
 194     /**Destroy line interface device.
 195        This calls Close() on the device.
 196       */
 197     ~OpalVoipBlasterDevice();
 198
 199     /**Open the VoIPBlaster device.
 200       */
 201     virtual BOOL Open(
 202       const PString & device  ///<  Device identifier name.
 203     );
 204
 205     /**Close the VoIPBlaster device.
 206       */
 207     virtual BOOL Close();
 208
 209     /**Get the device name.
 210       */
 211     virtual PString GetName() const;
 212
 213     /**Get the total number of lines supported by this device.
 214       */
 215     virtual unsigned GetLineCount()
 216       { return 1; }
 217
 218     /**Get the type of the line.
 219       */
 220     virtual BOOL IsLineTerminal(
 221       unsigned /*line*/   ///<  Number of line
 222     ) { return TRUE; }
 223
 224
 225     /**Determine if a physical line is present on the logical line.
 226       */
 227     virtual BOOL IsLinePresent(
 228       unsigned /*line*/,      ///<  Number of line
 229       BOOL /*force*/ = FALSE  ///<  Force test, do not optimise
 230     )
 231       { return FALSE; }
 232
 233
 234     /**Determine if line is currently off hook.
 235        This returns TRUE if GetLineState() is a state that implies the line is
 236        off hook (eg OffHook or LineBusy).
 237       */
 238     virtual BOOL IsLineOffHook(
 239       unsigned line   ///<  Number of line
 240     );
 241
 242     /**Set the state of the line.
 243        Note that not be possible on a given line.
 244       */
 245     virtual BOOL SetLineOffHook(
 246       unsigned line,        ///<  Number of line
 247       BOOL newState = TRUE  ///<  New state to set
 248     );
 249
 250
 251     /**Determine if line is ringing.
 252       */
 253     virtual BOOL IsLineRinging(
 254       unsigned line,          ///<  Number of line
 255       DWORD * cadence = NULL  ///<  Cadence of incoming ring
 256     );
 257
 258     /**Begin ringing local phone set with specified cadence.
 259        If cadence is zero then stops ringing.
 260       */
 261     virtual BOOL RingLine(
 262       unsigned line,    ///<  Number of line
 263       DWORD cadence     ///<  Cadence bit map for ring pattern
 264     );
 265
 266
 267     /**Determine if line has been disconnected from a call.
 268       */
 269     virtual BOOL IsLineDisconnected(
 270       unsigned line,   ///<  Number of line
 271       BOOL checkForWink = TRUE
 272     );
 273
 274
 275     /**Directly connect the two lines.
 276       */
 277     BOOL SetLineToLineDirect(
 278       unsigned line1,   ///<  Number of first line
 279       unsigned line2,   ///<  Number of second line
 280       BOOL connect      ///<  Flag for connect/disconnect
 281     );
 282
 283     /**Determine if the two lines are directly connected.
 284       */
 285     BOOL IsLineToLineDirect(
 286       unsigned line1,   ///<  Number of first line
 287       unsigned line2    ///<  Number of second line
 288     );
 289
 290
 291     /**Get the media formats this device is capable of using.
 292       */
 293     virtual OpalMediaFormat::List GetMediaFormats() const;
 294
 295     /**Set the VoIPBlaster codec for reading.
 296       */
 297     virtual BOOL SetReadFormat(
 298       unsigned line,    ///<  Number of line
 299       const OpalMediaFormat & mediaFormat   ///<  Codec type
 300     );
 301
 302     /**Set the VoIPBlaster codec for writing.
 303       */
 304     virtual BOOL SetWriteFormat(
 305       unsigned line,    ///<  Number of line
 306       const OpalMediaFormat & mediaFormat   ///<  Codec type
 307     );
 308
 309     /**Get the media format (codec) for reading on the specified line.
 310       */
 311     virtual OpalMediaFormat GetReadFormat(
 312       unsigned line    ///<  Number of line
 313     );
 314
 315     /**Get the media format (codec) for writing on the specified line.
 316       */
 317     virtual OpalMediaFormat GetWriteFormat(
 318       unsigned line    ///<  Number of line
 319     );
 320
 321     /**Set the line codec for reading/writing raw PCM data.
 322        A descendent may use this to do anything special to the device before
 323        beginning special PCM output. For example disabling AEC and set
 324        volume levels to standard values. This can then be used for generating
 325        standard tones using PCM if the driver is not capable of generating or
 326        detecting them directly.
 327
 328        The default behaviour simply does a SetReadCodec and SetWriteCodec for
 329        PCM data.
 330       */
 331     virtual BOOL SetRawCodec(
 332       unsigned line    ///<  Number of line
 333     );
 334
 335     /**Stop the raw PCM mode codec.
 336       */
 337     virtual BOOL StopRawCodec(
 338       unsigned line   ///<  Number of line
 339     );
 340
 341     /**Stop the read codec.
 342       */
 343     virtual BOOL StopReadCodec(
 344       unsigned line   ///<  Number of line
 345     );
 346
 347     /**Stop the write codec.
 348       */
 349     virtual BOOL StopWriteCodec(
 350       unsigned line   ///<  Number of line
 351     );
 352
 353     /**Get the read frame size in bytes.
 354        All calls to ReadFrame() will return this number of bytes.
 355       */
 356     virtual PINDEX GetReadFrameSize(
 357       unsigned line   ///<  Number of line
 358     );
 359
 360     virtual BOOL SetReadFrameSize(unsigned, PINDEX);
 361
 362     /**Get the write frame size in bytes.
 363        All calls to WriteFrame() must be this number of bytes.
 364       */
 365     virtual PINDEX GetWriteFrameSize(
 366       unsigned line   ///<  Number of line
 367     );
 368
 369     virtual BOOL SetWriteFrameSize(unsigned, PINDEX);
 370
 371     /**Low level read of a frame from the device.
 372      */
 373     virtual BOOL ReadFrame(
 374       unsigned line,    ///<  Number of line
 375       void * buf,       ///<  Pointer to a block of memory to receive data.
 376       PINDEX & count    ///<  Number of bytes read, <= GetReadFrameSize()
 377     );
 378
 379     /**Low level write frame to the device.
 380      */
 381     virtual BOOL WriteFrame(
 382       unsigned line,    ///<  Number of line
 383       const void * buf, ///<  Pointer to a block of memory to write.
 384       PINDEX count,     ///<  Number of bytes to write, <= GetWriteFrameSize()
 385       PINDEX & written  ///<  Number of bytes written, <= GetWriteFrameSize()
 386     );
 387
 388     /**Get average signal level in last frame.
 389       */
 390     virtual unsigned GetAverageSignalLevel(
 391       unsigned line,  ///<  Number of line
 392       BOOL playback   ///<  Get average playback or record level.
 393     );
 394
 395
 396     /**Enable audio for the line.
 397       */
 398     virtual BOOL EnableAudio(
 399       unsigned line,      ///<  Number of line
 400       BOOL enable = TRUE
 401     );
 402
 403
 404     /**Set volume level for recording.
 405        A value of 100 is the maximum volume possible for the hardware.
 406        A value of 0 is the minimum volume possible for the hardware.
 407       */
 408     virtual BOOL SetRecordVolume(
 409       unsigned line,    ///<  Number of line
 410       unsigned volume   ///<  Volume level from 0 to 100%
 411     );
 412
 413     /**Set volume level for playing.
 414        A value of 100 is the maximum volume possible for the hardware.
 415        A value of 0 is the minimum volume possible for the hardware.
 416       */
 417     virtual BOOL SetPlayVolume(
 418       unsigned line,    ///<  Number of line
 419       unsigned volume   ///<  Volume level from 0 to 100%
 420     );
 421
 422     /**Get volume level for recording.
 423        A value of 100 is the maximum volume possible for the hardware.
 424        A value of 0 is the minimum volume possible for the hardware.
 425       */
 426     virtual BOOL GetRecordVolume(
 427       unsigned line,      ///<  Number of line
 428       unsigned & volume   ///<  Volume level from 0 to 100%
 429     );
 430
 431     /**Set volume level for playing.
 432        A value of 100 is the maximum volume possible for the hardware.
 433        A value of 0 is the minimum volume possible for the hardware.
 434       */
 435     virtual BOOL GetPlayVolume(
 436       unsigned line,      ///<  Number of line
 437       unsigned & volume   ///<  Volume level from 0 to 100%
 438     );
 439
 440
 441     /**Set acoustic echo cancellation.
 442       */
 443     AECLevels GetAEC(
 444       unsigned line    ///<  Number of line
 445     );
 446
 447     /**Set acoustic echo cancellation.
 448       */
 449     BOOL SetAEC(
 450       unsigned line,    ///<  Number of line
 451       AECLevels level  ///<  AEC level
 452     );
 453
 454
 455     /**Get voice activity detection.
 456        Note, not all devices, or selected codecs, may support this function.
 457       */
 458     virtual BOOL GetVAD(
 459       unsigned line    ///<  Number of line
 460     );
 461
 462     /**Set voice activity detection.
 463        Note, not all devices, or selected codecs, may support this function.
 464       */
 465     virtual BOOL SetVAD(
 466       unsigned line,    ///<  Number of line
 467       BOOL enable       ///<  Flag for enabling VAD
 468     );
 469
 470
 471     /**Get Caller ID from the last incoming ring.
 472        The idString parameter is either simply the "number" field of the caller
 473        ID data, or if full is TRUE, all of the fields in the caller ID data.
 474
 475        The full data of the caller ID string consists of the number field, the
 476        time/date and the name field separated by tabs ('\t').
 477       */
 478     virtual BOOL GetCallerID(
 479       unsigned line,      ///<  Number of line
 480       PString & idString, ///<  ID string returned
 481       BOOL full = FALSE   ///<  Get full information in idString
 482     );
 483
 484     /**Set Caller ID for use in next RingLine() call.
 485        The full data of the caller ID string consists of the number field, the
 486        time/date and the name field separated by tabs ('\t').
 487
 488        If the date field is missing (two consecutive tabs) then the current
 489        time and date is used. Using an empty string will clear the caller ID
 490        so that no caller ID is sent on the next RingLine() call.
 491       */
 492     virtual BOOL SetCallerID(
 493       unsigned line,            ///<  Number of line
 494       const PString & idString  ///<  ID string to use
 495     );
 496
 497     /**Send Caller ID during call
 498      */
 499     virtual BOOL SendCallerIDOnCallWaiting(
 500       unsigned line,            ///<  Number of line
 501       const PString & idString  ///<  ID string to use
 502     );
 503
 504     /**Send a Visual Message Waiting Indicator
 505       */
 506     virtual BOOL SendVisualMessageWaitingIndicator(
 507       unsigned line,            ///<  Number of line
 508       BOOL on
 509     );
 510
 511
 512
 513     /**Play a DTMF digit.
 514        Any characters that are not in the set 0-9, A-D, * or # will be ignored.
 515       */
 516     virtual BOOL PlayDTMF(
 517       unsigned line,            ///<  Number of line
 518       const char * digits,      ///<  DTMF digits to be played
 519       DWORD onTime = DefaultDTMFOnTime,  ///<  Number of milliseconds to play each DTMF digit
 520       DWORD offTime = DefaultDTMFOffTime ///<  Number of milliseconds between digits
 521     );
 522
 523     /**Read a DTMF digit detected.
 524        This may be characters from the set 0-9, A-D, * or #. A null ('\0')
 525        character indicates that there are no tones in the queue.
 526
 527       */
 528     virtual char ReadDTMF(
 529       unsigned line   ///<  Number of line
 530     );
 531
 532     /**Get DTMF removal mode.
 533        When set in this mode the DTMF tones detected are removed from the
 534        encoded data stream as returned by ReadFrame().
 535       */
 536     virtual BOOL GetRemoveDTMF(
 537       unsigned line            ///<  Number of line
 538     );
 539
 540     /**Set DTMF removal mode.
 541        When set in this mode the DTMF tones detected are removed from the
 542        encoded data stream as returned by ReadFrame().
 543       */
 544     virtual BOOL SetRemoveDTMF(
 545       unsigned line,            ///<  Number of line
 546       BOOL removeTones   ///<  Flag for removing DTMF tones.
 547     );
 548
 549
 550     /**See if a tone is detected.
 551       */
 552     virtual unsigned IsToneDetected(
 553       unsigned line   ///<  Number of line
 554     );
 555
 556     /**Play a tone.
 557       */
 558     virtual BOOL PlayTone(
 559       unsigned line,          ///<  Number of line
 560       CallProgressTones tone  ///<  Tone to be played
 561     );
 562
 563     /**Determine if a tone is still playing
 564       */
 565     virtual BOOL IsTonePlaying(
 566       unsigned line   ///<  Number of line
 567     );
 568
 569     /**Stop playing a tone.
 570       */
 571     virtual BOOL StopTone(
 572       unsigned line   ///<  Number of line
 573     );
 574
 575    /**Return TRUE if a hook flash has been detected
 576       */
 577     virtual BOOL HasHookFlash(unsigned line);
 578
 579     /**Set the country code set for the device.
 580        This may change the line analogue coefficients, ring detect, call
 581        disconnect detect and call progress tones to fit the countries
 582        telephone network.
 583       */
 584     virtual BOOL SetCountryCode(
 585       T35CountryCodes country   ///<  COuntry code for device
 586     );
 587
 588
 589     /**Get the serial number for the VoIPBlaster card.
 590       */
 591     virtual DWORD GetSerialNumber();
 592
 593     /**Get all the VoIPBlaster devices.
 594       */
 595     static PStringArray GetDeviceNames();
 596
 597     /**
 598       * entry point for status handler thread
 599       */
 600     PDECLARE_NOTIFIER(PThread, OpalVoipBlasterDevice, StatusHandler);
 601
 602   protected:
 603     void HandleStatus(int status);
 604
 605     PThread * statusThread;
 606     BOOL statusRunning;
 607     BOOL hookState;
 608     BOOL headset;
 609     BOOL ringOn;
 610     BOOL firstTime;
 611
 612     ByteQueue dtmfQueue;
 613
 614     PAdaptiveDelay writeDelay;
 615     PAdaptiveDelay readDelay;
 616
 617     PString   deviceName;
 618     PMutex    readMutex, writeMutex;
 619     BOOL      readStopped, writeStopped;
 620     PINDEX    readFrameSize, writeFrameSize;
 621     PINDEX    readCodecType, writeCodecType;
 622     BOOL      lastHookStatus;
 623
 624     PMutex               vbMutex;
 625     VoipBlasterInterface vBlaster;
 626 };
 627
 628
 629 #endif // __OPAL_VBLASTERLID_H
 630
 631
 632 /////////////////////////////////////////////////////////////////////////////