pcss.h

Go to the documentation of this file.

/*
 * pcss.h
 *
 * PC Sound System support.
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 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 Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: pcss.h,v $
 * Revision 2.29  2007/04/03 07:59:13  rjongbloed
 * Warning: API change to PCSS callbacks:
 *   changed return on OnShowIncoming to BOOL, now agrees with
 *     documentation and allows UI to abort calls early.
 *   added BOOL to AcceptIncomingConnection indicating the
 *     supplied token is invalid.
 *   removed redundent OnGetDestination() function, was never required.
 *
 * Revision 2.28  2007/03/13 00:32:16  csoutheren
 * Simple but messy changes to allow compile time removal of protocol
 * options such as H.450 and H.460
 * Fix MakeConnection overrides
 *
 * Revision 2.27  2007/03/01 05:51:04  rjongbloed
 * Fixed backward compatibility of OnIncomingConnection() virtual
 *   functions on various classes. If an old override returned FALSE
 *   then it will now abort the call as it used to.
 *
 * Revision 2.26  2007/01/24 04:00:56  csoutheren
 * Arrrghh. Changing OnIncomingConnection turned out to have a lot of side-effects
 * Added some pure viritual functions to prevent old code from breaking silently
 * New OpalEndpoint and OpalConnection descendants will need to re-implement
 * OnIncomingConnection. Sorry :)
 *
 * Revision 2.25  2006/12/18 03:18:41  csoutheren
 * Messy but simple fixes
 *   - Add access to SIP REGISTER timeout
 *   - Ensure OpalConnection options are correctly progagated
 *
 * Revision 2.24  2006/10/15 06:23:35  rjongbloed
 * Fixed the mechanism where both A-party and B-party are indicated by the application. This now works
 *   for LIDs as well as PC endpoint, wheich is the only one that was used before.
 *
 * Revision 2.23  2006/10/10 07:18:18  csoutheren
 * Allow compilation with and without various options
 *
 * Revision 2.22  2006/08/29 08:47:43  rjongbloed
 * Added functions to get average audio signal level from audio streams in
 *   suitable connection types.
 *
 * Revision 2.21  2006/08/17 23:09:03  rjongbloed
 * Added volume controls
 *
 * Revision 2.20  2006/06/21 04:54:15  csoutheren
 * Fixed build with latest PWLib
 *
 * Revision 2.19  2005/12/28 20:03:00  dsandras
 * Attach the silence detector in OnPatchMediaStream so that it can be attached
 * before the echo cancellation filter.
 *
 * Revision 2.18  2005/12/27 22:25:55  dsandras
 * Added propagation of the callback to the pcss endpoint.
 *
 * Revision 2.17  2005/12/27 20:48:01  dsandras
 * Added media format parameter when opening the sound channel so that its
 * parameters can be used in the body of the method.
 *
 * Revision 2.16  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.15  2005/11/24 20:31:54  dsandras
 * Added support for echo cancelation using Speex.
 * Added possibility to add a filter to an OpalMediaPatch for all patches of a connection.
 *
 * Revision 2.14  2005/10/12 21:11:21  dsandras
 * Control if the video streams are started or not from this class.
 *
 * Revision 2.13  2004/08/14 07:56:29  rjongbloed
 * Major revision to utilise the PSafeCollection classes for the connections and calls.
 *
 * Revision 2.12  2004/07/11 12:42:10  rjongbloed
 * Added function on endpoints to get the list of all media formats any
 *   connection the endpoint may create can support.
 *
 * Revision 2.11  2004/05/17 13:24:18  rjongbloed
 * Added silence suppression.
 *
 * Revision 2.10  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.9  2003/03/17 10:11:05  robertj
 * Added call back functions for creating sound channel.
 * Added video support.
 *
 * Revision 2.8  2003/03/06 03:57:47  robertj
 * IVR support (work in progress) requiring large changes everywhere.
 *
 * Revision 2.7  2002/09/16 02:52:35  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 2.6  2002/06/16 02:19:31  robertj
 * Fixed and clarified function for initiating call, thanks Ted Szoczei
 *
 * Revision 2.5  2002/01/22 05:05:16  robertj
 * Revamp of user input API triggered by RFC2833 support
 *
 * Revision 2.4  2001/11/13 06:25:56  robertj
 * Changed SetUpConnection() so returns BOOL as returning
 *   pointer to connection is not useful.
 *
 * Revision 2.3  2001/10/15 04:29:26  robertj
 * Removed answerCall signal and replaced with state based functions.
 *
 * Revision 2.2  2001/08/17 08:33:38  robertj
 * More implementation.
 *
 * Revision 2.1  2001/08/01 05:52:24  robertj
 * Moved media formats list from endpoint to connection.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_PCSS_H
#define __OPAL_PCSS_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptbuildopts.h>

#ifndef P_AUDIO
#warning "PTLib soundcard support not available"
#else

#include <ptlib/sound.h>
#include <opal/buildopts.h>
#include <opal/endpoint.h>

class OpalPCSSConnection;


class OpalPCSSEndPoint : public OpalEndPoint
{
    PCLASSINFO(OpalPCSSEndPoint, OpalEndPoint);
  public:
    OpalPCSSEndPoint(
      OpalManager & manager,  
      const char * prefix = "pc" 
    );

    ~OpalPCSSEndPoint();

    virtual BOOL MakeConnection(
      OpalCall & call,           
      const PString & party,     
      void * userData = NULL,    
      unsigned int options = 0,  
      OpalConnection::StringOptions * stringOptions  = NULL
    );

    virtual OpalMediaFormatList GetMediaFormats() const;

    virtual OpalPCSSConnection * CreateConnection(
      OpalCall & call,    
      const PString & playDevice, 
      const PString & recordDevice, 
      void * userData     
    );

    virtual PSoundChannel * CreateSoundChannel(
      const OpalPCSSConnection & connection, 
      const OpalMediaFormat & mediaFormat,   
      BOOL isSource                          
    );

    PSafePtr<OpalPCSSConnection> GetPCSSConnectionWithLock(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite
    ) { return PSafePtrCast<OpalConnection, OpalPCSSConnection>(GetConnectionWithLock(token, mode)); }

    virtual BOOL OnShowIncoming(
      const OpalPCSSConnection & connection 
    ) = 0;

    virtual BOOL AcceptIncomingConnection(
      const PString & connectionToken 
    );

    virtual BOOL OnShowOutgoing(
      const OpalPCSSConnection & connection 
    ) = 0;

    virtual BOOL OnShowUserInput(
      const OpalPCSSConnection & connection, 
      const PString & indication
    );

    
    virtual void OnPatchMediaStream(
      const OpalPCSSConnection & connection, 
      BOOL isSource,                         
      OpalMediaPatch & patch                 
    );

    virtual BOOL SetSoundChannelPlayDevice(const PString & name);

    const PString & GetSoundChannelPlayDevice() const { return soundChannelPlayDevice; }

    virtual BOOL SetSoundChannelRecordDevice(const PString & name);

    const PString & GetSoundChannelRecordDevice() const { return soundChannelRecordDevice; }

    unsigned GetSoundChannelBufferDepth() const { return soundChannelBuffers; }

    void SetSoundChannelBufferDepth(
      unsigned depth    
    );


  protected:
    PString  soundChannelPlayDevice;
    PString  soundChannelRecordDevice;
    unsigned soundChannelBuffers;
};


class OpalPCSSConnection : public OpalConnection
{
    PCLASSINFO(OpalPCSSConnection, OpalConnection);
  public:
    OpalPCSSConnection(
      OpalCall & call,              
      OpalPCSSEndPoint & endpoint,  
      const PString & playDevice,   
      const PString & recordDevice  
    );

    ~OpalPCSSConnection();

    virtual BOOL SetUpConnection();

    virtual BOOL SetAlerting(
      const PString & calleeName,   
      BOOL withMedia                
    );

    virtual BOOL SetConnected();

    virtual OpalMediaFormatList GetMediaFormats() const;

    virtual OpalMediaStream * CreateMediaStream(
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      BOOL isSource                        
    );

    virtual void OnPatchMediaStream(
      BOOL isSource,
      OpalMediaPatch & patch    
    );

    virtual BOOL OpenSourceMediaStream(
      const OpalMediaFormatList & mediaFormats, 
      unsigned sessionID                   
    );

    virtual OpalMediaStream * OpenSinkMediaStream(
      OpalMediaStream & source    
    );

    virtual BOOL SetAudioVolume(
      BOOL source,                  
      unsigned percentage           
    );

    virtual unsigned GetAudioSignalLevel(
      BOOL source                   
    );

    virtual BOOL SendUserInputString(
      const PString & value                   
    );

    virtual void AcceptIncoming();

    virtual PSoundChannel * CreateSoundChannel(
      const OpalMediaFormat & mediaFormat, 
      BOOL isSource                        
    );

    const PString & GetSoundChannelPlayDevice() const { return soundChannelPlayDevice; }

    const PString & GetSoundChannelRecordDevice() const { return soundChannelRecordDevice; }

    unsigned GetSoundChannelBufferDepth() const { return soundChannelBuffers; }


  protected:
    OpalPCSSEndPoint & endpoint;
    PString            soundChannelPlayDevice;
    PString            soundChannelRecordDevice;
    unsigned           soundChannelBuffers;
};

#endif // P_AUDIO

#endif // __OPAL_PCSS_H


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

---