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): ______________________________________.
 *
 * $Revision: 24442 $
 * $Author: rjongbloed $
 * $Date: 2010-06-02 03:17:31 -0500 (Wed, 02 Jun 2010) $
 */

#ifndef OPAL_OPAL_ENDPOINT_H
#define OPAL_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 OpalEndPoint : public PObject
{
    PCLASSINFO(OpalEndPoint, PObject);
  public:
    enum Attributes {
      CanTerminateCall = 1,
      HasLineInterface = 2
    };

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

    ~OpalEndPoint();

    virtual void ShutDown();

    void PrintOn(
      ostream & strm    
    ) const;

    PBoolean StartListeners(
      const PStringArray & interfaces 
    );

    PBoolean StartListener(
      const OpalTransportAddress & iface 
    );

    PBoolean StartListener(
      OpalListener * listener 
    );

    virtual PStringArray GetDefaultListeners() const;

    OpalListener * FindListener(
        const OpalTransportAddress & iface 
    );

    PBoolean StopListener(
        const OpalTransportAddress & iface 
    );

    PBoolean RemoveListener(
      OpalListener * listener 
    );

    OpalTransportAddressArray GetInterfaceAddresses(
      PBoolean excludeLocalHost = PTrue,       
      const OpalTransport * associatedTransport = NULL
    );

    PDECLARE_NOTIFIER(PThread, OpalEndPoint, ListenerCallback);

    virtual PBoolean NewIncomingConnection(
      OpalTransport * transport  
    );

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

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

    virtual void OnProceeding(
      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   
    );

    virtual void OnHold(
      OpalConnection & connection,   
      bool fromRemote,               
      bool onHold                    
    );
    virtual void OnHold(OpalConnection & connection); // For backward compatibility

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

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

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

    virtual void ClearAllCalls(
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PBoolean wait = PTrue   
    );

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

    template <class ConnClass>
    PSafePtr<ConnClass> GetConnectionWithLockAs(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite
    )
    {
      PSafePtr<ConnClass> connection = PSafePtrCast<OpalConnection, ConnClass>(GetConnectionWithLock(token, mode));
      if (connection == NULL) {
        PSafePtr<OpalCall> call = manager.FindCallWithLock(token, PSafeReadOnly);
        if (call != NULL) {
          connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(0, mode));
          if (connection == NULL)
            connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(1, mode));
        }
      }
      return connection;
    }

    PStringList GetAllConnections();
    
    PINDEX GetConnectionCount() const { return connectionsActive.GetSize(); }

    virtual PBoolean HasConnection(
      const PString & token   
    );

    virtual void DestroyConnection(
      OpalConnection * connection  
    );

    virtual OpalMediaFormatList GetMediaFormats() const = 0;

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

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

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

#if OPAL_VIDEO

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

    virtual PBoolean CreateVideoOutputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PBoolean preview,                         
      PVideoOutputDevice * & device,        
      PBoolean & 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     
    );

    virtual void OnMWIReceived (
      const PString & party,                
      OpalManager::MessageWaitingType type, 
      const PString & extraInfo             
    );

    virtual PBoolean GarbageCollection();

    OpalManager & GetManager() const { return manager; }

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

    PBoolean 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; }

    virtual 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; }

    const OpalConnection::StringOptions & GetDefaultStringOptions() const { return m_defaultStringOptions; }

    void SetDefaultStringOptions(const OpalConnection::StringOptions & opts) { m_defaultStringOptions = opts; }

    void SetDefaultStringOption(const PCaselessString & key, const PString & data) { m_defaultStringOptions.SetAt(key, data); }

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

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

    virtual PString GetDefaultTransport() const;

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

#if OPAL_PTLIB_SSL
    PString GetSSLCertificate() const;
#endif

    bool FindListenerForProtocol(const char * protoPrefix, OpalTransportAddress & addr);

    virtual PBoolean Message(
      const PString & to, 
      const PString & body
    );
    virtual PBoolean Message(
      const PURL & to, 
      const PString & type,
      const PString & body,
      PURL & from, 
      PString & conversationId
    );

    virtual void OnMessageReceived(
      const PURL & from, 
      const PString & fromName,
      const PURL & to, 
      const PString & type,
      const PString & body,
      const PString & conversationId
    );

#if OPAL_HAS_IM

    virtual bool TransmitExternalIM(
      OpalConnection & conn, 
      const OpalMediaFormat & format, 
      RTP_IMFrame & frame
    );
#endif

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

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

    OpalListenerList   listeners;

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

    PMutex inUseFlag;

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

  private:
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &, unsigned), false);
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &), false);
    P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(const OpalConnection &, OpalMediaFormatList &) const);
};


bool OpalIsE164(
  const PString & number,   
  bool strict = false     
);


#endif // OPAL_OPAL_ENDPOINT_H


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

---