call.h

Go to the documentation of this file.
00001 /*
00002  * call.h
00003  *
00004  * Telephone call management
00005  *
00006  * Open Phone Abstraction Library (OPAL)
00007  * Formally known as the Open H323 project.
00008  *
00009  * Copyright (c) 2001 Equivalence Pty. Ltd.
00010  *
00011  * The contents of this file are subject to the Mozilla Public License
00012  * Version 1.0 (the "License"); you may not use this file except in
00013  * compliance with the License. You may obtain a copy of the License at
00014  * http://www.mozilla.org/MPL/
00015  *
00016  * Software distributed under the License is distributed on an "AS IS"
00017  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00018  * the License for the specific language governing rights and limitations
00019  * under the License.
00020  *
00021  * The Original Code is Open Phone Abstraction Library.
00022  *
00023  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00024  *
00025  * Contributor(s): ______________________________________.
00026  *
00027  * $Log: call.h,v $
00028  * Revision 2.24  2005/11/30 13:35:26  csoutheren
00029  * Changed tags for Doxygen
00030  *
00031  * Revision 2.23  2005/10/22 12:16:05  dsandras
00032  * Moved mutex preventing media streams to be opened before they are completely closed to the SIPConnection class.
00033  *
00034  * Revision 2.22  2005/09/22 17:08:52  dsandras
00035  * Added mutex to protect media streams access and prevent media streams for a call to be closed before they are all opened.
00036  *
00037  * Revision 2.21  2005/08/04 17:21:48  dsandras
00038  * Added functions to close/remove the media streams of a call.
00039  *
00040  * Revision 2.20  2005/07/11 01:52:23  csoutheren
00041  * Extended AnsweringCall to work for SIP as well as H.323
00042  * Fixed problems with external RTP connection in H.323
00043  * Added call to OnClosedMediaStream
00044  *
00045  * Revision 2.19  2005/05/11 04:25:09  dereksmithies
00046  * Add description of the OpalConnection class instances managed by an OpalCall structure.
00047  *
00048  * Revision 2.18  2004/08/14 07:56:29  rjongbloed
00049  * Major revision to utilise the PSafeCollection classes for the connections and calls.
00050  *
00051  * Revision 2.17  2004/07/14 13:26:14  rjongbloed
00052  * Fixed issues with the propagation of the "established" phase of a call. Now
00053  *   calling an OnEstablished() chain like OnAlerting() and OnConnected() to
00054  *   finally arrive at OnEstablishedCall() on OpalManager
00055  *
00056  * Revision 2.16  2004/05/01 10:00:50  rjongbloed
00057  * Fixed ClearCallSynchronous so now is actually signalled when call is destroyed.
00058  *
00059  * Revision 2.15  2004/04/18 07:09:12  rjongbloed
00060  * Added a couple more API functions to bring OPAL into line with similar functions in OpenH323.
00061  *
00062  * Revision 2.14  2004/03/11 06:54:27  csoutheren
00063  * Added ability to disable SIP or H.323 stacks
00064  *
00065  * Revision 2.13  2004/02/07 00:35:46  rjongbloed
00066  * Fixed calls GetMediaFormats so no DOES return intersection of all connections formats.
00067  * Tidied some API elements to make usage more explicit.
00068  *
00069  * Revision 2.12  2003/06/02 03:13:28  rjongbloed
00070  * Made changes so that media stream in opposite direction to the one already
00071  *   opened will use same media format for preference. That is try and use
00072  *   symmetric codecs if possible.
00073  *
00074  * Revision 2.11  2003/03/06 03:57:46  robertj
00075  * IVR support (work in progress) requiring large changes everywhere.
00076  *
00077  * Revision 2.10  2002/11/10 11:33:17  robertj
00078  * Updated to OpenH323 v1.10.3
00079  *
00080  * Revision 2.9  2002/09/16 02:52:35  robertj
00081  * Added #define so can select if #pragma interface/implementation is used on
00082  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00083  *
00084  * Revision 2.8  2002/04/08 02:40:13  robertj
00085  * Fixed issues with using double originate call, eg from simple app command line.
00086  *
00087  * Revision 2.7  2002/02/19 07:42:25  robertj
00088  * Restructured media bypass functions to fix problems with RFC2833.
00089  *
00090  * Revision 2.6  2002/02/11 07:38:01  robertj
00091  * Added media bypass for streams between compatible protocols.
00092  *
00093  * Revision 2.5  2002/01/22 05:03:47  robertj
00094  * Revamp of user input API triggered by RFC2833 support
00095  *
00096  * Revision 2.4  2001/11/15 07:02:12  robertj
00097  * Changed OpalCall::OpenSourceMediaStreams so the connection to not open
00098  *   a media stream on is optional.
00099  *
00100  * Revision 2.3  2001/08/22 10:20:09  robertj
00101  * Changed connection locking to use double mutex to guarantee that
00102  *   no threads can ever deadlock or access deleted connection.
00103  *
00104  * Revision 2.2  2001/08/17 08:24:33  robertj
00105  * Added call end reason for whole call, not just connection.
00106  *
00107  * Revision 2.1  2001/08/01 05:28:59  robertj
00108  * Added function to get all media formats possible in a call.
00109  *
00110  * Revision 2.0  2001/07/27 15:48:24  robertj
00111  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00112  *
00113  */
00114 
00115 #ifndef __OPAL_CALL_H
00116 #define __OPAL_CALL_H
00117 
00118 #ifdef P_USE_PRAGMA
00119 #pragma interface
00120 #endif
00121 
00122 #include <opal/buildopts.h>
00123 
00124 #include <opal/connection.h>
00125 #include <opal/guid.h>
00126 
00127 #include <ptlib/safecoll.h>
00128 
00129 
00130 class OpalManager;
00131 
00132 
00147 class OpalCall : public PSafeObject
00148 {
00149     PCLASSINFO(OpalCall, PSafeObject);
00150   public:
00155     OpalCall(
00156       OpalManager & manager   
00157     );
00158 
00161     ~OpalCall();
00163 
00170     void PrintOn(
00171       ostream & strm    
00172     ) const;
00174 
00179     BOOL IsEstablished() const { return isEstablished; }
00180 
00186     virtual void OnEstablishedCall();
00187 
00196     OpalConnection::CallEndReason GetCallEndReason() const { return callEndReason; }
00197 
00202     void SetCallEndReason(
00203       OpalConnection::CallEndReason reason   
00204     );
00205 
00214     void Clear(
00215       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00216       PSyncPoint * sync = NULL                                                 
00217     );
00218 
00224     virtual void OnCleared();
00226 
00234     virtual BOOL OnSetUp(
00235       OpalConnection & connection   
00236     );
00237 
00243     virtual BOOL OnAlerting(
00244       OpalConnection & connection   
00245     );
00246 
00247     virtual OpalConnection::AnswerCallResponse
00248        OnAnswerCall(OpalConnection & connection,
00249                      const PString & caller
00250     );
00251 
00252     virtual void AnsweringCall(
00253       OpalConnection::AnswerCallResponse response 
00254     );
00255 
00267     virtual BOOL OnConnected(
00268       OpalConnection & connection   
00269     );
00270 
00284     virtual BOOL OnEstablished(
00285       OpalConnection & connection   
00286     );
00287 
00293     virtual void OnReleased(
00294       OpalConnection & connection   
00295     );
00296 
00302     PSafePtr<OpalConnection> GetOtherPartyConnection(
00303       const OpalConnection & connection  
00304     ) const;
00305 
00308     PSafePtr<OpalConnection> GetConnection(
00309       PINDEX idx,
00310       PSafetyMode mode = PSafeReference
00311     ) { return connectionsActive.GetAt(idx, mode); }
00313 
00324     OpalMediaFormatList GetMediaFormats(
00325       const OpalConnection & connection,  
00326       BOOL includeSpecifiedConnection     
00327     );
00328 
00334     virtual BOOL OpenSourceMediaStreams(
00335       const OpalConnection & connection,        
00336       const OpalMediaFormatList & mediaFormats, 
00337       unsigned sessionID                        
00338     );
00339 
00345     virtual BOOL PatchMediaStreams(
00346       const OpalConnection & connection, 
00347       OpalMediaStream & source           
00348     );
00349     
00352     virtual void CloseMediaStreams();
00353     
00356     virtual void RemoveMediaStreams();
00357 
00360     virtual BOOL IsMediaBypassPossible(
00361       const OpalConnection & connection,  
00362       unsigned sessionID                  
00363     ) const;
00365 
00373     virtual void OnUserInputString(
00374       OpalConnection & connection,  
00375       const PString & value         
00376     );
00377 
00386     virtual void OnUserInputTone(
00387       OpalConnection & connection,  
00388       char tone,                    
00389       int duration                  
00390     );
00392 
00397     OpalManager & GetManager() const { return manager; }
00398 
00401     const PString & GetToken() const { return myToken; }
00402 
00407     const PString & GetPartyA() const { return partyA; }
00408 
00414     const PString & GetPartyB() const { return partyB; }
00415 
00421     void SetPartyB(
00422       const PString & b
00423     ) { partyB = b; }
00424 
00427     const PTime & GetStartTime() const { return startTime; }
00429 
00430 
00431   protected:
00432     OpalManager & manager;
00433 
00434     PString myToken;
00435 
00436     PString partyA;
00437     PString partyB;
00438     PTime   startTime;
00439     BOOL    isEstablished;
00440 
00441     OpalConnection::CallEndReason callEndReason;
00442 
00443     PSafeList<OpalConnection> connectionsActive;
00444 
00445     PSyncPoint * endCallSyncPoint;
00446 
00447   friend OpalConnection::OpalConnection(OpalCall & call, OpalEndPoint & ep, const PString & token);
00448 };
00449 
00450 
00451 #endif // __OPAL_CALL_H
00452 
00453 
00454 // End of File ///////////////////////////////////////////////////////////////

Generated on Mon Sep 25 16:19:33 2006 for OPAL by  doxygen 1.4.7