endpoint.h

Go to the documentation of this file.

/*
 * endpoint.h
 *
 * Telephony endpoint abstraction
 *
 * 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: endpoint.h,v $
 * Revision 2.50  2007/09/21 01:34:09  rjongbloed
 * Rewrite of SIP transaction handling to:
 *   a) use PSafeObject and safe collections
 *   b) only one database of transactions, remove connection copy
 *   c) fix timers not always firing due to bogus deadlock avoidance
 *   d) cleaning up only occurs in the existing garbage collection thread
 *   e) use of read/write mutex on endpoint list to avoid possible deadlock
 *
 * Revision 2.49  2007/06/29 06:59:56  rjongbloed
 * Major improvement to the "product info", normalising H.221 and User-Agent mechanisms.
 *
 * Revision 2.48  2007/05/15 07:26:38  csoutheren
 * Remove deprecated  interface to STUN server in H323Endpoint
 * Change UseNATForIncomingCall to IsRTPNATEnabled
 * Various cleanups of messy and unused code
 *
 * Revision 2.47  2007/05/15 05:24:50  csoutheren
 * Add UseNATForIncomingCall override so applications can optionally implement their own NAT activation strategy
 *
 * Revision 2.46  2007/03/29 23:55:46  rjongbloed
 * Tidied some code when a new connection is created by an endpoint. Now
 *   if someone needs to derive a connection class they can create it without
 *   needing to remember to do any more than the new.
 *
 * Revision 2.45  2007/03/21 06:15:57  rjongbloed
 * Added functions to find an active comms listener for an interface,
 *    and remove/stop it.
 *
 * Revision 2.44  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.43  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.42  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.41  2007/01/23 00:59:40  csoutheren
 * Fix problem with providing backwards compatible overrides for OpalEndpoint::MakeConnection
 *
 * Revision 2.40  2007/01/18 04:45:16  csoutheren
 * Messy, but simple change to add additional options argument to OpalConnection constructor
 * This allows the provision of non-trivial arguments for connections
 *
 * Revision 2.39  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.38  2006/12/08 05:10:43  csoutheren
 * Applied 1608002 - Callback for OpalTransportUDP multiple interface handling
 * Thanks to Hannes Friederich
 *
 * Revision 2.37  2006/11/20 03:37:12  csoutheren
 * Allow optional inclusion of RTP aggregation
 *
 * Revision 2.36  2006/11/19 06:02:57  rjongbloed
 * Moved function that reads User Input into a destination address to
 *   OpalManager so can be easily overidden in applications.
 *
 * Revision 2.35  2006/10/10 07:18:18  csoutheren
 * Allow compilation with and without various options
 *
 * Revision 2.34  2006/09/28 07:42:17  csoutheren
 * Merge of useful SRTP implementation
 *
 * Revision 2.33  2006/08/21 05:29:25  csoutheren
 * Messy but relatively simple change to add support for secure (SSL/TLS) TCP transport
 * and secure H.323 signalling via the sh323 URL scheme
 *
 * Revision 2.32  2006/05/30 04:58:06  csoutheren
 * Added suport for SIP INFO message (untested as yet)
 * Fixed some issues with SIP state machine on answering calls
 * Fixed some formatting issues
 *
 * Revision 2.31  2006/04/20 16:52:22  hfriederich
 * Adding support for H.224/H.281
 *
 * Revision 2.30  2006/02/22 10:40:09  csoutheren
 * Added patch #1374583 from Frederic Heem
 * Added additional H.323 virtual function
 *
 * Revision 2.29  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.28  2005/10/08 19:26:37  dsandras
 * Added OnForwarded callback in case of call forwarding.
 *
 * Revision 2.27  2005/08/24 10:43:51  rjongbloed
 * Changed create video functions yet again so can return pointers that are not to be deleted.
 *
 * Revision 2.26  2005/08/23 12:45:09  rjongbloed
 * Fixed creation of video preview window and setting video grab/display initial frame size.
 *
 * Revision 2.25  2005/07/14 08:51:18  csoutheren
 * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
 * to do the same thing
 * Fixed problems with logic associated with media bypass
 *
 * Revision 2.24  2005/07/11 06:52:16  csoutheren
 * Added support for outgoing calls using external RTP
 *
 * Revision 2.23  2005/07/11 01:52:23  csoutheren
 * Extended AnsweringCall to work for SIP as well as H.323
 * Fixed problems with external RTP connection in H.323
 * Added call to OnClosedMediaStream
 *
 * Revision 2.22  2005/04/10 20:45:22  dsandras
 * Added callback that is called when a connection is put on hold (locally or remotely).
 *
 * Revision 2.21  2004/08/14 07:56:29  rjongbloed
 * Major revision to utilise the PSafeCollection classes for the connections and calls.
 *
 * Revision 2.20  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.19  2004/04/26 06:30:32  rjongbloed
 * Added ability to specify more than one defualt listener for an endpoint,
 *   required by SIP which listens on both UDP and TCP.
 *
 * Revision 2.18  2004/03/13 06:25:52  rjongbloed
 * Slight rearrangement of local party name and alias list to beter match common
 *   behaviour in ancestor.
 * Abstracted local party name for endpoint into ancestor from H.,323.
 *
 * Revision 2.17  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.16  2004/02/19 10:46:44  rjongbloed
 * Merged OpenH323 version 1.13.1 changes.
 *
 * Revision 2.15  2003/03/17 10:26:59  robertj
 * Added video support.
 *
 * Revision 2.14  2003/03/06 03:57:47  robertj
 * IVR support (work in progress) requiring large changes everywhere.
 *
 * Revision 2.13  2002/11/10 11:33:17  robertj
 * Updated to OpenH323 v1.10.3
 *
 * Revision 2.12  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.11  2002/07/04 07:41:47  robertj
 * Fixed memory/thread leak of transports.
 *
 * Revision 2.10  2002/07/01 04:56:30  robertj
 * Updated to OpenH323 v1.9.1
 *
 * Revision 2.9  2002/04/05 10:36:53  robertj
 * Rearranged OnRelease to remove the connection from endpoints connection
 *   list at the end of the release phase rather than the beginning.
 *
 * Revision 2.8  2002/01/22 05:04:40  robertj
 * Revamp of user input API triggered by RFC2833 support
 *
 * Revision 2.7  2001/11/14 01:31:55  robertj
 * Corrected placement of adjusting media format list.
 *
 * Revision 2.6  2001/11/13 06:25:56  robertj
 * Changed SetUpConnection() so returns BOOL as returning
 *   pointer to connection is not useful.
 *
 * Revision 2.5  2001/08/23 05:51:17  robertj
 * Completed implementation of codec reordering.
 *
 * Revision 2.4  2001/08/22 10:20:09  robertj
 * Changed connection locking to use double mutex to guarantee that
 *   no threads can ever deadlock or access deleted connection.
 *
 * Revision 2.3  2001/08/17 08:22:23  robertj
 * Moved call end reasons enum from OpalConnection to global.
 *
 * Revision 2.2  2001/08/01 05:26:35  robertj
 * Moved media formats list from endpoint to connection.
 *
 * Revision 2.1  2001/07/30 07:22:25  robertj
 * Abstracted listener management from H.323 to OpalEndPoint class.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_ENDPOINT_H
#define __OPAL_ENDPOINT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <opal/manager.h>
#include <opal/mediafmt.h>
#include <opal/transports.h>

class OpalCall;
class OpalMediaStream;
class OpalH224Handler;
class OpalH281Handler;


class OpalEndPoint : public PObject
{
    PCLASSINFO(OpalEndPoint, PObject);
  public:
    enum Attributes {
      CanTerminateCall = 1,
      HasLineInterface = 2
    };

    OpalEndPoint(
      OpalManager & manager,          
      const PCaselessString & prefix, 
      unsigned attributes             
    );

    ~OpalEndPoint();

    void PrintOn(
      ostream & strm    
    ) const;

    BOOL StartListeners(
      const PStringArray & interfaces 
    );

    BOOL StartListener(
      const OpalTransportAddress & iface 
    );

    BOOL StartListener(
      OpalListener * listener 
    );

    virtual PStringArray GetDefaultListeners() const;

    OpalListener * FindListener(
        const OpalTransportAddress & iface 
    );

    BOOL StopListener(
        const OpalTransportAddress & iface 
    );

    BOOL RemoveListener(
      OpalListener * listener 
    );

    OpalTransportAddressArray GetInterfaceAddresses(
      BOOL excludeLocalHost = TRUE,       
      OpalTransport * associatedTransport = NULL
    );

    PDECLARE_NOTIFIER(PThread, OpalEndPoint, ListenerCallback);

    virtual BOOL NewIncomingConnection(
      OpalTransport * transport  
    );

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

    virtual BOOL OnSetUpConnection(OpalConnection &connection);
    
    virtual BOOL OnIncomingConnection(
      OpalConnection & connection,  
      unsigned options,             
      OpalConnection::StringOptions * stringOptions
    );
    virtual BOOL OnIncomingConnection(
      OpalConnection & connection,  
      unsigned options              
    );
    virtual BOOL OnIncomingConnection(
      OpalConnection & connection   
    );

    virtual void OnAlerting(
      OpalConnection & connection   
    );

    virtual OpalConnection::AnswerCallResponse OnAnswerCall(
      OpalConnection & connection,    
       const PString & caller         
    );

    virtual void OnConnected(
      OpalConnection & connection   
    );

    virtual void OnEstablished(
      OpalConnection & connection   
    );

    virtual void OnReleased(
      OpalConnection & connection   
    );

    void OnHold(
      OpalConnection & connection   
    );

    virtual BOOL OnForwarded(
      OpalConnection & connection,  
      const PString & remoteParty         
    );

    virtual BOOL ClearCall(
      const PString & token,    
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PSyncPoint * sync = NULL  
    );

    virtual BOOL ClearCallSynchronous(
      const PString & token,    
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PSyncPoint * sync = NULL  
    );

    virtual void ClearAllCalls(
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      BOOL wait = TRUE   
    );

    PSafePtr<OpalConnection> GetConnectionWithLock(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite
    ) { return connectionsActive.FindWithLock(token, mode); }

    PStringList GetAllConnections();

    virtual BOOL HasConnection(
      const PString & token   
    );

    virtual void DestroyConnection(
      OpalConnection * connection  
    );

    virtual OpalMediaFormatList GetMediaFormats() const = 0;

    virtual void AdjustMediaFormats(
      const OpalConnection & connection,  
      OpalMediaFormatList & mediaFormats  
    ) const;

    virtual BOOL OnOpenMediaStream(
      OpalConnection & connection,  
      OpalMediaStream & stream      
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

#if OPAL_VIDEO

    virtual void AddVideoMediaFormats(
      OpalMediaFormatList & mediaFormats, 
      const OpalConnection * connection = NULL  
    ) const;

    virtual BOOL CreateVideoInputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      BOOL & autoDelete                     
    );

    virtual BOOL CreateVideoOutputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      BOOL preview,                         
      PVideoOutputDevice * & device,        
      BOOL & autoDelete                     
    );
#endif


    virtual void OnUserInputString(
      OpalConnection & connection,  
      const PString & value   
    );

    virtual void OnUserInputTone(
      OpalConnection & connection,  
      char tone,                    
      int duration                  
    );

    virtual PString ReadUserInput(
      OpalConnection & connection,        
      const char * terminators = "#\r\n", 
      unsigned lastDigitTimeout = 4,      
      unsigned firstDigitTimeout = 30     
    );

#if OPAL_T120DATA

    virtual OpalT120Protocol * CreateT120ProtocolHandler(
      const OpalConnection & connection  
    ) const;
#endif

#if OPAL_T38FAX

    virtual OpalT38Protocol * CreateT38ProtocolHandler(
      const OpalConnection & connection  
    ) const;
        
#endif

#if OPAL_H224

    virtual OpalH224Handler * CreateH224ProtocolHandler(
      OpalConnection & connection, 
      unsigned sessionID
    ) const;
        
    virtual OpalH281Handler * CreateH281ProtocolHandler(
      OpalH224Handler & h224Handler
    ) const;
#endif

    virtual BOOL GarbageCollection();

    OpalManager & GetManager() const { return manager; }

    const PString & GetPrefixName() const { return prefixName; }

    BOOL HasAttribute(Attributes opt) const { return (attributeBits&opt) != 0; }

    WORD GetDefaultSignalPort() const { return defaultSignalPort; }

    const OpalProductInfo & GetProductInfo() const { return productInfo; }

    void SetProductInfo(
      const OpalProductInfo & info
    ) { productInfo = info; }

    const PString & GetDefaultLocalPartyName() const { return defaultLocalPartyName; }

    void SetDefaultLocalPartyName(const PString & name) { defaultLocalPartyName = name; }

    const PString & GetDefaultDisplayName() const { return defaultDisplayName; }

    void SetDefaultDisplayName(const PString & name) { defaultDisplayName = name; }

    unsigned GetInitialBandwidth() const { return initialBandwidth; }

    void SetInitialBandwidth(unsigned bandwidth) { initialBandwidth = bandwidth; }

    const OpalListenerList & GetListeners() const { return listeners; }

    OpalConnection::SendUserInputModes GetSendUserInputMode() const { return defaultSendUserInputMode; }

    void SetSendUserInputMode(OpalConnection::SendUserInputModes mode) { defaultSendUserInputMode = mode; }

    virtual PString GetDefaultTransport() const;

    virtual void OnNewConnection(OpalCall & call, OpalConnection & conn);

#if P_SSL
    PString GetSSLCertificate() const;
#endif

    virtual void SetDefaultSecurityMode(const PString & v)
    { defaultSecurityMode = v; }

    virtual PString GetDefaultSecurityMode() const 
    { return defaultSecurityMode; }

    virtual BOOL UseRTPAggregation() const;

    void SetRTPAggregationSize(
      PINDEX size            
    );

    PINDEX GetRTPAggregationSize() const;

    PHandleAggregator * GetRTPAggregator();
        
    virtual BOOL AdjustInterfaceTable(PIPSocket::Address & remoteAddress,
                                      PIPSocket::InterfaceTable & interfaceTable);

    virtual BOOL IsRTPNATEnabled(OpalConnection & conn, 
                       const PIPSocket::Address & localAddr, 
                       const PIPSocket::Address & peerAddr,
                       const PIPSocket::Address & sigAddr,
                                             BOOL incoming);

  protected:
    OpalManager   & manager;
    PCaselessString prefixName;
    unsigned        attributeBits;
    WORD            defaultSignalPort;
    OpalProductInfo productInfo;
    PString         defaultLocalPartyName;
    PString         defaultDisplayName;

    unsigned initialBandwidth;  // in 100s of bits/sev
    OpalConnection::SendUserInputModes defaultSendUserInputMode;

    OpalListenerList   listeners;

    class ConnectionDict : public PSafeDictionary<PString, OpalConnection>
    {
        virtual void DeleteObject(PObject * object) const;
    } connectionsActive;
    BOOL AddConnection(OpalConnection * connection);

    PMutex inUseFlag;

    PString defaultSecurityMode; 

#if OPAL_RTP_AGGREGATE
    PMutex rtpAggregationMutex;
    BOOL useRTPAggregation; 
    PINDEX rtpAggregationSize;
    PHandleAggregator * rtpAggregator;
#endif

    friend void OpalManager::GarbageCollection();
    friend void OpalConnection::Release(CallEndReason reason);
};


#endif // __OPAL_ENDPOINT_H


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

---