/**This class represents a particular H323 connection between two endpoints.   There are at least two threads in use, this one to look after the   signalling channel, an another to look after the control channel. There   would then be additional threads created for each data channel created by   the control channel protocol thread. */class H323Connection : public PObject{  PCLASSINFO(H323Connection, PObject);  public:  /**@name Construction */  //@{    /**Create a new connection.     */    H323Connection(      H323EndPoint & endpoint,   /// H323 End Point object      unsigned callReference     /// Call reference     );    /**Destroy the connection     */    ~H323Connection();    /**Lock connection.       When the H323EndPoint::FindConnectionWithLock() function is used to gain       access to a connection object, this is called to prevent it from being       closed and deleted by the background threads.     */    void Lock() { inUseFlag.Wait(); }    /**Unlock connection.       If the H323EndPoint::FindConnectionWithLock() function is used to gain       access to a connection object, this MUST be called to allow it to       subsequently be closed and disposed of.     */    void Unlock() { inUseFlag.Signal(); }    /**Determine if the call has been established.       This can be used in combination with the GetCallEndReason() function       to determine the three main phases of a call, call setup, call       established and call cleared.      */    BOOL IsEstablished() const { return connectionState == EstablishedConnection; }    /**Call clearance reasons.       NOTE: if anything is added to this, you also need to add the field to       the tables in h323.cxx and h323pdu.cxx.      */    enum CallEndReason {      EndedByLocalUser,         /// Local endpoint application cleared call      EndedByNoAccept,          /// Local endpoint did not accept call OnIncomingCall()=FALSE      EndedByAnswerDenied,      /// Local endpoint declined to answer call      EndedByRemoteUser,        /// Remote endpoint application cleared call      EndedByRefusal,           /// Remote endpoint refused call      EndedByNoAnswer,          /// Remote endpoint did not answer in required time      EndedByCallerAbort,       /// Remote endpoint stopped calling      EndedByTransportFail,     /// Transport error cleared call      EndedByConnectFail,       /// Transport connection failed to establish call      EndedByGatekeeper,        /// Gatekeeper has cleared call      EndedByNoUser,            /// Call failed as could not find user (in GK)      EndedByNoBandwidth,       /// Call failed as could not get enough bandwidth      EndedByCapabilityExchange,/// Could not find common capabilities      EndedByCallForwarded,     /// Call was forwarded using FACILITY message      NumCallEndReasons    };    /**Get the call clearand reason for this connection shutting down.       Note that this function is only generally useful in the       H323EndPoint::OnConnectionCleared() function. This is due to the       connection not being cleared before that, and the object not even       exiting after that.       If the call is still active then this will return NumCallEndReasons.      */    CallEndReason GetCallEndReason() const { return callEndReason; }    /**Set the call clearance reason.       An application should have no cause to use this function. It is present       for the H323EndPoint::ClearCall() function to set the clearance reason.      */    void SetCallEndReason(      CallEndReason reason   /// Reason for clearance of connection.    );    /**Clear a current connection.       This hangs up the connection to a remote endpoint. It actually just       calls the endpoint version of the ClearCall() function to avoid       possible multithreading race conditions.      */    BOOL ClearCall(      CallEndReason reason = EndedByLocalUser /// Reason for call clearing    );    /**Clean up the call clearance of the connection.       This function will do any internal cleaning up and waiting on background       threads that may be using the connection object. After this returns it       is then safe to delete the object.       An application will not typically use this function as it is used by the       H323EndPoint during a clear call.      */    virtual void CleanUpOnCallEnd();  //@}  /**@name Signalling Channel */  //@{    /**Attach a transport to this connection as the signalling channel.      */    void AttachSignalChannel(      H323Transport * channel  /// Transport for the PDU's    );    /**Write a PDU to the signalling channel.      */    BOOL WriteSignalPDU(      H323SignalPDU & pdu       /// PDU to write.    );    /* Handle reading PDU's from the signalling channel.     */    void HandleSignallingChannel();    /* Handle PDU from the signalling channel.     */    virtual BOOL HandleSignalPDU(      H323SignalPDU & pdu       /// PDU to handle.    );    /* Handle Control PDU tunnelled in the signalling channel.     */    virtual void HandleTunnelPDU(      const H323SignalPDU & pdu,    /// PDU to handle.      H323SignalPDU * reply         /// Optional PDU to piggy back replies    );    /**Handle an incoming Q931 setup PDU.       The default behaviour is to do the handshaking operation calling a few       virtuals at certain moments in the sequence.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.     */    virtual BOOL OnReceivedSignalSetup(      const H323SignalPDU & pdu   /// Received setup PDU    );    /**Handle an incoming Q931 call proceeding PDU.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour checks for hH245Address field and if present       starts the separate H245 channel, if successful or not present it       returns TRUE.     */    virtual BOOL OnReceivedCallProceeding(      const H323SignalPDU & pdu   /// Received call proceeding PDU    );    /**Handle an incoming Q931 alerting PDU.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour obtains the display name and calls OnAlerting().     */    virtual BOOL OnReceivedAlerting(      const H323SignalPDU & pdu   /// Received connect PDU    );    /**Handle an incoming Q931 connect PDU.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour checks for hH245Address field and if present       starts the separate H245 channel, if successful it returns TRUE.       If not present and there is no H245Tunneling then it returns FALSE.     */    virtual BOOL OnReceivedSignalConnect(      const H323SignalPDU & pdu   /// Received connect PDU    );    /**Handle an incoming Q931 facility PDU.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour checks for hH245Address field and if present       starts the separate H245 channel, if successful or not present it       returns TRUE.     */    virtual BOOL OnReceivedFacility(      const H323SignalPDU & pdu   /// Received connect PDU    );    /**Handle an incoming Q931 Status Enquiry PDU.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour sends a Q931 Status PDU back.     */    virtual BOOL OnReceivedStatusEnquiry(      const H323SignalPDU & pdu   /// Received connect PDU    );    /**This function is called from the HandleSignallingChannel() function       for unhandled PDU types.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent. The default behaviour returns TRUE.     */    virtual BOOL OnUnknownSignalPDU(      const H323SignalPDU & pdu  /// Received PDU    );    /**Call back for incoming call.       This function is called from the OnReceivedSignalSetup() function       before it sends the Alerting PDU. It gives an opportunity for an       application to alter the reply before transmission to the other       endpoint.       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour calls the endpoint function of the same name.     */    virtual BOOL OnIncomingCall(      const H323SignalPDU & setupPDU,   /// Received setup PDU      H323SignalPDU & alertingPDU       /// Alerting PDU to send    );    /**Forward incoming call to specified address.       This would typically be called from within the OnIncomingCall()       function when an application wishes to redirct an unwanted incoming       call.       The return value is TRUE if the call is to be forwarded, FALSE       otherwise. Note that if the call is forwarded the current connection is       cleared with teh ended call code of EndedByCallForwarded.      */    virtual BOOL ForwardCall(      const PString & forwardParty   /// Party to forward call to.    );    enum AnswerCallResponse {      AnswerCallNow,      // Answer the call continuing with the connection.      AnswerCallDenied,   // Refuse the call sending a release complete.      AnswerCallPending,  // Send an Alerting PDU and wait for AnsweringCall()      AnswerCallDeferred, // As for AnswerCallPending but does not send Alerting PDU      NumAnswerCallResponses    };    /**Call back for answering an incoming call.       This function is used for an application to control the answering of       incoming calls. It is usually used to indicate the immediate action to       be taken in answering the call.       It is called from the OnReceivedSignalSetup() function before it sends       the Alerting or Connect PDUs. It also gives an opportunity for an       application to alter the Connect PDU reply before transmission to the       remote endpoint.       If AnswerCallNow is returned then the H.323 protocol proceeds with the       connection. If AnswerCallDenied is returned the connection is aborted       and a Release Complete PDU is sent. If AnswerCallPending is returned       then the Alerting PDU is sent and the protocol negotiations are paused       until the AnsweringCall() function is called. Finally, if       AnswerCallDeferred is returned then no Alerting PDU is sent, but the       system still waits as in the AnswerCallPending response.       Note this function should not block for any length of time. If the       decision to answer the call may take some time eg waiting for a user to       pick up the phone, then AnswerCallPending or AnswerCallDeferred should       be returned.       The default behaviour calls the endpoint function of the same name       which in turn will return AnswerCallNow.     */    virtual AnswerCallResponse OnAnswerCall(      const PString & callerName,       /// Name of caller      const H323SignalPDU & setupPDU,   /// Received setup PDU      H323SignalPDU & connectPDU        /// Connect PDU to send.     );    /**Indicate the result of answering an incoming call.       This should only be called if the OnAnswerCall() callback function has       returned a AnswerCallPending or AnswerCallDeferred response.       Note sending further AnswerCallPending responses via this function will       have the result of an Alerting PDU being sent to the remote endpoint.       In this way multiple Alerting PDUs may be sent.       Sending a AnswerCallDeferred response would have no effect.      */    void AnsweringCall(      AnswerCallResponse response /// Answer response to incoming call    );    /**Send first PDU in signalling channel.       This function does the signalling handshaking for establishing a       connection to a remote endpoint. The transport (TCP/IP) for the       signalling channel is assumed to be already created. This function       will then do the SetRemoteAddress() and Connect() calls o establish       the transport.       Returns the error code for the call failure reason or NumCallEndReasons       if the call was successful to that point in the protocol.     */    virtual CallEndReason SendSignalSetup(      const PString & alias,                /// Name of remote party      const H323TransportAddress & address  /// Address of destination    );    /**Adjust setup PDU being sent on initialisation of signal channel.       This function is called from the SendSignalSetup() function before it       sends the Setup PDU. It gives an opportunity for an application to       alter the request before transmission to the other endpoint.       The default behaviour simply returns TRUE. Note that this is usually       overridden by the transport dependent descendent class, eg the       H323ConnectionTCP descendent fills in the destCallSignalAddress field       with the TCP/IP data. Therefore if you override this in your       application make sure you call the ancestor function.     */    virtual BOOL OnSendSignalSetup(      H323SignalPDU & setupPDU   /// Setup PDU to send    );    /**Call back for remote party being alerted.       This function is called from the SendSignalSetup() function after it       receives the optional Alerting PDU from the remote endpoint. That is       when the remote "phone" is "ringing".       If FALSE is returned the connection is aborted and a Release Complete       PDU is sent.       The default behaviour calls the endpoint function of the same name.     */    virtual BOOL OnAlerting(      const H323SignalPDU & alertingPDU,  /// Received Alerting PDU      const PString & user                /// Username of remote endpoint    );    /**This function is called from the SendSignalSetup() function after it       receives the Connect PDU from the remote endpoint, but before it       attempts to open the control channel.