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): ______________________________________.
 *
 * $Log: call.h,v $
 * Revision 2.32  2007/09/20 04:32:36  rjongbloed
 * Fixed issue with clearing a call before it has finished setting up.
 *
 * Revision 2.31  2007/09/18 09:37:52  rjongbloed
 * Propagated call backs for RTP statistics through OpalManager and OpalCall.
 *
 * Revision 2.30  2007/05/07 14:13:51  csoutheren
 * Add call record capability
 *
 * Revision 2.29  2007/04/16 06:48:04  rjongbloed
 * Added virtual to OpalCall::GetMediaFormats to allow user override.
 *
 * Revision 2.28  2007/04/03 05:27:29  rjongbloed
 * Cleaned up somewhat confusing usage of the OnAnswerCall() virtual
 *   function. The name is innaccurate and exists as a legacy from the
 *   OpenH323 days. it now only indicates how alerting is done
 *   (with/without media) and does not actually answer the call.
 *
 * Revision 2.27  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.26  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.25  2006/06/30 00:49:06  csoutheren
 * Applied 1469865 - remove connection from call's connection list
 * Thanks to Frederich Heem
 *
 * Revision 2.24  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.23  2005/10/22 12:16:05  dsandras
 * Moved mutex preventing media streams to be opened before they are completely closed to the SIPConnection class.
 *
 * Revision 2.22  2005/09/22 17:08:52  dsandras
 * Added mutex to protect media streams access and prevent media streams for a call to be closed before they are all opened.
 *
 * Revision 2.21  2005/08/04 17:21:48  dsandras
 * Added functions to close/remove the media streams of a call.
 *
 * Revision 2.20  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.19  2005/05/11 04:25:09  dereksmithies
 * Add description of the OpalConnection class instances managed by an OpalCall structure.
 *
 * Revision 2.18  2004/08/14 07:56:29  rjongbloed
 * Major revision to utilise the PSafeCollection classes for the connections and calls.
 *
 * Revision 2.17  2004/07/14 13:26:14  rjongbloed
 * Fixed issues with the propagation of the "established" phase of a call. Now
 *   calling an OnEstablished() chain like OnAlerting() and OnConnected() to
 *   finally arrive at OnEstablishedCall() on OpalManager
 *
 * Revision 2.16  2004/05/01 10:00:50  rjongbloed
 * Fixed ClearCallSynchronous so now is actually signalled when call is destroyed.
 *
 * Revision 2.15  2004/04/18 07:09:12  rjongbloed
 * Added a couple more API functions to bring OPAL into line with similar functions in OpenH323.
 *
 * Revision 2.14  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.13  2004/02/07 00:35:46  rjongbloed
 * Fixed calls GetMediaFormats so no DOES return intersection of all connections formats.
 * Tidied some API elements to make usage more explicit.
 *
 * Revision 2.12  2003/06/02 03:13:28  rjongbloed
 * Made changes so that media stream in opposite direction to the one already
 *   opened will use same media format for preference. That is try and use
 *   symmetric codecs if possible.
 *
 * Revision 2.11  2003/03/06 03:57:46  robertj
 * IVR support (work in progress) requiring large changes everywhere.
 *
 * Revision 2.10  2002/11/10 11:33:17  robertj
 * Updated to OpenH323 v1.10.3
 *
 * Revision 2.9  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.8  2002/04/08 02:40:13  robertj
 * Fixed issues with using double originate call, eg from simple app command line.
 *
 * Revision 2.7  2002/02/19 07:42:25  robertj
 * Restructured media bypass functions to fix problems with RFC2833.
 *
 * Revision 2.6  2002/02/11 07:38:01  robertj
 * Added media bypass for streams between compatible protocols.
 *
 * Revision 2.5  2002/01/22 05:03:47  robertj
 * Revamp of user input API triggered by RFC2833 support
 *
 * Revision 2.4  2001/11/15 07:02:12  robertj
 * Changed OpalCall::OpenSourceMediaStreams so the connection to not open
 *   a media stream on is optional.
 *
 * Revision 2.3  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.2  2001/08/17 08:24:33  robertj
 * Added call end reason for whole call, not just connection.
 *
 * Revision 2.1  2001/08/01 05:28:59  robertj
 * Added function to get all media formats possible in a call.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_CALL_H
#define __OPAL_CALL_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

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

#include <ptlib/safecoll.h>


class OpalManager;


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

    ~OpalCall();

    void PrintOn(
      ostream & strm    
    ) const;

    BOOL IsEstablished() const { return isEstablished; }

    virtual void OnEstablishedCall();

    OpalConnection::CallEndReason GetCallEndReason() const { return callEndReason; }

    void SetCallEndReason(
      OpalConnection::CallEndReason reason   
    );

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

    virtual void OnCleared();

    virtual BOOL OnSetUp(
      OpalConnection & connection   
    );

    virtual BOOL OnAlerting(
      OpalConnection & connection   
    );

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

    virtual BOOL OnConnected(
      OpalConnection & connection   
    );

    virtual BOOL OnEstablished(
      OpalConnection & connection   
    );

    virtual void OnReleased(
      OpalConnection & connection   
    );

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

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

    virtual OpalMediaFormatList GetMediaFormats(
      const OpalConnection & connection,  
      BOOL includeSpecifiedConnection     
    );

    virtual BOOL OpenSourceMediaStreams(
      const OpalConnection & connection,        
      const OpalMediaFormatList & mediaFormats, 
      unsigned sessionID                        
    );

    virtual BOOL PatchMediaStreams(
      const OpalConnection & connection, 
      OpalMediaStream & source           
    );
    
    virtual void OnRTPStatistics(
      const OpalConnection & connection,  
      const RTP_Session & session         
    );

    virtual void CloseMediaStreams();
    
    virtual void RemoveMediaStreams();

    virtual BOOL IsMediaBypassPossible(
      const OpalConnection & connection,  
      unsigned sessionID                  
    ) const;

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

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

    OpalManager & GetManager() const { return manager; }

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

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

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

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

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

    virtual BOOL StartRecording(const PFilePath & fn);
    virtual void StopRecording();
    void OnStopRecordAudio(const PString & callToken);

  protected:
    OpalManager & manager;

    PString myToken;

    PString partyA;
    PString partyB;
    PTime   startTime;
    BOOL    isEstablished;
    BOOL    isClearing;

    OpalConnection::CallEndReason callEndReason;

    PSafeList<OpalConnection> connectionsActive;

    PSyncPoint * endCallSyncPoint;

    
  //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();
};


#endif // __OPAL_CALL_H


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

---