call.h

Go to the documentation of this file.

/*
 * call.h
 *
 * Telephone call management
 *
 * 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): ______________________________________.
 */

#ifndef OPAL_OPAL_CALL_H
#define OPAL_OPAL_CALL_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <opal/connection.h>
#include <opal/recording.h>
#include <opal/guid.h>

#include <ptlib/safecoll.h>


class OpalManager;
class OpalRTPSession;


class OpalCall : public PSafeObject
{
    PCLASSINFO(OpalCall, PSafeObject);
  public:
    OpalCall(
      OpalManager & manager   
    );

    ~OpalCall();

    void PrintOn(
      ostream & strm    
    ) const;

    PBoolean IsEstablished() const { return m_isEstablished; }

    virtual void OnEstablishedCall();

    OpalConnection::CallEndReason GetCallEndReason() const;

    PString GetCallEndReasonText() const { return OpalConnection::GetCallEndReasonText(GetCallEndReason()); }

    void SetCallEndReason(
      OpalConnection::CallEndReason reason   
    );

    void Clear(
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PSyncPoint * sync = NULL                                                 
    );

    virtual void OnCleared();

    virtual void OnNewConnection(
      OpalConnection & connection   
    );

    virtual PBoolean OnSetUp(
      OpalConnection & connection   
    );

    virtual void OnProceeding(
      OpalConnection & connection   
    );

    virtual void OnAlerting(
      OpalConnection & connection,   
      bool withMedia                 
    );
    virtual PBoolean OnAlerting(OpalConnection & connection); // For backward compatibility

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

    virtual PBoolean OnConnected(
      OpalConnection & connection   
    );

    virtual PBoolean OnEstablished(
      OpalConnection & connection   
    );

    virtual void OnReleased(
      OpalConnection & connection   
    );

    virtual void OnHold(
      OpalConnection & connection,   
      bool fromRemote,               
      bool onHold                    
    );

    PSafePtr<OpalConnection> GetOtherPartyConnection(
      const OpalConnection & connection  
    ) const;

    PINDEX GetConnectionCount() const { return m_connectionsActive.GetSize(); }

    PSafePtr<OpalConnection> GetConnection(
      PINDEX idx,
      PSafetyMode mode = PSafeReference
    ) { return m_connectionsActive.GetAt(idx, mode); }

    template <class ConnClass>
    PSafePtr<ConnClass> GetConnectionAs(
      PINDEX count = 0,
      PSafetyMode mode = PSafeReadWrite
    )
    {
      PSafePtr<ConnClass> connection;
      for (PSafePtr<OpalConnection> iterConn(m_connectionsActive, PSafeReference); iterConn != NULL; ++iterConn) {
        if ((connection = PSafePtrCast<OpalConnection, ConnClass>(iterConn)) != NULL && count-- == 0) {
          if (!connection.SetSafetyMode(mode))
            connection.SetNULL();
          break;
        }
      }
      return connection;
    }

    bool Hold(bool hold = true);

    bool Retrieve() { return Hold(false); }

    bool IsOnHold(
      bool fromRemote = false
    ) const;

    bool Transfer(
      const PString & address,           
      OpalConnection * connection = NULL 
    );

    virtual OpalMediaFormatList GetMediaFormats(
      const OpalConnection & connection  
    );

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

    virtual bool OpenSourceMediaStreams(
      OpalConnection & connection,              
      const OpalMediaType & mediaType,          
      unsigned sessionID = 0,                   
      const OpalMediaFormat & preselectedFormat = OpalMediaFormat(),  
#if OPAL_VIDEO
      OpalVideoFormat::ContentRole contentRole = OpalVideoFormat::eNoRole, 
#endif
      bool transfer = false,
      bool startPaused = false
    );

    virtual bool SelectMediaFormats(
      const OpalMediaType & mediaType,        
      const OpalMediaFormatList & srcFormats, 
      const OpalMediaFormatList & dstFormats, 
      const OpalMediaFormatList & masterFormats, 
      OpalMediaFormat & srcFormat,            
      OpalMediaFormat & dstFormat             
    ) const;

    virtual void CloseMediaStreams();

#if OPAL_STATISTICS
    bool GetStatistics(
      const OpalMediaType & mediaType,  
      bool fromAparty,                  
      OpalMediaStatistics & statistics  
    );
#endif // OPAL_STATISTICS


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

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

    OpalManager & GetManager() const { return m_manager; }

    const PString & GetToken() const { return m_token; }

    const PString & GetPartyA() const { return m_partyA; }

    const PString & GetPartyB() const { return m_partyB; }

    void SetPartyB(
      const PString & b
    ) { m_partyB = b; }

    const PString & GetNameA() const { return m_nameA; }

    const PString & GetNameB() const { return m_nameB; }

    const PString & GetIdentityA() const { return m_identityA; }

    const PString & GetIdentityB() const { return m_identityB; }

    bool IsNetworkOriginated() const { return m_networkOriginated; }

    const PString & GetRemoteParty() const { return m_networkOriginated ? m_partyA : m_partyB; }

    const PString & GetLocalParty() const { return m_networkOriginated ? m_partyB : m_partyA; }

    const PString & GetRemoteName() const { return m_networkOriginated ? m_nameA : m_nameB; }

    const PString & GetLocalName() const { return m_networkOriginated ? m_nameB : m_nameA; }

    const PTime & GetStartTime() const { return m_startTime; }

    const PTime & GetEstablishedTime() const { return m_establishedTime; }

#if OPAL_HAS_MIXER

    bool StartRecording(
      const PFilePath & filename, 
      const OpalRecordManager::Options & options = false 
    );

    bool StartRecording(
      const PDirectory & outputDir, 
      const PString & fileTemplate, 
      const PString & fileType,     
      const OpalRecordManager::Options & options = false 
    );

    bool IsRecording() const;

    bool StopRecording();

    virtual bool OnStartRecording(
      const PString & streamId,       
      const OpalMediaFormat & format  
    );

    virtual void OnStopRecording(
      const PString & streamId       
    );

    virtual void OnRecordAudio(
      const PString & streamId,       
      const RTP_DataFrame & frame     
    );

#if OPAL_VIDEO

    virtual void OnRecordVideo(
      const PString & streamId,       
      const RTP_DataFrame & frame     
    );
#endif
#endif // OPAL_HAS_MIXER

    void InternalOnClear();

    void SetPartyNames();

#if OPAL_T38_CAPABILITY
    bool IsSwitchingT38()     const { return m_T38SwitchState != e_NotSwitchingT38; }
    bool IsSwitchingToT38()   const { return m_T38SwitchState == e_SwitchingToT38;  }
    void ResetSwitchingT38()        { m_T38SwitchState = e_NotSwitchingT38; }
    void SetSwitchingT38(bool to)   { m_T38SwitchState = to ? e_SwitchingToT38 : e_SwitchingFromT38; }
#endif

  protected:
    bool EnumerateConnections(
      PSafePtr<OpalConnection> & connection,
      PSafetyMode mode,
      const OpalConnection * skipConnection = NULL
    ) const;

    OpalManager & m_manager;

    PString m_token;

    PString m_partyA;
    PString m_partyB;
    PString m_nameA;
    PString m_nameB;
    PString m_identityA;
    PString m_identityB;
    bool    m_networkOriginated;
    PTime   m_startTime;
    PTime   m_establishedTime;
    bool    m_isEstablished;
    bool    m_isClearing;
    bool    m_handlingHold;
    atomic<bool> m_isCleared;

    OpalConnection::CallEndReason m_callEndReason;
    PCriticalSection              m_callEndReasonMutex;
    std::list<PSyncPoint *> m_endCallSyncPoint;

    PSafeArray<OpalConnection> m_connectionsActive;

#if OPAL_HAS_MIXER
    OpalRecordManager * m_recordManager;
#endif

#if OPAL_SCRIPT
    PDECLARE_ScriptFunctionNotifier(OpalCall, ScriptClear);
#endif

#if OPAL_T38_CAPABILITY
    enum {
      e_NotSwitchingT38,
      e_SwitchingToT38,
      e_SwitchingFromT38
    } m_T38SwitchState;
#endif

  //use to add the connection to the call's connection list
  friend OpalConnection::OpalConnection(OpalCall &, OpalEndPoint &, const PString &, unsigned int, OpalConnection::StringOptions *);
  //use to remove the connection from the call's connection list
  friend OpalConnection::~OpalConnection();

  P_REMOVE_VIRTUAL_VOID(OnRTPStatistics(const OpalConnection &, const OpalRTPSession &));
};


#endif // OPAL_OPAL_CALL_H


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