# connection.h

Go to the documentation of this file.

    00001 /*
    00002  * connection.h
    00003  *
    00004  * Telephony connection abstraction
    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): Post Increment
    00026  *     Portions of this code were written with the assistance of funding from
    00027  *     US Joint Forces Command Joint Concept Development & Experimentation (J9)
    00028  *     http://www.jfcom.mil/about/abt_j9.htm
    00029  *
    00030  * $Revision: 21004 $
    00031  * $Author: rjongbloed $
    00032  * $Date: 2008-09-16 07:08:56 +0000 (Tue, 16 Sep 2008) $
    00033  */
    00034
    00035 #ifndef __OPAL_CONNECTION_H
    00036 #define __OPAL_CONNECTION_H
    00037
    00038 #ifdef P_USE_PRAGMA
    00039 #pragma interface
    00040 #endif
    00041
    00042 #include <opal/buildopts.h>
    00043
    00044 #include <opal/mediafmt.h>
    00045 #include <opal/mediastrm.h>
    00046 #include <opal/guid.h>
    00047 #include <opal/transports.h>
    00048 #include <ptclib/dtmf.h>
    00049 #include <ptlib/safecoll.h>
    00050 #include <rtp/rtp.h>
    00051
    00052 class OpalEndPoint;
    00053 class OpalCall;
    00054 class OpalSilenceDetector;
    00055 class OpalEchoCanceler;
    00056 class OpalRFC2833Proto;
    00057 class OpalRFC2833Info;
    00058
    00270 class OpalProductInfo
    00271 {
    00272   public:
    00273     OpalProductInfo();
    00274
    00275     static OpalProductInfo & Default();
    00276
    00277     PCaselessString AsString() const;
    00278
    00279     PString vendor;
    00280     PString name;
    00281     PString version;
    00282     PString comments;
    00283     BYTE    t35CountryCode;
    00284     BYTE    t35Extension;
    00285     WORD    manufacturerCode;
    00286 };
    00287
    00288
    00306 class OpalConnection : public PSafeObject
    00307 {
    00308     PCLASSINFO(OpalConnection, PSafeObject);
    00309   public:
    00314     enum CallEndReason {
    00315       EndedByLocalUser,
    00316       EndedByNoAccept,
    00317       EndedByAnswerDenied,
    00318       EndedByRemoteUser,
    00319       EndedByRefusal,
    00320       EndedByNoAnswer,
    00321       EndedByCallerAbort,
    00322       EndedByTransportFail,
    00323       EndedByConnectFail,
    00324       EndedByGatekeeper,
    00325       EndedByNoUser,
    00326       EndedByNoBandwidth,
    00327       EndedByCapabilityExchange,
    00328       EndedByCallForwarded,
    00329       EndedBySecurityDenial,
    00330       EndedByLocalBusy,
    00331       EndedByLocalCongestion,
    00332       EndedByRemoteBusy,
    00333       EndedByRemoteCongestion,
    00334       EndedByUnreachable,
    00335       EndedByNoEndPoint,
    00336       EndedByHostOffline,
    00337       EndedByTemporaryFailure,
    00338       EndedByQ931Cause,
    00339       EndedByDurationLimit,
    00340       EndedByInvalidConferenceID,
    00341       EndedByNoDialTone,
    00342       EndedByNoRingBackTone,
    00343       EndedByOutOfService,
    00344       EndedByAcceptingCallWaiting,
    00345       NumCallEndReasons,
    00346
    00347       EndedWithQ931Code = 0x100
    00348     };
    00349
    00350 #if PTRACING
    00351     friend ostream & operator<<(ostream & o, CallEndReason reason);
    00352 #endif
    00353
    00354     enum AnswerCallResponse {
    00355       AnswerCallNow,
    00356       AnswerCallDenied,
    00357       AnswerCallPending,
    00358       AnswerCallDeferred,
    00359       AnswerCallAlertWithMedia,
    00360       AnswerCallDeferredWithMedia,
    00361       AnswerCallProgress,
    00362       AnswerCallNowAndReleaseCurrent,
    00363       NumAnswerCallResponses
    00364     };
    00365 #if PTRACING
    00366     friend ostream & operator<<(ostream & o, AnswerCallResponse s);
    00367 #endif
    00368
    00371     enum Options {
    00372       FastStartOptionDisable       = 0x0001,   // H.323 specific
    00373       FastStartOptionEnable        = 0x0002,
    00374       FastStartOptionMask          = 0x0003,
    00375
    00376       H245TunnelingOptionDisable   = 0x0004,   // H.323 specific
    00377       H245TunnelingOptionEnable    = 0x0008,
    00378       H245TunnelingOptionMask      = 0x000c,
    00379
    00380       H245inSetupOptionDisable     = 0x0010,   // H.323 specific
    00381       H245inSetupOptionEnable      = 0x0020,
    00382       H245inSetupOptionMask        = 0x0030,
    00383
    00384       DetectInBandDTMFOptionDisable = 0x0040,  // SIP and H.323
    00385       DetectInBandDTMFOptionEnable  = 0x0080,
    00386       DetectInBandDTMFOptionMask    = 0x00c0,
    00387
    00388       RTPAggregationDisable        = 0x0100,   // SIP and H.323
    00389       RTPAggregationEnable         = 0x0200,
    00390       RTPAggregationMask           = 0x0300,
    00391
    00392       SendDTMFAsDefault            = 0x0000,   // SIP and H.323
    00393       SendDTMFAsString             = 0x0400,
    00394       SendDTMFAsTone               = 0x0800,
    00395       SendDTMFAsRFC2833            = 0x0c00,
    00396       SendDTMFMask                 = 0x0c00
    00397     };
    00398
    00399     class StringOptions : public PStringToString
    00400     {
    00401     };
    00402
    00407     OpalConnection(
    00408       OpalCall & call,
    00409       OpalEndPoint & endpoint,
    00410       const PString & token,
    00411       unsigned options = 0,
    00412       OpalConnection::StringOptions * stringOptions = NULL
    00413     );
    00414
    00417     ~OpalConnection();
    00419
    00426     void PrintOn(
    00427       ostream & strm
    00428     ) const;
    00430
    00447     virtual bool IsNetworkConnection() const = 0;
    00448
    00452     enum Phases {
    00453         UninitialisedPhase,
    00454         SetUpPhase,
    00455         AlertingPhase,
    00456         ConnectedPhase,
    00457         EstablishedPhase,
    00458         ReleasingPhase,
    00459         ReleasedPhase,
    00460         NumPhases
    00461     };
    00462
    00467     inline Phases GetPhase() const { return phase; }
    00468
    00477     CallEndReason GetCallEndReason() const { return callEndReason; }
    00478
    00483     virtual void SetCallEndReason(
    00484       CallEndReason reason
    00485     );
    00486
    00494     void ClearCall(
    00495       CallEndReason reason = EndedByLocalUser
    00496     );
    00497
    00500     virtual void ClearCallSynchronous(
    00501       PSyncPoint * sync,
    00502       CallEndReason reason = EndedByLocalUser
    00503     );
    00504
    00508     unsigned GetQ931Cause() const { return q931Cause; }
    00509
    00513     void SetQ931Cause(unsigned v) { q931Cause = v; }
    00514
    00521     virtual bool TransferConnection(
    00522       const PString & remoteParty
    00523     );
    00524
    00527     virtual bool HoldConnection();
    00528
    00532     virtual bool RetrieveConnection();
    00533
    00536     virtual PBoolean IsConnectionOnHold();
    00537
    00542     virtual void OnHold(
    00543       bool fromRemote,
    00544       bool onHold
    00545     );
    00547
    00575     virtual PBoolean OnIncomingConnection(unsigned int options, OpalConnection::StringOptions * stringOptions);
    00576     virtual PBoolean OnIncomingConnection(unsigned int options);
    00577     virtual PBoolean OnIncomingConnection();
    00578
    00585     virtual PBoolean SetUpConnection() = 0;
    00586
    00590     virtual PBoolean OnSetUpConnection();
    00591
    00592
    00608     virtual void OnAlerting();
    00609
    00620     virtual PBoolean SetAlerting(
    00621       const PString & calleeName,
    00622       PBoolean withMedia
    00623     ) = 0;
    00624
    00641     virtual AnswerCallResponse OnAnswerCall(
    00642       const PString & callerName
    00643     );
    00644
    00655     virtual void AnsweringCall(
    00656       AnswerCallResponse response
    00657     );
    00658
    00673     virtual void OnConnected();
    00674
    00685     virtual PBoolean SetConnected();
    00686
    00698     virtual void OnEstablished();
    00699
    00708     virtual void Release(
    00709       CallEndReason reason = EndedByLocalUser
    00710     );
    00711
    00729     virtual void OnReleased();
    00731
    00742     virtual PString GetDestinationAddress();
    00743
    00753     virtual PBoolean ForwardCall(
    00754       const PString & forwardParty
    00755     );
    00756
    00759     PSafePtr<OpalConnection> GetOtherPartyConnection() const;
    00760
    00763     template <class cls> PSafePtr<cls> GetOtherPartyConnectionAs() const { return PSafePtrCast<OpalConnection, cls>(GetOtherPartyConnection()); }
    00765
    00774     virtual OpalMediaFormatList GetMediaFormats() const;
    00775
    00780     virtual OpalMediaFormatList GetLocalMediaFormats();
    00781
    00790     virtual void AdjustMediaFormats(
    00791       OpalMediaFormatList & mediaFormats
    00792     ) const;
    00793
    00796     virtual OpalMediaStreamPtr OpenMediaStream(
    00797       const OpalMediaFormat & mediaFormat,
    00798       unsigned sessionID,
    00799       bool isSource
    00800     );
    00801
    00806     virtual bool CloseMediaStream(
    00807       unsigned sessionId,
    00808       bool source
    00809     );
    00810
    00815     virtual bool CloseMediaStream(
    00816       OpalMediaStream & stream
    00817     );
    00818
    00826     bool RemoveMediaStream(
    00827       OpalMediaStream & strm     // media stream to remove
    00828     );
    00829
    00832     virtual void StartMediaStreams();
    00833
    00836     virtual void CloseMediaStreams();
    00837
    00840     virtual void PauseMediaStreams(PBoolean paused);
    00841
    00854     virtual OpalMediaStream * CreateMediaStream(
    00855       const OpalMediaFormat & mediaFormat,
    00856       unsigned sessionID,
    00857       PBoolean isSource
    00858     );
    00859
    00863     OpalMediaStreamPtr GetMediaStream(
    00864       const PString & streamID
    00865     ) const;
    00866
    00872     OpalMediaStreamPtr GetMediaStream(
    00873       unsigned sessionId,
    00874       bool source
    00875     ) const;
    00876
    00882     OpalMediaStreamPtr GetMediaStream(
    00883       const OpalMediaType & mediaType,
    00884       bool source
    00885     ) const;
    00886
    00898     virtual PBoolean OnOpenMediaStream(
    00899       OpalMediaStream & stream
    00900     );
    00901
    00906     virtual void OnClosedMediaStream(
    00907       const OpalMediaStream & stream
    00908     );
    00909
    00914     virtual void OnPatchMediaStream(
    00915       PBoolean isSource,
    00916       OpalMediaPatch & patch
    00917     );
    00918
    00923     virtual void AttachRFC2833HandlerToPatch(PBoolean isSource, OpalMediaPatch & patch);
    00924
    00930     virtual PBoolean IsMediaBypassPossible(
    00931       unsigned sessionID
    00932     ) const;
    00933
    00934 #if OPAL_VIDEO
    00935
    00940     virtual void AddVideoMediaFormats(
    00941       OpalMediaFormatList & mediaFormats
    00942     ) const;
    00943
    00946     virtual PBoolean CreateVideoInputDevice(
    00947       const OpalMediaFormat & mediaFormat,
    00948       PVideoInputDevice * & device,
    00949       PBoolean & autoDelete
    00950     );
    00951
    00955     virtual PBoolean CreateVideoOutputDevice(
    00956       const OpalMediaFormat & mediaFormat,
    00957       PBoolean preview,
    00958       PVideoOutputDevice * & device,
    00959       PBoolean & autoDelete
    00960     );
    00961 #endif
    00962
    00965     virtual PBoolean SetAudioVolume(
    00966       PBoolean source,
    00967       unsigned percentage
    00968     );
    00969
    00973     virtual unsigned GetAudioSignalLevel(
    00974       PBoolean source
    00975     );
    00977
    00982     unsigned GetBandwidthAvailable() const { return bandwidthAvailable; }
    00983
    00988     virtual PBoolean SetBandwidthAvailable(
    00989       unsigned newBandwidth,
    00990       PBoolean force = PFalse
    00991     );
    00992
    00997     virtual unsigned GetBandwidthUsed() const;
    00998
    01007     virtual PBoolean SetBandwidthUsed(
    01008       unsigned releasedBandwidth,
    01009       unsigned requiredBandwidth
    01010     );
    01012
    01015     enum SendUserInputModes {
    01016       SendUserInputAsQ931,
    01017       SendUserInputAsString,
    01018       SendUserInputAsTone,
    01019       SendUserInputAsInlineRFC2833,
    01020       SendUserInputAsSeparateRFC2833,  // Not implemented
    01021       SendUserInputAsProtocolDefault,
    01022       NumSendUserInputModes
    01023     };
    01024 #if PTRACING
    01025     friend ostream & operator<<(ostream & o, SendUserInputModes m);
    01026 #endif
    01027
    01030     virtual void SetSendUserInputMode(SendUserInputModes mode);
    01031
    01034     virtual SendUserInputModes GetSendUserInputMode() const { return sendUserInputMode; }
    01035
    01041     virtual SendUserInputModes GetRealSendUserInputMode() const { return GetSendUserInputMode(); }
    01042
    01049     virtual PBoolean SendUserInputString(
    01050       const PString & value
    01051     );
    01052
    01069     virtual PBoolean SendUserInputTone(
    01070       char tone,
    01071       unsigned duration = 0
    01072     );
    01073
    01080     virtual void OnUserInputString(
    01081       const PString & value
    01082     );
    01083
    01090     virtual void OnUserInputTone(
    01091       char tone,
    01092       unsigned duration
    01093     );
    01094
    01098     void SendUserInputHookFlash(
    01099       unsigned duration = 500
    01100     ) { SendUserInputTone('!', duration); }
    01101
    01104     virtual PString GetUserInput(
    01105       unsigned timeout = 30
    01106     );
    01107
    01112     virtual void SetUserInput(
    01113       const PString & input
    01114     );
    01115
    01118     virtual PString ReadUserInput(
    01119       const char * terminators = "#\r\n",
    01120       unsigned lastDigitTimeout = 4,
    01121       unsigned firstDigitTimeout = 30
    01122     );
    01123
    01130     virtual PBoolean PromptUserInput(
    01131       PBoolean play
    01132     );
    01134
    01139     virtual bool GarbageCollection();
    01141
    01146     OpalEndPoint & GetEndPoint() const { return endpoint; }
    01147
    01150     OpalCall & GetCall() const { return ownerCall; }
    01151
    01154     const PString & GetToken() const { return callToken; }
    01155
    01158     PBoolean IsOriginating() const { return originating; }
    01159
    01162     PTime GetSetupUpTime() const { return setupTime; }
    01163
    01166     PTime GetAlertingTime() const { return alertingTime; }
    01167
    01170     PTime GetConnectionStartTime() const { return connectedTime; }
    01171
    01174     PTime GetConnectionEndTime() const { return callEndTime; }
    01175
    01178     const OpalProductInfo & GetProductInfo() const { return productInfo; }
    01179
    01182     void SetProductInfo(
    01183       const OpalProductInfo & info
    01184     ) { productInfo = info; }
    01185
    01188     virtual PString GetPrefixName() const;
    01189
    01192     const PString & GetLocalPartyName() const { return localPartyName; }
    01193
    01196     virtual void SetLocalPartyName(const PString & name);
    01197
    01200     virtual PString GetLocalPartyURL() const;
    01201
    01204     const PString & GetDisplayName() const { return displayName; }
    01205
    01208     void SetDisplayName(const PString & name) { displayName = name; }
    01209
    01212     const PString & GetRemotePartyName() const { return remotePartyName; }
    01213
    01216     void SetRemotePartyName(const PString & name) { remotePartyName = name; }
    01217
    01226     const PString & GetRemotePartyNumber() const { return remotePartyNumber; }
    01227
    01233     const PString & GetRemotePartyAddress() const { return remotePartyAddress; }
    01234
    01237     void SetRemotePartyAddress(const PString & addr) { remotePartyAddress = addr; }
    01238
    01245     virtual PString GetRemotePartyURL() const;
    01246
    01247     // Deprecated - backward compatibility only
    01248     const PString GetRemotePartyCallbackURL() const { return GetRemotePartyURL(); }
    01249
    01253     PCaselessString GetRemoteApplication() const { return remoteProductInfo.AsString(); }
    01254
    01257     const OpalProductInfo & GetRemoteProductInfo() const { return remoteProductInfo; }
    01258
    01259
    01266     const PString & GetCalledPartyName() const { return m_calledPartyName; }
    01267
    01274     const PString & GetCalledPartyNumber() const { return m_calledPartyNumber; }
    01275
    01283     virtual PString GetCalledPartyURL();
    01284
    01285     /* Internal function to copy party names from "network" connection to
    01286        "non-network" connection such as OpalPCSSConnection. This allows
    01287        the non-network GetRemoteAddress() function and its ilk to return
    01288        the intuitive value, i.e. the value from the OTHER connection.
    01289      */
    01290     void CopyPartyNames(const OpalConnection & other);
    01291
    01295     unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }
    01296
    01300     unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }
    01301
    01304     void SetAudioJitterDelay(
    01305       unsigned minDelay,
    01306       unsigned maxDelay
    01307     );
    01308
    01311     OpalSilenceDetector * GetSilenceDetector() const { return silenceDetector; }
    01312
    01315     OpalEchoCanceler * GetEchoCanceler() const { return echoCanceler; }
    01316
    01319     virtual const OpalGloballyUniqueID & GetIdentifier() const
    01320     { return callIdentifier; }
    01321
    01330     virtual PINDEX GetMaxRtpPayloadSize() const;
    01331
    01332     virtual OpalTransport & GetTransport() const
    01333     { return *(OpalTransport *)NULL; }
    01334
    01335     PDICTIONARY(MediaAddressesDict, POrdinalKey, OpalTransportAddress);
    01336     MediaAddressesDict & GetMediaTransportAddresses()
    01337     { return mediaTransportAddresses; }
    01338
    01339 #if OPAL_STATISTICS
    01340
    01342     unsigned GetVideoUpdateRequestsSent() const { return m_VideoUpdateRequestsSent; }
    01343 #endif
    01344
    01345
    01346     StringOptions * GetStringOptions() const
    01347     { return stringOptions; }
    01348
    01349     void SetStringOptions(StringOptions * options);
    01350
    01362     virtual PBoolean OnOpenIncomingMediaChannels();
    01363
    01364     virtual void ApplyStringOptions();
    01365
    01366     virtual void PreviewPeerMediaFormats(const OpalMediaFormatList & fmts);
    01367
    01368     virtual void EnableRecording();
    01369     virtual void DisableRecording();
    01370
    01371     virtual void OnMediaPatchStart(
    01372       unsigned sessionId,
    01373           bool isSource
    01374     );
    01375     virtual void OnMediaPatchStop(
    01376       unsigned sessionId,
    01377           bool isSource
    01378     );
    01379
    01383     PDECLARE_NOTIFIER(OpalMediaCommand, OpalConnection, OnMediaCommand);
    01384
    01385   protected:
    01386     void OnConnectedInternal();
    01387
    01388 #if OPAL_PTLIB_DTMF
    01389     PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnUserInputInBandDTMF);
    01390 #endif
    01391     PDECLARE_NOTIFIER(PThread, OpalConnection, OnReleaseThreadMain);
    01392     PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordAudio);
    01393
    01394   // Member variables
    01395     OpalCall             & ownerCall;
    01396     OpalEndPoint         & endpoint;
    01397
    01398   private:
    01399     PMutex               phaseMutex;
    01400     Phases               phase;
    01401
    01402   protected:
    01403     PString              callToken;
    01404     OpalGloballyUniqueID callIdentifier;
    01405     PBoolean             originating;
    01406     PTime                setupTime;
    01407     PTime                alertingTime;
    01408     PTime                connectedTime;
    01409     PTime                callEndTime;
    01410     OpalProductInfo      productInfo;
    01411     PString              localPartyName;
    01412     PString              displayName;
    01413     PString              remotePartyName;
    01414     OpalProductInfo      remoteProductInfo;
    01415     PString              remotePartyNumber;
    01416     PString              remotePartyAddress;
    01417     CallEndReason        callEndReason;
    01418     bool                 synchronousOnRelease;
    01419     PString              m_calledPartyNumber;
    01420     PString              m_calledPartyName;
    01421
    01422     SendUserInputModes    sendUserInputMode;
    01423     PString               userInputString;
    01424     PSyncPoint            userInputAvailable;
    01425     PBoolean              detectInBandDTMF;
    01426     unsigned              dtmfScaleMultiplier;
    01427     unsigned              dtmfScaleDivisor;
    01428     unsigned              q931Cause;
    01429
    01430     OpalSilenceDetector * silenceDetector;
    01431     OpalEchoCanceler    * echoCanceler;
    01432
    01433     MediaAddressesDict         mediaTransportAddresses;
    01434     PSafeList<OpalMediaStream> mediaStreams;
    01435
    01436     unsigned            minAudioJitterDelay;
    01437     unsigned            maxAudioJitterDelay;
    01438     unsigned            bandwidthAvailable;
    01439
    01440     // The In-Band DTMF detector. This is used inside an audio filter which is
    01441     // added to the audio channel.
    01442 #if OPAL_PTLIB_DTMF
    01443     PDTMFDecoder        dtmfDecoder;
    01444 #endif
    01445
    01449     void SetPhase(Phases phaseToSet);
    01450
    01451 #if PTRACING
    01452     friend ostream & operator<<(ostream & o, Phases p);
    01453 #endif
    01454
    01455     StringOptions * stringOptions;
    01456     PString recordAudioFilename;
    01457
    01458 #if OPAL_STATISTICS
    01459     unsigned m_VideoUpdateRequestsSent;
    01460 #endif
    01461 };
    01462
    01463 #endif // __OPAL_CONNECTION_H
    01464
    01465
    01466 // End of File ///////////////////////////////////////////////////////////////