1 /* 2 * connection.h 3 * 4 * Telephony connection abstraction 5 * 6 * Open Phone Abstraction Library (OPAL) 7 * Formally known as the Open H323 project. 8 * 9 * Copyright (c) 2001 Equivalence Pty. Ltd. 10 * 11 * The contents of this file are subject to the Mozilla Public License 12 * Version 1.0 (the "License"); you may not use this file except in 13 * compliance with the License. You may obtain a copy of the License at 14 * http://www.mozilla.org/MPL/ 15 * 16 * Software distributed under the License is distributed on an "AS IS" 17 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 18 * the License for the specific language governing rights and limitations 19 * under the License. 20 * 21 * The Original Code is Open Phone Abstraction Library. 22 * 23 * The Initial Developer of the Original Code is Equivalence Pty. Ltd. 24 * 25 * Contributor(s): Post Increment 26 * Portions of this code were written with the assistance of funding from 27 * US Joint Forces Command Joint Concept Development & Experimentation (J9) 28 * http://www.jfcom.mil/about/abt_j9.htm 29 * 30 * $Revision: 28445 $ 31 * $Author: rjongbloed $ 32 * $Date: 2012-10-02 20:11:02 -0500 (Tue, 02 Oct 2012) $ 33 */ 34 35 #ifndef OPAL_OPAL_CONNECTION_H 36 #define OPAL_OPAL_CONNECTION_H 37 38 #ifdef P_USE_PRAGMA 39 #pragma interface 40 #endif 41 42 #include <opal/buildopts.h> 43 44 #include <opal/mediafmt.h> 45 #include <opal/mediastrm.h> 46 #include <opal/guid.h> 47 #include <opal/transports.h> 48 #include <ptclib/dtmf.h> 49 #include <ptlib/safecoll.h> 50 #include <rtp/rtp.h> 51 52 #if OPAL_HAS_IM 53 #include <im/t140.h> 54 #include <im/rfc4103.h> 55 #include <im/im.h> 56 #endif 57 58 #if P_LUA 59 #include <ptclib/lua.h> 60 #endif 61 62 class OpalEndPoint; 63 class OpalCall; 64 class OpalSilenceDetector; 65 class OpalEchoCanceler; 66 class OpalRFC2833Proto; 67 class OpalRFC2833Info; 68 class PURL; 69 70 71 #define OPAL_URL_PARAM_PREFIX "OPAL-" 72 73 #define OPAL_OPT_AUTO_START "AutoStart" ///< String option for auto-started media types 74 #define OPAL_OPT_CALL_IDENTIFIER "Call-Identifier" ///< String option to override generated call identifier 75 #define OPAL_OPT_CALLING_PARTY_URL "Calling-Party-URL" ///< String option to set outgoing local URL 76 #define OPAL_OPT_CALLING_PARTY_NUMBER "Calling-Party-Number" ///< String option to set outgoing local number, deprecated, same as OPAL_OPT_CALLING_PARTY_NAME 77 #define OPAL_OPT_CALLING_PARTY_NAME "Calling-Party-Name" ///< String option to set outgoing local name 78 #define OPAL_OPT_CALLING_PARTY_DOMAIN "Calling-Party-Domain" ///< String option to set outgoing local host/address/domain 79 #define OPAL_OPT_CALLING_DISPLAY_NAME "Calling-Display-Name" ///< String option to set outgoing display name 80 #define OPAL_OPT_CALLED_PARTY_NAME "Called-Party-Name" ///< String option to set outgoing party name 81 #define OPAL_OPT_CALLED_DISPLAY_NAME "Called-Display-Name" ///< String option to set outgoing display name 82 #define OPAL_OPT_REDIRECTING_PARTY "Redirecting-Party" ///< String option to set redirecting/refferred-by party 83 #define OPAL_OPT_PRESENTATION_BLOCK "Presentation-Block" ///< String option to block outgoing calling number presentation 84 #define OPAL_OPT_ORIGINATOR_ADDRESS "Originator-Address" ///< String option for originator address used by IVR 85 #define OPAL_OPT_INTERFACE "Interface" ///< String option to set the interface used for outgoing call 86 #define OPAL_OPT_USER_INPUT_MODE "User-Input-Mode" ///< String option to set User Input indication mode: 87 ///< "RFC2833", "String", "Tone", "Q.931" or "InBand" 88 #define OPAL_OPT_ENABLE_INBAND_DTMF "EnableInbandDTMF" ///< String option to enable in band DTMF detection 89 #define OPAL_OPT_ENABLE_INBAND_DTMF "EnableInbandDTMF" ///< String option to enable in band DTMF detection/send 90 #define OPAL_OPT_DETECT_INBAND_DTMF "DetectInBandDTMF" ///< String option to enable in band DTMF detection 91 #define OPAL_OPT_SEND_INBAND_DTMF "SendInBandDTMF" ///< String option to enable in band DTMF send as fall back for other UI modes 92 #define OPAL_OPT_DTMF_MULT "dtmfmult" 93 #define OPAL_OPT_DTMF_DIV "dtmfdiv" 94 #define OPAL_OPT_DISABLE_JITTER "Disable-Jitter" ///< String option to disable jitter buffer if "true" 95 #define OPAL_OPT_MAX_JITTER "Max-Jitter" ///< String option to set maximum jitter in milliseconds 96 #define OPAL_OPT_MIN_JITTER "Min-Jitter" ///< String option to set minimum jitter in milliseconds 97 #define OPAL_OPT_RECORD_AUDIO "Record-Audio" ///< String option to start recording to a file for call 98 #define OPAL_OPT_ALERTING_TYPE "Alerting-Type" ///< String option to set the alerting type string for call 99 #define OPAL_OPT_REMOVE_CODEC "Remove-Codec" ///< String option to remove codecs for this call 100 101 102 /*! \page pageOpalConnections Connection handling in the OPAL library 103 104 \section secOverview Overview 105 This page of the documentation is designed to provide an understanding of the 106 use of the OpalConnection class in the OPAL library. From the description, you 107 will be able to add your own voip protocol to OPAL, and utilise the features 108 provided by the existing class structure. 109 110 Key to understanding the OpalConnection class is that this class is 111 responsible for supervising the call signaling and media control for one call. 112 113 There will be one descendant of this OpalConnection class created for each 114 protocol that is supported. 115 116 117 \section secCallPhases Call Phases 118 119 Defined in OpalConnection, there is an enum (OpalConnection::Phases) that describes the 120 different stages of the call. Note that all OpalConnection instances go 121 through these phases as a call progresses. Even the OpalPCSSConnection, which 122 is the connection of PCM audio to/from the sound card, will (at some time) be 123 in each of the available phases. 124 125 To illustrate the meaning of the phases, we will descibe a very simple voip 126 protocol. This example protocol will also be used to show when the different 127 callbacks happen, and when the phases are changed at either endpoint of the 128 call. 129 130 The two endpoints in the call are labelled L and R (left and right). L is making a call to R 131 132 \li L goes to OpalConnection::SetUpPhase, and sends invite packet to R 133 \li R goes to OpalConnection::SetUpPhase, and starts ringing the phone 134 \li R goes to OpalConnection::AlertingPhase 135 \li R sends a message to L, "my phone is ringing" 136 \li L goes to OpalConnection::AlertingPhase 137 \li L sends a message to R, "I can only do G711 ALaw, RTP data to port 5400" 138 \li R sends s message to L, "Ok, we talk with G711 ALaw, send RTP data to me on port 5401" 139 \li R and L both wait for R's user to accept the ringing phone 140 \li R's user accepts the call by picking up the phone 141 \li R goes to OpalConnection::ConnectedPhase 142 \li R tells L that the call is accepted 143 \li L goes to OpalConnection::ConnectedPhase 144 \li R notices that media type is agreed on, the call is accepted, so goes to OpalConnection::EstablishedPhase 145 \li R realises that L knows everything is good for a call, so sends media to L 146 \li L reads the accepted message from R, goes to OpalConnection::EstablishedPhase 147 \li L sends media to R 148 \li both L and R exchange G711 ALaw on RTP port s 5400 and 5401 149 \li L (it could be R) sends a hangup message to R 150 \li L goes to OpalConnection::ReleasingPhase, and then stops all media traffic. 151 \li R receives the hangup message, goes to OpalConnection::ReleasingPhase, and stops all media traffic 152 \li L (and R) switch to OpalConnection::ReleasedPhase when all media and control streams have been terminated. 153 154 In the example above, if R had answered yes immediately, the call could not 155 move immediately to OpalConnection::EstablishedPhase as the media types were 156 not agreed on. 157 158 In the example above, we have described the decision process as to the codec 159 type, and the ports used. This decision process is not necessarily directly 160 handled by the OpalConnection descendant. For IAX2, where media negotiation is 161 an integral part of setting up the call, the IAX2Connection does media 162 negotiation. However, for SIP, there are SDPBandwidth, SDPMediaDescription, 163 SDPMediaFormat, SDPSessionDescription classes for handling media 164 negotiation. For the case of a pstn gateway using ISDN, there is no media 165 negotiation. It always uses G.711 and the same "port" (the B channel). 166 167 168 The different phases are. 169 170 \li OpalConnection::UninitialisedPhase - there is no call active. An 171 OpalConnection takes this phase when instantiated. 172 173 \li OpalConnection::SetUpPhase - the call is being created. This is around 174 the time of the first packet, which announces the 175 intent to create a call. At this point, there is no 176 agreement on the media format etc. 177 178 \li OpalConnection::AlertingPhase - the OpalConnection instance is aware the phone is ringing. 179 180 \li OpalConnection::ConnectedPhase - both endpoints have accepted the call, there may or may 181 not be agreement on media at this time. Note that in many systems 182 this constitutes the start of charging for a call. 183 184 \li OpalConnection::EstablishedPhase - we are "connected", there is agreement on the media 185 type, network ports, media can flow. This is the condition that 186 contitutes a call being "ready to use". 187 188 \li OpalConnection::ReleasingPhase - Either side (L or R) has said 189 "hangup". The media streams are in the process of 190 closing down. 191 192 \li OpalConnection::ReleasedPhase - Media and control streams have closed 193 down. When the call is in this phase, there is no 194 possibility of additional messages between L and R. 195 196 \li OpalConnection::NumPhases - Used for internal accounting. This indicates 197 that the phase is unknown. 198 199 \section secCallbacks OnEvent Callbacks in Opal 200 201 An OnXXX function is called when an external stimuli from the protocol occurs 202 and a SetXXX function may be called by OPAL to perform the protocol command. For 203 example OnAlerting is called when the H.323 ALERTING packet is received, and 204 SetAlerting transmits the ALERTING packet. 205 206 It is the OpalConnection class (or descendant) which is in charge of handling 207 the control packets of a particular protocol. Consequently, it is only 208 code in this class which sets the current call phase variable. Further, most 209 events are generated in the OpalConnection class, which are usually passed back to the 210 OpalEndPoint, then to the OpalManager, and usually on to the OpalCall class. 211 212 Consequently, if a descendant of the OpalManager has been created, the 213 application will have access to to notification on when the phase of a call 214 has changed. Applications may create descendants of the H323Connection and 215 SIPConnection to get protocol specific information about call progress. 216 217 Whenever the application does override a method in OpalManager (or 218 OpalEndPoint, or OpalConnection), the application should 219 \li spend the minimum of time in the overridden method, as this is holding up 220 call processing 221 \li call the method that was overridden, to ensure the correct operation of 222 Opal 223 224 225 The stages in a call, as applies to the methods provided by the OpalEndPoint, 226 OpalConnection, OpalCall and Manager classes. 227 228 \li The OpalConnection derivative, on deciding that a call is ready to begin 229 negotiations as to media etc, sets the phase to 230 OpalConnection::SetUpPhase, and invoke OpalCall::OnSetUp(). Note that it 231 is only partyA which invokes OpalCall::OnSetUp(). Then, for the other 232 OpalConnection instance in this voip call, the methods 233 OpalConnection::SetUpConnection and OpalConnection::OnSetUpConnection are 234 invoked. The OpalConnection::OnSetUpConnection then invokes 235 OpalEndPoint::OnSetUpConnection(). 236 237 \li The recipient of an incoming voip call (R from example above) will go 238 straight from OpalConnection::UninitialisedPhase to 239 OpalConnection::AlertingPhase, on receipt of the INVITE/Hello packet. The 240 initiator of a voip call (L from example above) moves to 241 OpalConnection::AlertingPhase on receiving a notice the call has not been 242 immediately rejected. 243 244 \li When an OpalConnection instance moves to OpalConnection::OnAlerting 245 phase, which invokes OpalConnection::OnAlerting, which invokes 246 OpalEndPoint::OnAlerting, which invokes OpalManager::OnAlerting, which 247 invokes OpalCall::OnAlerting. The OpalCall::OnAlerting method then invokes 248 the OpalConnection::SetAlerting method of the other OpalConnection 249 instance in this call (which is partyB). Consequently, when one 250 OpalConnection instance in a call does OpalConnection::OnAlerting, the 251 other OpalConnection instance in the call does a 252 OpalConnection::SetAlerting. 253 254 \li The method for deciding on the appropriate media to use, and for deciding 255 when the user at R actually picks up the remote phone to accept the call, 256 is entirely protocol specific. This decision making process is handled 257 by code in the descendant of the OpalConnection class. As much of the 258 common behaviour is abstracted to OpalConnection, OpalMediaFormat etc 259 as possible, but the details must reside in the OpalConnection. 260 261 \li When the signaling is completed, and the call is accepted at R, both L and R 262 will move to the OpalConnection::ConnectedPhase, and invoke 263 OpalConnection::OnConnected. which invokes OpalEndPoint::OnConnected, 264 which invokes OpalManager::OnConnected, which invokes 265 OpalCall::OnConnected. The OpalCall::OnConnected method then invokes the 266 OpalConnection::SetConnected method of the other OpalConnection instance 267 in this call (which is partyB). Consequently, when one OpalConnection 268 instance in a call does OpalConnection::OnConnected, the other 269 OpalConnection instance in the call does a OpalConnection::SetConnected. 270 The operation of the OpalConnection::SetConnected method is currently 271 empty - it is a protocol dependant thing exactly how to respond. 272 273 \li When the media is decided on, and the call has been accepted at R, media 274 can flow. At the point where the media threads are created and agreed on 275 at both ends, the call is marked as OpalConnection::OnEstablished. It is 276 the transition to the established phase that starts the media 277 streams. The descendant of OpalConnection decides to move to established 278 phase, and invokes OpalConnection::OnEstablished. which starts the media 279 streams and invokes OpalEndPoint::OnEstablished, which invokes 280 OpalManager::OnEstablished., which invokes OpalCall::OnEstablished. The 281 OpalCall::OnEstablished method then checks that there are two 282 OpalConnection instances in the call, and starts the media streams on the 283 calling connection. The OpalCall::OnEstablished method then checks that 284 all OpalConnection instances in this call are marked as 285 Established. Fininally, the OpalCall::OnEstablishedCall method is 286 invoked, which then invokes OpalManager::OnEstablishedCall. The 287 OpalManager::OnEstablishedCall method is empty, but if an application 288 overrides this method, the application will get notification of when a 289 call has started sending media. 290 291 \li Calls are terminated by the OpalManager::ClearCall method, which invokes 292 OpalCall::Clear. For each OpalConnection instance in the OpalCall class, 293 the OpalConnection::Release method is invoked. The call phase is switched 294 to OpalConnection::ReleasingPhase and a thread is created to close down 295 the OpalConnection instance. This thread invokes 296 OpalConnection::OnRelease, which then invokes OpalConnection::OnReleased, 297 closes the media streams, and then invokes OpalEndPoint::OnReleased. The 298 endpoint invokes OpalManager::OnReleased, which invokes 299 OpalCall::OnReleased. The OpalCall::OnReleased method will do 300 OpalConnection::Release() on the other OpalConnection instance managed by 301 the OpalCall (if the other OpalConnection is still there). Once all 302 OpalConnection instances have gone from the OpalCall, OpalCall::OnCleared 303 is invoked, which invokes OpalManager::OnClearedCall. The 304 OpalManager::OnClearedCall method is empty, but can be overridden by the 305 application to get notification when all components of a call (media, 306 control) have fully terminated. 307 */ 308 309 /** Class for carying vendor/product 310 information. 311 */ 312 class OpalProductInfo 313 { 314 public: 315 OpalProductInfo(); 316 317 static OpalProductInfo & Default(); 318 319 friend ostream & operator<<(ostream & strm, const OpalProductInfo & info); 320 PCaselessString AsString() const; 321 322 PCaselessString vendor; 323 PCaselessString name; 324 PCaselessString version; 325 PCaselessString comments; 326 327 BYTE t35CountryCode; 328 BYTE t35Extension; 329 WORD manufacturerCode; 330 331 private: 332 OpalProductInfo(bool); 333 }; 334 335 336 /**This is the base class for connections to an endpoint. 337 A particular protocol will have a descendant class from this to implement 338 the specific semantics of that protocols connection. 339 340 A connection is part of a call, and will be "owned" by an OpalCall object. 341 It is also attached to the creator endpoint to do any protocol specific 342 management of the connection. However the deletion of the connection is 343 done by a special thread in the OpalManager class. A connnection should 344 never be deleted directly. 345 346 The connection is also in charge of creating media streams. It may do this 347 in respose to an explicit call to OpenMediaStream or implicitly due to 348 requests in the underlying protocol. 349 350 When media streams are created they must make requests for bandwidth which 351 is managed by the connection. 352 */ 353 class OpalConnection : public PSafeObject 354 { 355 PCLASSINFO(OpalConnection, PSafeObject); 356 public: 357 /**Call/Connection ending reasons. 358 NOTE: if anything is added to this, you also need to add the field to 359 the tables in connection.cxx and h323pdu.cxx. 360 */ 361 enum CallEndReasonCodes { 362 EndedByLocalUser, /// Local endpoint application cleared call 363 EndedByNoAccept, /// Local endpoint did not accept call OnIncomingCall()=false 364 EndedByAnswerDenied, /// Local endpoint declined to answer call 365 EndedByRemoteUser, /// Remote endpoint application cleared call 366 EndedByRefusal, /// Remote endpoint refused call 367 EndedByNoAnswer, /// Remote endpoint did not answer in required time 368 EndedByCallerAbort, /// Remote endpoint stopped calling 369 EndedByTransportFail, /// Transport error cleared call 370 EndedByConnectFail, /// Transport connection failed to establish call 371 EndedByGatekeeper, /// Gatekeeper has cleared call 372 EndedByNoUser, /// Call failed as could not find user (in GK) 373 EndedByNoBandwidth, /// Call failed as could not get enough bandwidth 374 EndedByCapabilityExchange, /// Could not find common capabilities 375 EndedByCallForwarded, /// Call was forwarded using FACILITY message 376 EndedBySecurityDenial, /// Call failed a security check and was ended 377 EndedByLocalBusy, /// Local endpoint busy 378 EndedByLocalCongestion, /// Local endpoint congested 379 EndedByRemoteBusy, /// Remote endpoint busy 380 EndedByRemoteCongestion, /// Remote endpoint congested 381 EndedByUnreachable, /// Could not reach the remote party 382 EndedByNoEndPoint, /// The remote party is not running an endpoint 383 EndedByHostOffline, /// The remote party host off line 384 EndedByTemporaryFailure, /// The remote failed temporarily app may retry 385 EndedByQ931Cause, /// The remote ended the call with unmapped Q.931 cause code 386 EndedByDurationLimit, /// Call cleared due to an enforced duration limit 387 EndedByInvalidConferenceID, /// Call cleared due to invalid conference ID 388 EndedByNoDialTone, /// Call cleared due to missing dial tone 389 EndedByNoRingBackTone, /// Call cleared due to missing ringback tone 390 EndedByOutOfService, /// Call cleared because the line is out of service, 391 EndedByAcceptingCallWaiting, /// Call cleared because another call is answered 392 EndedByGkAdmissionFailed, /// Call cleared because gatekeeper admission request failed. 393 NumCallEndReasons 394 }; 395 396 struct CallEndReason { 397 CallEndReason( 398 CallEndReasonCodes reason = NumCallEndReasons, 399 unsigned cause = 0 codeCallEndReason400 ) : code(reason), q931(cause) { } CallEndReasonCallEndReason401 explicit CallEndReason( 402 long reason 403 ) : code((CallEndReasonCodes)(reason&0xff)), q931((reason>>8)&0xff) { } 404 CallEndReasonCodesCallEndReason405 __inline operator CallEndReasonCodes() const { return code; } 406 AsIntegerCallEndReason407 __inline int AsInteger() const { return code|(q931<<8); } 408 409 CallEndReasonCodes code:8; // Normalised OPAL code 410 unsigned q931:8; // PSTN Interworking code, actually Q.850 411 }; 412 413 #if PTRACING 414 friend ostream & operator<<(ostream & o, CallEndReason reason); 415 #endif 416 417 enum AnswerCallResponse { 418 AnswerCallNow, /// Answer the call continuing with the connection. 419 AnswerCallDenied, /// Refuse the call sending a release complete. 420 AnswerCallPending, /// Send an Alerting PDU and wait for AnsweringCall() 421 AnswerCallDeferred, /// As for AnswerCallPending but does not send Alerting PDU 422 AnswerCallAlertWithMedia, /// As for AnswerCallPending but starts media channels 423 AnswerCallDeferredWithMedia, /// As for AnswerCallDeferred but starts media channels 424 AnswerCallProgress, /// Answer the call with a h323 progress, or sip 183 session in progress, or ... 425 AnswerCallNowAndReleaseCurrent, /// Answer the call and destroy the current call 426 NumAnswerCallResponses 427 }; 428 #if PTRACING 429 friend ostream & operator<<(ostream & o, AnswerCallResponse s); 430 #endif 431 432 /** Connection options 433 */ 434 enum Options { 435 FastStartOptionDisable = 0x0001, // H.323 specific 436 FastStartOptionEnable = 0x0002, 437 FastStartOptionMask = 0x0003, 438 439 H245TunnelingOptionDisable = 0x0004, // H.323 specific 440 H245TunnelingOptionEnable = 0x0008, 441 H245TunnelingOptionMask = 0x000c, 442 443 H245inSetupOptionDisable = 0x0010, // H.323 specific 444 H245inSetupOptionEnable = 0x0020, 445 H245inSetupOptionMask = 0x0030, 446 447 DetectInBandDTMFOptionDisable = 0x0040, // SIP and H.323 448 DetectInBandDTMFOptionEnable = 0x0080, 449 DetectInBandDTMFOptionMask = 0x00c0, 450 451 RTPAggregationDisable = 0x0100, // SIP and H.323 452 RTPAggregationEnable = 0x0200, 453 RTPAggregationMask = 0x0300, 454 455 SendDTMFAsDefault = 0x0000, // SIP and H.323 456 SendDTMFAsString = 0x0400, 457 SendDTMFAsTone = 0x0800, 458 SendDTMFAsRFC2833 = 0x0c00, 459 SendDTMFMask = 0x0c00 460 }; 461 462 class StringOptions : public PStringOptions 463 { 464 public: 465 /** Extract the parameters that start with "OPAL-XXX" from the URL and 466 insert into the string options dictionary. The parameters are 467 removed from the URL. 468 */ 469 void ExtractFromURL( 470 PURL & url 471 ); 472 }; 473 474 /**@name Construction */ 475 //@{ 476 /**Create a new connection. 477 */ 478 OpalConnection( 479 OpalCall & call, ///< Owner calll for connection 480 OpalEndPoint & endpoint, ///< Owner endpoint for connection 481 const PString & token, ///< Token to identify the connection 482 unsigned options = 0, ///< Option bit map to be passed to connection 483 OpalConnection::StringOptions * stringOptions = NULL ///< Options to be passed to connection 484 ); 485 486 /**Destroy connection. 487 */ 488 ~OpalConnection(); 489 //@} 490 491 /**@name Overrides from PObject */ 492 //@{ 493 /**Standard stream print function. 494 The PObject class has a << operator defined that invokes this function 495 polymorphically. 496 */ 497 void PrintOn( 498 ostream & strm ///< Stream to output text representation 499 ) const; 500 //@} 501 502 /**@name Basic operations */ 503 //@{ 504 /**Get indication of connection being to a "network". 505 This indicates the if the connection may be regarded as a "network" 506 connection. The distinction is about if there is a concept of a "remote" 507 party being connected to and is best described by example: sip, h323, 508 iax and pstn are all "network" connections as they connect to something 509 "remote". While pc, pots and ivr are not as the entity being connected 510 to is intrinsically local. 511 512 As a rule a network connection would have different names returned by 513 GetLocalPartyName() and GetRemotePartyName() functions. A non-network 514 connection, for ease of use, has a unique value for GetLocalPartyName() 515 but, for convenience, uses the GetRemotePartyName() for the other 516 connection in the call for it's GetRemotePartyName(). 517 */ 518 virtual bool IsNetworkConnection() const = 0; 519 520 /**Different phases of a call, which are used in all OpalConnection 521 instances. These phases are fully described in the documentation page 522 \ref pageOpalConnections. */ 523 enum Phases { 524 UninitialisedPhase, //!< Indicates the OpalConnection instance has just been constructed 525 SetUpPhase, //!< Has just sent/received the initial SETUP/INVITE packet 526 ProceedingPhase, //!< The receipt of SETUP/INVITE has been acknowledged 527 AlertingPhase, //!< The remote says there is a phone ringing, somewhere 528 ConnectedPhase, //!< There is agreement on having a call, usually means billing will apply 529 EstablishedPhase, //!< Media is established, streams are all operational 530 ForwardingPhase, //!< Connection is in the process of being forwarded 531 ReleasingPhase, //!< Hangup packet has been sent/received, media and control not yet stopped 532 ReleasedPhase, //!< Media and control streams have been terminated 533 NumPhases //!< Number of available phases. Can be used to indicate an unknown phase 534 }; 535 536 /**Get the phase of the connection. 537 This indicates the current phase of the connection sequence. Whether 538 all phases and the transitions between phases is protocol dependent. 539 */ GetPhase()540 __inline Phases GetPhase() const { return m_phase; } 541 542 /// Return true if connection is in the established phase. IsEstablished()543 __inline bool IsEstablished() const { return m_phase == EstablishedPhase; } 544 545 /// Return true if connection is in the established phase. IsReleased()546 __inline bool IsReleased() const { return m_phase >= ReleasingPhase; } 547 548 /**Set the phase of the connection. 549 Note that this is primarily for internal use and calling from user code 550 is likely to have very strange results. 551 */ 552 void SetPhase( 553 Phases phaseToSet ///< phaseToSet the phase to set 554 ); 555 556 /**Get the reason for this connection shutting down. 557 Note that this function is only generally useful in the 558 OpalEndPoint::OnClearedCall() function. This is due to the 559 connection not being cleared before that, and the object not even 560 existing after that. 561 562 If the call is still active then this will return NumCallEndReasons. 563 */ GetCallEndReason()564 CallEndReason GetCallEndReason() const { return callEndReason; } 565 566 /**Get the reason for this connection shutting down as text. 567 */ 568 static PString GetCallEndReasonText(CallEndReason reason); GetCallEndReasonText()569 PString GetCallEndReasonText() const { return GetCallEndReasonText(callEndReason); } 570 571 /**Get the reason for this connection shutting down as text. 572 */ 573 static void SetCallEndReasonText(CallEndReasonCodes reasonCode, const PString & newText); 574 575 /**Set the call clearance reason. 576 An application should have no cause to use this function. It is present 577 for the H323EndPoint::ClearCall() function to set the clearance reason. 578 */ 579 virtual void SetCallEndReason( 580 CallEndReason reason ///< Reason for clearance of connection. 581 ); 582 583 /**Clear a current call. 584 This hangs up the current call. This will release all connections 585 currently in the call by calling the OpalCall::Clear() function. 586 587 Note that this function will return quickly as the release and 588 disposal of the connections is done by another thread. 589 590 If \p sync is not NULL then it is signalled when the calls are cleared. 591 */ 592 void ClearCall( 593 CallEndReason reason = EndedByLocalUser, ///< Reason for call clearing 594 PSyncPoint * sync = NULL 595 ); 596 597 /**Clear a current connection, synchronously. 598 This hangs up the connection to a remote endpoint. Note that this function 599 is always synchronous. If \p sync is NULL then a local PSyncPoint is used. 600 */ 601 virtual void ClearCallSynchronous( 602 PSyncPoint * sync, ///< Synchronisation object to signal 603 CallEndReason reason = EndedByLocalUser ///< Reason for call clearing 604 ); 605 606 /**Get the Q.931 cause code (Q.850) that terminated this call. 607 See Q931::CauseValues for common values. 608 */ GetQ931Cause()609 unsigned GetQ931Cause() const { return callEndReason.q931; } 610 611 /**Set the outgoing Q.931 cause code (Q.850) that is sent for this call 612 See Q931::CauseValues for common values. 613 */ SetQ931Cause(unsigned v)614 void SetQ931Cause(unsigned v) { callEndReason.q931 = v; } 615 616 /**Initiate the transfer of an existing call (connection) to a new remote 617 party. 618 619 If remoteParty is a valid call token, then the remote party is transferred 620 to that party (consultation transfer) and both calls are cleared. 621 */ 622 virtual bool TransferConnection( 623 const PString & remoteParty ///< Remote party to transfer the existing call to 624 ); 625 626 /**Put the current connection on hold, suspending all media streams. 627 The \p fromRemote parameter indicates if we a putting the remote on 628 hold (false) or it is a request for the remote to put us on hold (true). 629 630 The /p placeOnHold parameter indicates of teh command/request is for 631 going on hold or retrieving from hold. 632 */ 633 virtual bool Hold( 634 bool fromRemote, ///< Flag for if remote has us on hold, or we have them 635 bool placeOnHold ///< Flag for setting on or off hold 636 ); 637 638 /**Return true if the current connection is on hold. 639 The \p fromRemote parameter indicates if we are testing if the remote 640 system has us on hold, or we have them on hold. 641 */ 642 virtual bool IsOnHold( 643 bool fromRemote ///< Flag for if remote has us on hold, or we have them 644 ); 645 646 /**Call back indicating result of last hold/retrieve operation. 647 This also indicates if the local connection has been put on hold by the 648 remote connection. 649 */ 650 virtual void OnHold( 651 bool fromRemote, ///< Indicates remote has held local connection 652 bool onHold ///< Indicates have just been held/retrieved. 653 ); 654 //@} 655 656 /**@name Call progress functions */ 657 //@{ 658 /**Call back for an incoming call. 659 This function is used for an application to control the answering of 660 incoming calls. 661 662 If true is returned then the connection continues. If false then the 663 connection is aborted. 664 665 Note this function should not block for any length of time. If the 666 decision to answer the call may take some time eg waiting for a user to 667 pick up the phone, then AnswerCallPending or AnswerCallDeferred should 668 be returned. 669 670 If an application overrides this function, it should generally call the 671 ancestor version to complete calls. Unless the application completely 672 takes over that responsibility. Generally, an application would only 673 intercept this function if it wishes to do some form of logging. For 674 this you can obtain the name of the caller by using the function 675 OpalConnection::GetRemotePartyName(). 676 677 The default behaviour calls the OpalManager function of the same name. 678 679 Note that the most explicit version of this override is made pure, so as to force 680 descendant classes to implement it. This will only affect code that implements new 681 descendants of OpalConnection - code that uses existing descendants will be unaffected 682 */ 683 virtual PBoolean OnIncomingConnection(unsigned int options, OpalConnection::StringOptions * stringOptions); 684 685 /**Start an outgoing connection. 686 This function will initiate the connection to the remote entity, for 687 example in H.323 it sends a SETUP, in SIP it sends an INVITE etc. 688 689 The default behaviour is pure. 690 */ 691 virtual PBoolean SetUpConnection() = 0; 692 693 /**Callback for outgoing connection, it is invoked after SetUpConnection 694 This function allows the application to set up some parameters or to log some messages 695 */ 696 virtual PBoolean OnSetUpConnection(); 697 698 699 /**Call back for remote party is now responsible for completing the call. 700 This function is called when the remote system has been contacted and it 701 has accepted responsibility for completing, or failing, the call. This 702 is distinct from OnAlerting() in that it is not known at this time if 703 anything is ringing. This indication may be used to distinguish between 704 "transport" level error, in which case another host may be tried, and 705 that finalising the call has moved "upstream" and the local system has 706 no more to do but await a result. 707 708 If an application overrides this function, it should generally call the 709 ancestor version for correct operation. 710 711 The default behaviour calls the OpalEndPoint function of the same name. 712 */ 713 virtual void OnProceeding(); 714 715 /**Call back for remote party being alerted. 716 This function is called after the connection is informed that the 717 remote endpoint is "ringing". Generally some time after the 718 SetUpConnection() function was called, this is function is called. 719 720 If an application overrides this function, it should generally call the 721 ancestor version for correct operation. 722 723 The default behaviour calls the OpalEndPoint function of the same name. 724 */ 725 virtual void OnAlerting(); 726 727 /**Indicate to remote endpoint an alert is in progress. 728 If this is an incoming connection and the AnswerCallResponse is in a 729 AnswerCallDeferred or AnswerCallPending state, then this function is 730 used to indicate to that endpoint that an alert is in progress. This is 731 usually due to another connection which is in the call (the B party) 732 has received an OnAlerting() indicating that its remoteendpoint is 733 "ringing". 734 735 The default behaviour is pure. 736 */ 737 virtual PBoolean SetAlerting( 738 const PString & calleeName, ///< Name of endpoint being alerted. 739 PBoolean withMedia ///< Open media with alerting 740 ) = 0; 741 742 /**Call back for answering an incoming call. 743 This function is called after the connection has been acknowledged 744 but before the connection is established 745 746 This gives the application time to wait for some event before 747 signalling to the endpoint that the connection is to proceed. For 748 example the user pressing an "Answer call" button. 749 750 If AnswerCallDenied is returned the connection is aborted and the 751 connetion specific end call PDU is sent. If AnswerCallNow is returned 752 then the connection proceeding, Finally if AnswerCallPending is returned then the 753 protocol negotiations are paused until the AnsweringCall() function is 754 called. 755 756 The default behaviour calls the endpoint function of the same name. 757 */ 758 virtual AnswerCallResponse OnAnswerCall( 759 const PString & callerName ///< Name of caller 760 ); 761 762 /**Indicate the result of answering an incoming call. 763 This should only be called if the OnAnswerCall() callback function has 764 returned a AnswerCallPending or AnswerCallDeferred response. 765 766 Note sending further AnswerCallPending responses via this function will 767 have the result of notification PDUs being sent to the remote endpoint (if possible). 768 In this way multiple notification PDUs may be sent. 769 770 Sending a AnswerCallDeferred response would have no effect. 771 */ 772 virtual void AnsweringCall( 773 AnswerCallResponse response ///< Answer response to incoming call 774 ); 775 776 /**A call back function whenever a connection is "connected". 777 This indicates that a connection to an endpoint was connected. That 778 is the endpoint received acknowledgement via whatever protocol it uses 779 that the connection may now start media streams. 780 781 In the context of H.323 this means that the CONNECT pdu has been 782 received. 783 784 The default behaviour calls the OpalEndPoint function of the same name. 785 786 When this method is called, we are effectively being told that 787 the remote endpoint has accepted our call and is now sending 788 media to us. 789 */ 790 virtual void OnConnected(); 791 792 /**Indicate to remote endpoint we are connected. 793 794 The default behaviour sets the phase to ConnectedPhase, sets the 795 connection start time and then checks if there is any media channels 796 opened and if so, moves on to the established phase, calling 797 OnEstablished(). 798 799 In other words, this method is used to handle incoming calls, 800 and is an indication that we have accepted the incoming call. 801 */ 802 virtual PBoolean SetConnected(); 803 804 /**A call back function whenever a connection is established. 805 This indicates that a connection to an endpoint was established. This 806 usually occurs after OnConnected() and indicates that the connection 807 is both connected and has media flowing. 808 809 In the context of H.323 this means that the signalling and control 810 channels are open and the TerminalCapabilitySet and MasterSlave 811 negotiations are complete. 812 813 The default behaviour calls the OpalEndPoint function of the same name. 814 */ 815 virtual void OnEstablished(); 816 817 /**A call back function to monitor the progress of a transfer. 818 When a transfer operation is initiated, the Transfer() function will 819 generally return immediately and the transfer may take some time. This 820 call back can give an indication to the application of the progress of 821 the transfer. 822 the transfer. 823 824 For example in SIP, the OpalCall::Transfer() function will have sent a 825 REFER request to the remote party. The remote party sends us NOTIFY 826 requests about the progress of the REFER request. 827 828 An application can now make a decision during the transfer operation 829 to short circuit the sequence, or let it continue. It can also 830 determine if the transfer did not go through, and it should "take back" 831 the call. Note no action is required to "take back" the call other than 832 indicate to the user that they are back on. 833 834 A return value of false will immediately disconnect the current call. 835 836 The exact format of the \p info parameter is dependent on the protocol 837 being used. As a minimum, it will always have a values info["result"] 838 and info["party"]. 839 840 The info["party"] indicates the part the \p connection is playing in 841 the transfer. This will be: 842 "A" party being transferred 843 "B" party initiating the transfer of "A" 844 "C" party "A" is being transferred to 845 846 The info["result"] will be at least one of the following: 847 "success" Transfer completed successfully (party A or B) 848 "incoming" New call was from a transfer (party C) 849 "started" Transfer operation has started (party A) 850 "progress" Transfer is in progress (party B) 851 "blind" Transfer is blind, no further notification (party B) 852 "error" Transfer could not begin (party B) 853 "failed" Transfer started but did not complete (party A or B) 854 855 For SIP, there may be an additional info["state"] containing the NOTIFY 856 subscription state, an info["code"] entry containing the 3 digit 857 code returned in the NOTIFY body and info["Referred-By"] indicating the 858 URI of party B. Other fields may also be present. 859 860 The default behaviour calls the OpalEndPoint function of the same name. 861 The default action of that function is to return false, thereby 862 releasing the connection if the info["result"] == "success". 863 */ 864 virtual bool OnTransferNotify( 865 const PStringToString & info, ///< State of the transfer 866 const OpalConnection * transferringConnection 867 ///< Connection performing transfer, maybe "this" 868 ); 869 870 /**Release the current connection. 871 This removes the connection from the current call. The call may 872 continue if there are other connections still active on it. If this was 873 the last connection for the call then the call is disposed of as well. 874 875 Note that this function will return quickly as the release and 876 disposal of the connections is done by another thread. 877 */ 878 virtual void Release( 879 CallEndReason reason = EndedByLocalUser, ///< Reason for call release 880 bool synchronous = false ///< If true spawns thread to release connection 881 ); 882 883 /**Clean up the termination of the connection. 884 This function can do any internal cleaning up and waiting on background 885 threads that may be using the connection object. 886 887 Note that there is not a one to one relationship with the 888 OnEstablishedConnection() function. This function may be called without 889 that function being called. For example if SetUpConnection() was used 890 but the call never completed. 891 892 Classes that override this function should make sure they call the 893 ancestor version for correct operation. 894 895 An application will not typically call this function as it is used by 896 the OpalManager during a release of the connection. 897 898 The default behaviour calls the OpalEndPoint function of the same name. 899 */ 900 virtual void OnReleased(); 901 //@} 902 903 /**@name Additional signalling functions */ 904 //@{ 905 /**Get the destination address of an incoming connection. 906 This will, for example, collect a phone number from a POTS line, or 907 get the fields from the H.225 SETUP pdu in a H.323 connection, or 908 INVITE for SIP connection. 909 910 The default behaviour returns "*", which by convention means any 911 address the endpoint/connection can get to. 912 */ 913 virtual PString GetDestinationAddress(); 914 915 /**Forward incoming call to specified address. 916 This would typically be called from within the OnIncomingCall() 917 function when an application wishes to redirct an unwanted incoming 918 call. 919 920 The return value is true if the call is to be forwarded, false 921 otherwise. Note that if the call is forwarded the current connection is 922 cleared with teh ended call code of EndedByCallForwarded. 923 */ 924 virtual PBoolean ForwardCall( 925 const PString & forwardParty ///< Party to forward call to. 926 ); 927 928 /**Get the other connection in the call, if there is one. 929 */ 930 PSafePtr<OpalConnection> GetOtherPartyConnection() const; 931 932 /**Get the other connection in the call, if there is one. 933 */ GetOtherPartyConnectionAs()934 template <class cls> PSafePtr<cls> GetOtherPartyConnectionAs() const { return PSafePtrCast<OpalConnection, cls>(GetOtherPartyConnection()); } 935 //@} 936 937 /**@name Media Stream Management */ 938 //@{ 939 /**Get the data formats this connection is capable of operating. 940 This provides a list of media data format names that a 941 OpalMediaStream may be created in within this connection. 942 943 The default behaviour calls GetMediaFormats() on the endpoint. 944 */ 945 virtual OpalMediaFormatList GetMediaFormats() const; 946 947 /**Get the list of data formats used for making calls 948 949 The default behaviour is to call GetMediaFormats() on the owner call. 950 */ 951 virtual OpalMediaFormatList GetLocalMediaFormats(); 952 953 /**Adjust media formats available on a connection. 954 This is called by a connection after it has called 955 OpalCall::GetMediaFormats() to get all media formats that it can use so 956 that an application may remove or reorder the media formats before they 957 are used to open media streams. 958 959 This function may also be executed by other connections in the call. If 960 this happens then the "otherConnection" parameter will be non-NULL. The 961 "local" parameter sense is relative to the "otherConnection" parameter, 962 if NULL then it is relative to "this". 963 964 The default behaviour calls the OpalEndPoint function of the same name. 965 */ 966 virtual void AdjustMediaFormats( 967 bool local, ///< Media formats a local ones to be presented to remote 968 const OpalConnection * otherConnection, ///< Other connection we are adjusting media for 969 OpalMediaFormatList & mediaFormats ///< Media formats to use 970 ) const; 971 972 /**Get next available session ID for the media type. 973 974 Default behaviour returns zero indicating that this connection type 975 does not care what the session ID is, and the other connection in the 976 call should be asked. If neither care, then teh default of the media 977 type is used. 978 */ 979 virtual unsigned GetNextSessionID( 980 const OpalMediaType & mediaType, ///< Media type of stream being opened 981 bool isSource ///< Stream is a source/sink 982 ); 983 984 /** Indicate whether a particular media type can auto-start. 985 This is typically used for things like video or fax to contol if on 986 initial connection, that media type is opened straight away. Streams 987 of that type may be opened later, during the call, by using the 988 OpalCall::OpenSourceMediaStreams() function. 989 */ 990 virtual OpalMediaType::AutoStartMode GetAutoStart( 991 const OpalMediaType & mediaType ///< media type to check 992 ) const; 993 994 /**Open source media streams, if needed. 995 */ 996 virtual void AutoStartMediaStreams( 997 bool force = false ///< Force re-open even if already open 998 ); 999 1000 #if OPAL_FAX 1001 /**Switch to/from T.38 mode. 1002 */ 1003 virtual bool SwitchFaxMediaStreams( 1004 bool toT38 ///< Enable T.38 or return to audio mode 1005 ); 1006 1007 /**Indicate status of switch to/from T.38 mode. 1008 1009 Default behaviour does nothing. 1010 */ 1011 virtual void OnSwitchedFaxMediaStreams( 1012 bool toT38, ///< Were switching to T.38 or audio mode 1013 bool success ///< Switch succeeded or failed 1014 ); 1015 1016 /**Indicate remote is requesting switch to/from T.38 fax mode. 1017 1018 Default behaviour calls the same function on the other connection. 1019 */ 1020 virtual bool OnSwitchingFaxMediaStreams( 1021 bool toT38 ///< Is switching to T.38 or audio mode 1022 ); 1023 #endif 1024 1025 /**Open source or sink media stream for session. 1026 */ 1027 virtual OpalMediaStreamPtr OpenMediaStream( 1028 const OpalMediaFormat & mediaFormat, ///< Media format to open 1029 unsigned sessionID, ///< Session to start stream on 1030 bool isSource ///< Stream is a source/sink 1031 ); 1032 1033 /**Close of a media stream by session. 1034 */ 1035 virtual bool CloseMediaStream( 1036 unsigned sessionId, ///< Session ID to search for. 1037 bool source ///< Indicates the direction of stream. 1038 ); 1039 1040 /**Close of a specific media stream. 1041 */ 1042 virtual bool CloseMediaStream( 1043 OpalMediaStream & stream ///< Stream to close 1044 ); 1045 1046 /**Remove the specified media stream from the list of streams for this channel. 1047 This will automatically delete the stream if the stream was found in the 1048 stream list. 1049 1050 Returns true if the media stream was removed the list and deleted, else 1051 returns false if the media stream was unchanged 1052 */ 1053 bool RemoveMediaStream( 1054 OpalMediaStream & strm ///< media stream to remove 1055 ); 1056 1057 /**Start all media streams for connection. 1058 */ 1059 virtual void StartMediaStreams(); 1060 1061 /**Request close all media streams on connection. 1062 */ 1063 virtual void CloseMediaStreams(); 1064 1065 /**Pause media streams for connection. 1066 */ 1067 virtual void PauseMediaStreams( 1068 bool paused ///< Flag for pausing/un-pausing 1069 ); 1070 1071 /**Pause media streams for connection. 1072 */ 1073 virtual void OnPauseMediaStream( 1074 OpalMediaStream & strm, ///< Media stream paused/un-paused 1075 bool paused ///< Flag for pausing/un-pausing 1076 ); 1077 1078 /**Create a new media stream. 1079 This will create a media stream of an appropriate subclass as required 1080 by the underlying connection protocol. For instance H.323 would create 1081 an OpalRTPStream. 1082 1083 The sessionID parameter may not be needed by a particular media stream 1084 and may be ignored. In the case of an OpalRTPStream it us used. 1085 1086 Note that media streams may be created internally to the underlying 1087 protocol. This function is not the only way a stream can come into 1088 existance. 1089 */ 1090 virtual OpalMediaStream * CreateMediaStream( 1091 const OpalMediaFormat & mediaFormat, ///< Media format for stream 1092 unsigned sessionID, ///< Session number for stream 1093 PBoolean isSource ///< Is a source stream 1094 ); 1095 1096 /**Get a media stream. 1097 Locates a stream given an identifier string. 1098 1099 If streamID is an empty string, then the first source/sink stream 1100 of any type, session or id is returned. 1101 */ 1102 OpalMediaStreamPtr GetMediaStream( 1103 const PString & streamID, ///< Stream ID to search for. 1104 bool source ///< Indicates the direction of stream. 1105 ) const; 1106 1107 /**Get a media stream. 1108 Locates a stream given a RTP session ID. Each session would usually 1109 have two media streams associated with it, so the source flag 1110 may be used to distinguish which channel to return. 1111 */ 1112 OpalMediaStreamPtr GetMediaStream( 1113 unsigned sessionId, ///< Session ID to search for. 1114 bool source ///< Indicates the direction of stream. 1115 ) const; 1116 1117 /**Get a media stream. 1118 Locates a stream given a media type. The source flag may be used to 1119 distinguish which stream durection to return. 1120 1121 If mediaType is empty (i.e. OpalMediaType()), then the first 1122 source/sink stream of any type, session or id is returned. 1123 1124 The previous parameter may be used to enumerate multiple stream of the 1125 same type and direction. If NULL then the first stream is returned. 1126 */ 1127 OpalMediaStreamPtr GetMediaStream( 1128 const OpalMediaType & mediaType, ///< Media type to search for. 1129 bool source, ///< Indicates the direction of stream. 1130 OpalMediaStreamPtr previous = NULL ///< Previous stream to start search from 1131 ) const; 1132 1133 /**Call back when opening a media stream. 1134 This function is called when a connection has created a new media 1135 stream according to the logic of its underlying protocol. 1136 1137 The usual requirement is that media streams are created on all other 1138 connections participating in the call and all of the media streams are 1139 attached to an instance of an OpalMediaPatch object that will read from 1140 one of the media streams passing data to the other media streams. 1141 1142 The default behaviour calls the OpalEndPoint function of the same name. 1143 */ 1144 virtual PBoolean OnOpenMediaStream( 1145 OpalMediaStream & stream ///< New media stream being opened 1146 ); 1147 1148 /**Call back for closed a media stream. 1149 1150 The default behaviour calls the OpalEndPoint function of the same name. 1151 */ 1152 virtual void OnClosedMediaStream( 1153 const OpalMediaStream & stream ///< Media stream being closed 1154 ); 1155 1156 /**Call back when patching a media stream. 1157 This function is called when a connection has created a new media 1158 patch between two streams. This is usually called twice per media patch, 1159 once for the source stream and once for the sink stream. 1160 1161 Note this is not called within the context of the patch thread and is 1162 called before that thread has started. 1163 */ 1164 virtual void OnPatchMediaStream( 1165 PBoolean isSource, ///< Is source/sink call 1166 OpalMediaPatch & patch ///< New patch 1167 ); 1168 1169 /**Call back when media stream patch thread starts. 1170 */ 1171 virtual void OnStartMediaPatch( 1172 OpalMediaPatch & patch ///< Patch being started 1173 ); 1174 1175 /**Call back when media stream patch thread stops. 1176 */ 1177 virtual void OnStopMediaPatch( 1178 OpalMediaPatch & patch ///< Patch being stopped 1179 ); 1180 1181 /** Callback for media commands. 1182 Calls the SendIntraFrameRequest on the rtp session 1183 1184 @returns true if command is handled. 1185 */ 1186 virtual bool OnMediaCommand( 1187 OpalMediaStream & stream, ///< Stream command executed on 1188 const OpalMediaCommand & command ///< Media command being executed 1189 ); 1190 1191 /**Attaches the RFC 2833 handler to the media patch 1192 This method may be called from subclasses, e.g. within 1193 OnPatchMediaStream() 1194 */ 1195 virtual void AttachRFC2833HandlerToPatch(PBoolean isSource, OpalMediaPatch & patch); 1196 1197 /**See if the media can bypass the local host. 1198 1199 The default behaviour returns false indicating that media bypass is not 1200 possible. 1201 */ 1202 virtual PBoolean IsMediaBypassPossible( 1203 unsigned sessionID ///< Session ID for media channel 1204 ) const; 1205 1206 #if OPAL_VIDEO 1207 /**Create an PVideoInputDevice for a source media stream. 1208 */ 1209 virtual PBoolean CreateVideoInputDevice( 1210 const OpalMediaFormat & mediaFormat, ///< Media format for stream 1211 PVideoInputDevice * & device, ///< Created device 1212 PBoolean & autoDelete ///< Flag for auto delete device 1213 ); 1214 1215 /**Create an PVideoOutputDevice for a sink media stream or the preview 1216 display for a source media stream. 1217 */ 1218 virtual PBoolean CreateVideoOutputDevice( 1219 const OpalMediaFormat & mediaFormat, ///< Media format for stream 1220 PBoolean preview, ///< Flag indicating is a preview output 1221 PVideoOutputDevice * & device, ///< Created device 1222 PBoolean & autoDelete ///< Flag for auto delete device 1223 ); 1224 1225 /** Send a Video Update Picture request to media stream. 1226 If \p force is set then a "force Intra frame" is sent, otherwise a 1227 "picture loss" is sent. The underlying protocol may or may not make a 1228 distinction. 1229 */ 1230 virtual bool SendVideoUpdatePicture( 1231 unsigned sessionID = 0, ///< Session for media stream, 0 is use first Video stream 1232 bool force = false ///< Indicate is a picture loss or forced I-Frame 1233 ) const; 1234 #endif 1235 1236 /**Set the volume (gain) for the audio media channel. 1237 The volume range is 0 == muted, 100 == LOUDEST. 1238 */ 1239 virtual PBoolean SetAudioVolume( 1240 PBoolean source, ///< true for source (microphone), false for sink (speaker) 1241 unsigned percentage ///< Gain, 0=silent, 100=maximun 1242 ); 1243 1244 /**Get the volume (gain) for the audio media channel. 1245 The volume range is 0 == muted, 100 == LOUDEST. 1246 */ 1247 virtual PBoolean GetAudioVolume( 1248 PBoolean source, ///< true for source (microphone), false for sink (speaker) 1249 unsigned & percentage ///< Gain, 0=silent, 100=maximun 1250 ); 1251 1252 /**Set the mute state for the audio media channel. 1253 */ 1254 virtual bool SetAudioMute( 1255 bool source, ///< true for source (microphone), false for sink (speaker) 1256 bool mute ///< Flag for muted audio 1257 ); 1258 1259 /**Get the mute state for the audio media channel. 1260 */ 1261 virtual bool GetAudioMute( 1262 bool source, ///< true for source (microphone), false for sink (speaker) 1263 bool & mute ///< Flag for muted audio 1264 ); 1265 1266 /**Get the average signal level (0..32767) for the audio media channel. 1267 A return value of UINT_MAX indicates no valid signal, eg no audio channel opened. 1268 */ 1269 virtual unsigned GetAudioSignalLevel( 1270 PBoolean source ///< true for source (microphone), false for sink (speaker) 1271 ); 1272 //@} 1273 1274 /**@name Bandwidth Management */ 1275 //@{ 1276 /**Get the available bandwidth in 100's of bits/sec. 1277 */ GetBandwidthAvailable()1278 unsigned GetBandwidthAvailable() const { return bandwidthAvailable; } 1279 1280 /**Set the available bandwidth in 100's of bits/sec. 1281 Note if the force parameter is true this function will close down 1282 active media streams to meet the new bandwidth requirement. 1283 */ 1284 virtual PBoolean SetBandwidthAvailable( 1285 unsigned newBandwidth, ///< New bandwidth limit 1286 PBoolean force = false ///< Force bandwidth limit 1287 ); 1288 1289 /**Get the bandwidth currently used. 1290 This totals the bandwidth used by open streams and returns the total 1291 bandwidth used in 100's of bits/sec 1292 */ 1293 virtual unsigned GetBandwidthUsed() const; 1294 1295 /**Set the used bandwidth in 100's of bits/sec. 1296 This is an internal function used by the OpalMediaStream bandwidth 1297 management code. 1298 1299 If there is insufficient bandwidth available, false is returned. If 1300 sufficient bandwidth is available, then true is returned and the amount 1301 of available bandwidth is reduced by the specified amount. 1302 */ 1303 virtual PBoolean SetBandwidthUsed( 1304 unsigned releasedBandwidth, ///< Bandwidth to release 1305 unsigned requiredBandwidth ///< Bandwidth required 1306 ); 1307 //@} 1308 1309 /**@name User input */ 1310 //@{ 1311 enum SendUserInputModes { 1312 SendUserInputAsQ931, 1313 SendUserInputAsString, 1314 SendUserInputAsTone, 1315 SendUserInputAsRFC2833, 1316 SendUserInputInBand, 1317 SendUserInputAsProtocolDefault, 1318 NumSendUserInputModes, 1319 1320 SendUserInputAsInlineRFC2833 = SendUserInputAsRFC2833 // For backward compatibility 1321 }; 1322 #if PTRACING 1323 friend ostream & operator<<(ostream & o, SendUserInputModes m); 1324 #endif 1325 1326 /**Set the user input indication transmission mode. 1327 */ 1328 virtual void SetSendUserInputMode(SendUserInputModes mode); 1329 1330 /**Get the user input indication transmission mode. 1331 */ GetSendUserInputMode()1332 virtual SendUserInputModes GetSendUserInputMode() const { return sendUserInputMode; } 1333 1334 /**Get the real user input indication transmission mode. 1335 This will return the user input mode that will actually be used for 1336 transmissions. It will be the value of GetSendUserInputMode() provided 1337 the remote endpoint is capable of that mode. 1338 */ GetRealSendUserInputMode()1339 virtual SendUserInputModes GetRealSendUserInputMode() const { return GetSendUserInputMode(); } 1340 1341 /**Send a user input indication to the remote endpoint. 1342 This is for sending arbitrary strings as user indications. 1343 1344 The default behaviour is to call SendUserInputTone() for each character 1345 in the string. 1346 */ 1347 virtual PBoolean SendUserInputString( 1348 const PString & value ///< String value of indication 1349 ); 1350 1351 /**Send a user input indication to the remote endpoint. 1352 This sends DTMF emulation user input. If something more sophisticated 1353 than the simple tones that can be sent using the SendUserInput() 1354 function. 1355 1356 A duration of zero indicates that no duration is to be indicated. 1357 A non-zero logical channel indicates that the tone is to be syncronised 1358 with the logical channel at the rtpTimestamp value specified. 1359 1360 The tone parameter must be one of "0123456789#*ABCD!" where '!' 1361 indicates a hook flash. If tone is a ' ' character then a 1362 signalUpdate PDU is sent that updates the last tone indication 1363 sent. See the H.245 specifcation for more details on this. 1364 1365 The default behaviour sends the tone using RFC2833. 1366 */ 1367 virtual PBoolean SendUserInputTone( 1368 char tone, ///< DTMF tone code 1369 unsigned duration = 0 ///< Duration of tone in milliseconds 1370 ); 1371 1372 /**Call back for remote enpoint has sent user input as a string. 1373 This will be called irrespective of the source (H.245 string, H.245 1374 signal or RFC2833). 1375 1376 The default behaviour calls the endpoint function of the same name. 1377 */ 1378 virtual void OnUserInputString( 1379 const PString & value ///< String value of indication 1380 ); 1381 1382 /**Call back for remote enpoint has sent user input. 1383 If duration is zero then this indicates the beginning of the tone. If 1384 duration is non-zero then it indicates the end of the tone output. 1385 1386 The default behaviour calls the OpalEndPoint function of the same name. 1387 */ 1388 virtual void OnUserInputTone( 1389 char tone, 1390 unsigned duration 1391 ); 1392 1393 /**Send a user input indication to the remote endpoint. 1394 This sends a Hook Flash emulation user input. 1395 */ 1396 void SendUserInputHookFlash( 1397 unsigned duration = 500 ///< Duration of tone in milliseconds 1398 ) { SendUserInputTone('!', duration); } 1399 1400 /**Get a user input indication string, waiting until one arrives. 1401 */ 1402 virtual PString GetUserInput( 1403 unsigned timeout = 30 ///< Timeout in seconds on input 1404 ); 1405 1406 /**Set a user indication string. 1407 This allows the GetUserInput() function to unblock and return this 1408 string. 1409 */ 1410 virtual void SetUserInput( 1411 const PString & input ///< Input string 1412 ); 1413 1414 /**Read a sequence of user indications with timeouts. 1415 */ 1416 virtual PString ReadUserInput( 1417 const char * terminators = "#\r\n", ///< Characters that can terminte input 1418 unsigned lastDigitTimeout = 4, ///< Timeout on last digit in string 1419 unsigned firstDigitTimeout = 30 ///< Timeout on receiving any digits 1420 ); 1421 1422 /**Play a prompt to the connection before rading user indication string. 1423 1424 For example the LID connection would play a dial tone. 1425 1426 The default behaviour does nothing. 1427 */ 1428 virtual PBoolean PromptUserInput( 1429 PBoolean play ///< Flag to start or stop playing the prompt 1430 ); 1431 //@} 1432 1433 /** Execute garbage collection for endpoint. 1434 Returns true if all garbage has been collected. 1435 Default behaviour deletes the objects in the connectionsActive list. 1436 */ 1437 virtual bool GarbageCollection(); 1438 //@} 1439 1440 /**@name Member variable access */ 1441 //@{ 1442 /**Get the owner endpoint for this connection. 1443 */ GetEndPoint()1444 OpalEndPoint & GetEndPoint() const { return endpoint; } 1445 1446 /**Get the owner call for this connection. 1447 */ GetCall()1448 OpalCall & GetCall() const { return ownerCall; } 1449 1450 /**Get the token for this connection. 1451 */ GetToken()1452 const PString & GetToken() const { return callToken; } 1453 1454 /**Get the call direction for this connection. 1455 */ IsOriginating()1456 PBoolean IsOriginating() const { return originating; } 1457 1458 /**Get the time at which the phase of the call was entered. 1459 */ GetPhaseTime(Phases phase)1460 const PTime & GetPhaseTime(Phases phase) const { return m_phaseTime[phase]; } 1461 1462 /**Get the time at which the connection was begun 1463 */ GetSetupUpTime()1464 const PTime & GetSetupUpTime() const { return m_phaseTime[SetUpPhase]; } 1465 1466 /**Get the time at which the ALERTING/18x was received 1467 */ GetAlertingTime()1468 const PTime & GetAlertingTime() const { return m_phaseTime[AlertingPhase]; } 1469 1470 /**Get the time at which the connection was started. 1471 This is where the H.323 CONNECT or SIP 200 OK is received and generally 1472 indicates the start of te billable period for a call. 1473 */ GetConnectionStartTime()1474 const PTime & GetConnectionStartTime() const { return m_phaseTime[ConnectedPhase]; } 1475 1476 /**Get the time at which the connection was cleared 1477 */ GetConnectionEndTime()1478 const PTime & GetConnectionEndTime() const { return m_phaseTime[ReleasingPhase]; } 1479 1480 /**Get the product info for all endpoints. 1481 */ GetProductInfo()1482 const OpalProductInfo & GetProductInfo() const { return productInfo; } 1483 1484 /**Set the product info for all endpoints. 1485 */ SetProductInfo(const OpalProductInfo & info)1486 void SetProductInfo( 1487 const OpalProductInfo & info 1488 ) { productInfo = info; } 1489 1490 /**Get this connections protocol prefix for URLs. 1491 */ 1492 virtual PString GetPrefixName() const; 1493 1494 /**Get the local name/alias. 1495 */ GetLocalPartyName()1496 const PString & GetLocalPartyName() const { return localPartyName; } 1497 1498 /**Set the local name/alias. 1499 */ 1500 virtual void SetLocalPartyName(const PString & name); 1501 1502 /**Get the local name/alias. 1503 */ 1504 virtual PString GetLocalPartyURL() const; 1505 1506 /**Get the local display name. 1507 */ GetDisplayName()1508 const PString & GetDisplayName() const { return displayName; } 1509 1510 /**Set the local display name. 1511 */ SetDisplayName(const PString & name)1512 void SetDisplayName(const PString & name) { displayName = name; } 1513 1514 /**Determine if remote presentation of Caller-ID is to be blocked. 1515 Applies to an outgoing call to a "network" based endpoint type. 1516 Corresponds to Q.931 Calling-Party-Number Information Elementin H.323. 1517 Will remove display name for SIP. 1518 */ 1519 virtual bool IsPresentationBlocked() const; 1520 1521 /**Get the remote party display name. 1522 */ GetRemotePartyName()1523 const PString & GetRemotePartyName() const { return remotePartyName; } 1524 1525 /**Set the remote party display name. 1526 */ SetRemotePartyName(const PString & name)1527 void SetRemotePartyName(const PString & name) { remotePartyName = name; } 1528 1529 /**Get the remote party number, if there was one one. 1530 If the remote party has indicated an E.1164 number as one of its aliases 1531 or some other field such as Q.931 Calling-Party-Number, then this function 1532 will return that number. 1533 1534 Note if none of the remote names are a legal E.164 number then an empty 1535 string is returned. 1536 */ GetRemotePartyNumber()1537 const PString & GetRemotePartyNumber() const { return remotePartyNumber; } 1538 1539 /**Get the remote party address. 1540 This is typically a URL like sip:user\@hostname, though it may be just a host 1541 address. It should not be used as a "call back" address, use the 1542 GetRemotePartyURL() function for that purpose. 1543 */ GetRemotePartyAddress()1544 const PString & GetRemotePartyAddress() const { return remotePartyAddress; } 1545 1546 /**Set the remote party address. 1547 */ SetRemotePartyAddress(const PString & addr)1548 void SetRemotePartyAddress(const PString & addr) { remotePartyAddress = addr; } 1549 1550 /**Get the remote party address as URL. 1551 This will return the "best guess" at an address to use in a 1552 to call the user again later. Note that under some circumstances this may be 1553 different to the value GetRemotePartyAddress() value returns. In particular 1554 if a gatekeeper is involved. 1555 */ 1556 virtual PString GetRemotePartyURL() const; 1557 1558 /**Get the redirecting party. 1559 This is the party that caused an incoming call to arrive at this endpoint. 1560 */ GetRedirectingParty()1561 const PString & GetRedirectingParty() const { return m_redirectingParty; } 1562 1563 /**Set the redirecting party. 1564 This is the party that caused an incoming call to arrive at this endpoint. 1565 */ SetRedirectingParty(const PString & party)1566 void SetRedirectingParty(const PString & party) { m_redirectingParty = party; } 1567 1568 // Deprecated - backward compatibility only GetRemotePartyCallbackURL()1569 const PString GetRemotePartyCallbackURL() const { return GetRemotePartyURL(); } 1570 1571 /**Get the remote application description. This is for backward 1572 compatibility and has been supercedded by GeREmoteProductInfo(); 1573 */ GetRemoteApplication()1574 PCaselessString GetRemoteApplication() const { return remoteProductInfo.AsString(); } 1575 1576 /** Get the remote product info. 1577 */ GetRemoteProductInfo()1578 const OpalProductInfo & GetRemoteProductInfo() const { return remoteProductInfo; } 1579 1580 1581 /**Get the called alias name (for incoming calls). This is useful for gateway 1582 applications where the destination name may not be the same as the local name. 1583 1584 Note that if the called party is anm E.164 address and there are no alternative 1585 names, such as aliases in H.323, then this field will be empty. 1586 */ GetCalledPartyName()1587 const PString & GetCalledPartyName() const { return m_calledPartyName; } 1588 1589 /**Get the called E.164 number (for incoming calls). This is useful for gateway 1590 applications where the destination number may not be the same as the local number. 1591 1592 Note that if the incoming call does not contain a legal E.164 number in it's 1593 addressing then this will return an empty string. 1594 */ GetCalledPartyNumber()1595 const PString & GetCalledPartyNumber() const { return m_calledPartyNumber; } 1596 1597 /**Get the fulll URL being indicated by the remote for incoming calls. This may 1598 not have any relation to the local name of the endpoint. 1599 1600 The default behaviour returns GetDestinationAddress() normalised to a URL. 1601 The remote may provide a full URL, if it does not then the prefix for the 1602 endpoint is prepended to the destination address. 1603 */ 1604 virtual PString GetCalledPartyURL(); 1605 1606 /* Internal function to copy party names from "network" connection to 1607 "non-network" connection such as OpalPCSSConnection. This allows 1608 the non-network GetRemoteAddress() function and its ilk to return 1609 the intuitive value, i.e. the value from the OTHER connection. 1610 */ 1611 void CopyPartyNames(const OpalConnection & other); 1612 1613 1614 /**Get alerting type information of an incoming call. 1615 The type of "distinctive ringing" for the call. The string is protocol 1616 dependent, so the caller would need to be aware of the type of call 1617 being made. Some protocols may ignore the field completely. 1618 1619 For SIP this corresponds to the string contained in the "Alert-Info" 1620 header field of the INVITE. This is typically a URI for the ring file. 1621 1622 For H.323 this must be a string representation of an integer from 0 to 7 1623 which will be contained in the Q.931 SIGNAL (0x34) Information Element. 1624 1625 Default behaviour returns an empty string. 1626 */ 1627 virtual PString GetAlertingType() const; 1628 1629 /**Set alerting type information for outgoing call. 1630 The type of "distinctive ringing" for the call. The string is protocol 1631 dependent, so the caller would need to be aware of the type of call 1632 being made. Some protocols may ignore the field completely. 1633 1634 For SIP this corresponds to the string contained in the "Alert-Info" 1635 header field of the INVITE. This is typically a URI for the ring file. 1636 1637 For H.323 this must be a string representation of an integer from 0 to 7 1638 which will be contained in the Q.931 SIGNAL (0x34) Information Element. 1639 1640 Default behaviour returns false. 1641 */ 1642 virtual bool SetAlertingType(const PString & info); 1643 1644 /**Get call information of an incoming call. 1645 This is protocol dependent information provided about the call. The 1646 details are outside the scope of this help. 1647 1648 For SIP this corresponds to the string contained in the "Call-Info" 1649 header field of the INVITE. 1650 */ 1651 virtual PString GetCallInfo() const; 1652 1653 /**Get the default maximum audio jitter delay parameter. 1654 Defaults to 50ms 1655 */ GetMinAudioJitterDelay()1656 unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; } 1657 1658 /**Get the default maximum audio delay jitter parameter. 1659 Defaults to 250ms. 1660 */ GetMaxAudioJitterDelay()1661 unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; } 1662 1663 /**Set the maximum audio delay jitter parameter. 1664 */ 1665 void SetAudioJitterDelay( 1666 unsigned minDelay, ///< New minimum jitter buffer delay in milliseconds 1667 unsigned maxDelay ///< New maximum jitter buffer delay in milliseconds 1668 ); 1669 1670 /**Get the silence detector active on connection. 1671 */ GetSilenceDetector()1672 OpalSilenceDetector * GetSilenceDetector() const { return silenceDetector; } 1673 1674 #if OPAL_AEC 1675 /**Get the echo canceler active on connection. 1676 */ GetEchoCanceler()1677 OpalEchoCanceler * GetEchoCanceler() const { return echoCanceler; } 1678 #endif 1679 1680 /**Get the protocol-specific unique identifier for this connection. 1681 Default behaviour just returns the connection token. 1682 */ 1683 virtual PString GetIdentifier() const; 1684 1685 /**Get the maximum transmitted RTP payload size. 1686 This function allows a user to override the value returned on a 1687 connection by connection basis, for example knowing the connection is 1688 on a LAN with ethernet MTU the payload size could be increased. 1689 1690 Defaults to the value returned by the OpalManager function of the same 1691 name. 1692 */ 1693 virtual PINDEX GetMaxRtpPayloadSize() const; 1694 GetTransport()1695 virtual OpalTransport & GetTransport() const 1696 { return *(OpalTransport *)NULL; } 1697 1698 PDICTIONARY(MediaAddressesDict, POrdinalKey, OpalTransportAddress); GetMediaTransportAddresses()1699 MediaAddressesDict & GetMediaTransportAddresses() 1700 { return mediaTransportAddresses; } 1701 1702 #if OPAL_STATISTICS 1703 /**Get Video Update requests statistic. 1704 */ GetVideoUpdateRequestsSent()1705 unsigned GetVideoUpdateRequestsSent() const { return m_VideoUpdateRequestsSent; } 1706 #endif 1707 //@} 1708 1709 /// Get the string options associated with this connection. GetStringOptions()1710 const StringOptions & GetStringOptions() const { return m_stringOptions; } 1711 1712 /// Set the string options associated with this connection. 1713 void SetStringOptions( 1714 const StringOptions & options, 1715 bool overwrite 1716 ); 1717 1718 /// Call back for connection to act on changed string options 1719 virtual void OnApplyStringOptions(); 1720 1721 #if OPAL_HAS_MIXER 1722 1723 virtual void EnableRecording(); 1724 virtual void DisableRecording(); 1725 1726 #endif 1727 1728 #if 0 //OPAL_HAS_IM 1729 /** 1730 * Called to transmit an IM to the other connection in the call 1731 */ 1732 virtual bool TransmitInternalIM( 1733 const OpalMediaFormat & format, 1734 RTP_IMFrame & body 1735 ); 1736 1737 /** 1738 * Called when this connection receives an IM from the other connection in the call 1739 */ 1740 virtual void OnReceiveInternalIM( 1741 const OpalMediaFormat & format, 1742 RTP_IMFrame & body 1743 ); 1744 1745 /** 1746 * Called to transmit an IM to the other end of the connection 1747 */ 1748 virtual bool TransmitExternalIM( 1749 const OpalMediaFormat & format, 1750 RTP_IMFrame & body 1751 ); 1752 1753 /** 1754 * Called when this connection receives an IM from the other end of the connection 1755 */ 1756 virtual bool OnReceiveExternalIM( 1757 const OpalMediaFormat & format, 1758 RTP_IMFrame & body 1759 ); 1760 1761 /** Used for creating IM messages. 1762 * 0 = used for sending internal 1763 * 1 = used for sending external 1764 */ 1765 RFC4103Context & GetRFC4103Context(PINDEX i) { return m_rfc4103Context[i]; }; 1766 1767 protected: 1768 RFC4103Context m_rfc4103Context[2]; 1769 1770 #endif 1771 1772 protected: 1773 void OnConnectedInternal(); 1774 1775 PDECLARE_NOTIFIER(PThread, OpalConnection, OnReleaseThreadMain); 1776 1777 #if OPAL_HAS_MIXER 1778 PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordAudio); 1779 #if OPAL_VIDEO 1780 PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordVideo); 1781 #endif 1782 void OnStartRecording(OpalMediaPatch * patch); 1783 void OnStopRecording(OpalMediaPatch * patch); 1784 #endif 1785 1786 // Member variables 1787 OpalCall & ownerCall; 1788 OpalEndPoint & endpoint; 1789 1790 private: 1791 PMutex m_phaseMutex; 1792 Phases m_phase; 1793 1794 protected: 1795 PString callToken; 1796 PBoolean originating; 1797 OpalProductInfo productInfo; 1798 PString localPartyName; 1799 PString displayName; 1800 PString remotePartyName; 1801 PString remotePartyURL; 1802 OpalProductInfo remoteProductInfo; 1803 PString remotePartyNumber; 1804 PString remotePartyAddress; 1805 PString m_redirectingParty; 1806 CallEndReason callEndReason; 1807 PString m_calledPartyNumber; 1808 PString m_calledPartyName; 1809 1810 SendUserInputModes sendUserInputMode; 1811 PString userInputString; 1812 PSyncPoint userInputAvailable; 1813 1814 OpalSilenceDetector * silenceDetector; 1815 #if OPAL_AEC 1816 OpalEchoCanceler * echoCanceler; 1817 #endif 1818 OpalMediaFormat m_filterMediaFormat; 1819 1820 OpalMediaFormatList m_localMediaFormats; 1821 MediaAddressesDict mediaTransportAddresses; 1822 PSafeList<OpalMediaStream> mediaStreams; 1823 1824 unsigned minAudioJitterDelay; 1825 unsigned maxAudioJitterDelay; 1826 unsigned bandwidthAvailable; 1827 1828 // The In-Band DTMF detector. This is used inside an audio filter which is 1829 // added to the audio channel. 1830 #if OPAL_PTLIB_DTMF 1831 PDTMFDecoder m_dtmfDecoder; 1832 bool m_detectInBandDTMF; 1833 unsigned m_dtmfScaleMultiplier; 1834 unsigned m_dtmfScaleDivisor; 1835 PNotifier m_dtmfDetectNotifier; 1836 PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnDetectInBandDTMF); 1837 1838 bool m_sendInBandDTMF; 1839 OpalMediaFormat m_dtmfSendFormat; 1840 PBYTEArray m_inBandDTMF; 1841 PINDEX m_emittedInBandDTMF; 1842 PMutex m_inBandMutex; 1843 PNotifier m_dtmfSendNotifier; 1844 PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnSendInBandDTMF); 1845 #endif 1846 1847 #if PTRACING 1848 friend ostream & operator<<(ostream & o, Phases p); 1849 #endif 1850 1851 StringOptions m_stringOptions; 1852 1853 #if OPAL_HAS_MIXER 1854 PString m_recordingFilename; 1855 PNotifier m_recordAudioNotifier; 1856 #if OPAL_VIDEO 1857 PNotifier m_recordVideoNotifier; 1858 #endif 1859 #endif 1860 1861 #if OPAL_STATISTICS 1862 unsigned m_VideoUpdateRequestsSent; 1863 #endif 1864 1865 struct AutoStartInfo { 1866 unsigned preferredSessionId; // preferred session ID (only used for originating) 1867 OpalMediaType::AutoStartMode autoStart;// Mode for this session when the call is started 1868 }; 1869 1870 class AutoStartMap : public std::map<OpalMediaType, AutoStartInfo> 1871 { 1872 public: 1873 AutoStartMap(); 1874 void Initialise(const OpalConnection::StringOptions & stringOptions); 1875 OpalMediaType::AutoStartMode GetAutoStart(const OpalMediaType & mediaType) const; 1876 void SetAutoStart(const OpalMediaType & mediaType, OpalMediaType::AutoStartMode autoStart); 1877 1878 protected: 1879 bool m_initialised; 1880 PMutex m_mutex; 1881 1882 }; 1883 AutoStartMap m_autoStartInfo; 1884 1885 #if OPAL_FAX 1886 enum { 1887 e_NotSwitchingFaxMediaStreams, 1888 e_SwitchingToFaxMediaStreams, 1889 e_SwitchingFromFaxMediaStreams 1890 } m_faxMediaStreamsSwitchState; 1891 #endif 1892 1893 #if P_LUA 1894 protected: 1895 PLua m_lua; 1896 bool m_luaScriptLoaded; 1897 1898 public: 1899 PLUA_BINDING_START(OpalConnection) 1900 PLUA_BINDING2(LuaSetOption, "SetOption") 1901 PLUA_BINDING_END() 1902 PLUA_DECLARE_FUNCTION(LuaSetOption); 1903 #endif 1904 1905 // A version of PTime where default constructor creates invalid times 1906 class ZeroTime : public PTime 1907 { 1908 public: ZeroTime()1909 ZeroTime() : PTime(0) { } 1910 }; 1911 ZeroTime m_phaseTime[NumPhases]; 1912 1913 private: 1914 P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(unsigned int), false); 1915 P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(), false); 1916 P_REMOVE_VIRTUAL(PBoolean, IsConnectionOnHold(), false); 1917 P_REMOVE_VIRTUAL_VOID(OnMediaPatchStart(unsigned, bool)); 1918 P_REMOVE_VIRTUAL_VOID(OnMediaPatchStop(unsigned, bool)); 1919 P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(OpalMediaFormatList &) const); 1920 P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(OpalMediaFormatList &, OpalConnection *) const); 1921 P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(bool,OpalMediaFormatList &,OpalConnection *) const); 1922 P_REMOVE_VIRTUAL_VOID(PreviewPeerMediaFormats(const OpalMediaFormatList &)); 1923 P_REMOVE_VIRTUAL(bool, HoldConnection(), false); 1924 P_REMOVE_VIRTUAL(bool, RetrieveConnection(), false); 1925 P_REMOVE_VIRTUAL(bool, IsConnectionOnHold(bool), false); 1926 P_REMOVE_VIRTUAL_VOID(ApplyStringOptions(OpalConnection::StringOptions &)); 1927 P_REMOVE_VIRTUAL(bool, OnTransferNotify(const PStringToString &), false); 1928 P_REMOVE_VIRTUAL_VOID(OnSwitchedFaxMediaStreams(bool)); 1929 }; 1930 1931 #endif // OPAL_OPAL_CONNECTION_H 1932 1933 1934 // End of File /////////////////////////////////////////////////////////////// 1935