This class represents a particular H323 connection between two endpoints.
![]() | Construction |
![]() | Signalling Channel |
![]() | Control Channel |
![]() | Logical Channel Management |
![]() | Bandwidth Management |
![]() | Indications |
![]() | RTP Session Management |
![]() | Request Mode Changes |
![]() | Member variable access |
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.
Returns FALSE if the lock was not obtainable due to the connection being
shut down.
If the call is still active then this will return NumCallEndReasons.
An application will not typically use this function as it is used by the
H323EndPoint during a clear call.
~H323Connection()
BOOL Lock()
void Unlock()
virtual void OnEstablished()
virtual void OnCleared()
BOOL IsEstablished() const
virtual void InternalEstablishedConnectionCheck()
enum CallEndReason
EndedByNoAccept
EndedByAnswerDenied
EndedByRemoteUser
EndedByRefusal
EndedByNoAnswer
EndedByCallerAbort
EndedByTransportFail
EndedByConnectFail
EndedByGatekeeper
EndedByNoUser
EndedByNoBandwidth
EndedByCapabilityExchange
EndedByCallForwarded
EndedBySecurityDenial
EndedByLocalBusy
EndedByLocalCongestion
EndedByRemoteBusy
EndedByRemoteCongestion
EndedByUnreachable
EndedByNoEndPoint
EndedByHostOffline
CallEndReason GetCallEndReason() const
void SetCallEndReason( CallEndReason reason, PSyncPoint * sync = NULL )
sync - syncpoint to use for synchronous destructionvirtual BOOL ClearCall( CallEndReason reason = EndedByLocalUser )
virtual BOOL ClearCallSynchronous( PSyncPoint * sync, CallEndReason reason = EndedByLocalUser )
virtual void CleanUpOnCallEnd()
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent.
The default behaviour does nothing.
The default behaviour does nothing.
The default behaviour checks for hH245Address field and if present
starts the separate H245 channel, if successful or not present it
returns TRUE.
The default behaviour checks for hH245Address field and if present
starts the separate H245 channel, if successful or not present it
returns TRUE.
The default behaviour obtains the display name and calls OnAlerting().
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.
The default behaviour checks for hH245Address field and if present
starts the separate H245 channel, if successful or not present it
returns TRUE.
The default behaviour simply returns TRUE.
The default behaviour simply returns TRUE.
The default behaviour sends a Q931 Status PDU back.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour returns TRUE.
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.
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.
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.
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.
Returns the error code for the call failure reason or NumCallEndReasons
if the call was successful to that point in the protocol.
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.
The default behaviour simply returns TRUE.
Returning FALSE will prevent the release complete from being sent. Note
that this would be very unusual as this is called when the connection
is being cleaned up. There will be no second chance to send the PDU and
it must be sent. The default behaviour simply returns TRUE.
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.
It is expected that the application will override this function. It
should be noted that the application should not block in the function
but only indicate to whatever other thread is gathering digits that
more are required and that thread should call SendMoreDigits(). If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour simply returns FALSE.
The digits parameter is appended to the existing remoteNumber member
variable and the call is retried. If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour simply returns TRUE.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour simply returns TRUE.
If FALSE is returned then no fast start has been acknowledged, possibly
due to no common codec in fast start request. The default behaviour uses OnSelectLogicalChannels() to find a pair of
channels and adds then to the provided PDU.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour parses the provided array and starts the channels
acknowledged in it.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour checks to see if it is a known transport and
creates a corresponding H323Transport decendent for the control
channel.
BOOL WriteSignalPDU( H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalSetup( const H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalSetupAck( const H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalInformation( const H323SignalPDU & pdu )
virtual BOOL OnReceivedCallProceeding( const H323SignalPDU & pdu )
virtual BOOL OnReceivedProgress( const H323SignalPDU & pdu )
virtual BOOL OnReceivedAlerting( const H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalConnect( const H323SignalPDU & pdu )
virtual BOOL OnReceivedFacility( const H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalNotify( const H323SignalPDU & pdu )
virtual BOOL OnReceivedSignalStatus( const H323SignalPDU & pdu )
virtual BOOL OnReceivedStatusEnquiry( const H323SignalPDU & pdu )
virtual void OnReceivedReleaseComplete( const H323SignalPDU & pdu )
virtual BOOL OnUnknownSignalPDU( const H323SignalPDU & pdu )
virtual BOOL OnIncomingCall( const H323SignalPDU & setupPDU, H323SignalPDU & alertingPDU )
alertingPDU - Alerting PDU to sendvirtual BOOL ForwardCall( const PString & forwardParty )
void TransferCall( const PString & remoteParty )
BOOL IsTransferringCall() const
BOOL IsTransferredCall() const
void HandleTransferCall( const PString & token, const PString & identity )
int GetCallTransferInvokeId()
void HoldCall( BOOL localHold )
void RetrieveCall( bool localHold )
BOOL IsLocalHold() const
BOOL IsRemoteHold() const
virtual AnswerCallResponse OnAnswerCall( const PString & callerName, const H323SignalPDU & setupPDU, H323SignalPDU & connectPDU )
setupPDU - Received setup PDU
connectPDU - Connect PDU to send.
AnswerCallDenied
AnswerCallPending
AnswerCallDeferred
AnswerCallAlertWithMedia
AnswerCallDeferredWithMedia
NumAnswerCallResponses
void AnsweringCall( AnswerCallResponse response )
virtual CallEndReason SendSignalSetup( const PString & alias, const H323TransportAddress & address )
address - Address of destinationvirtual BOOL OnSendSignalSetup( H323SignalPDU & setupPDU )
virtual BOOL OnSendCallProceeding( H323SignalPDU & callProceedingPDU )
virtual BOOL OnSendReleaseComplete( H323SignalPDU & releaseCompletePDU )
virtual BOOL OnAlerting( const H323SignalPDU & alertingPDU, const PString & user )
user - Username of remote endpointvirtual BOOL OnInsufficientDigits()
virtual void SendMoreDigits( const PString & digits )
virtual BOOL OnOutgoingCall( const H323SignalPDU & connectPDU )
virtual BOOL SendFastStartAcknowledge( H225_ArrayOf_PASN_OctetString & array )
virtual BOOL HandleFastStartAcknowledge( const H225_ArrayOf_PASN_OctetString & array )
virtual BOOL StartControlChannel()
virtual BOOL StartControlChannel( const H225_TransportAddress & h245Address )
If FALSE is returned the connection is aborted. The default behaviour
returns TRUE.
If FALSE is returned the connection is aborted. The default behaviour
returns TRUE.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent. The default behaviour returns TRUE. The default behaviour send a FunctioNotUnderstood indication back to
the sender, and returns TRUE to continue operation.
The errorData field may be a string or PDU or some other data depending
on the value of the errorSource parameter. These are:
e_UnhandledPDU &H323ControlPDU
e_MasterSlaveDetermination const char * If FALSE is returned the connection is aborted. The default behaviour
returns TRUE.
The default behaviour will make ädjustments" for compatibiliry with
some broken remote endpoints.
Note any codec types that are the remote system supports that are not in
the codecs list member variable for the endpoint are ignored and not
included in the remoteCodecs list. The default behaviour assigns the table and set to member variables and
returns TRUE if the remoteCodecs list is not empty.
The default behaviour does nothing.
BOOL StartControlNegotiations()
virtual void HandleControlChannel()
virtual BOOL HandleControlData( PPER_Stream & strm )
virtual BOOL HandleControlPDU( const H323ControlPDU & pdu )
virtual BOOL OnUnknownControlPDU( const H323ControlPDU & pdu )
virtual BOOL OnH245Request( const H323ControlPDU & pdu )
virtual BOOL OnH245Response( const H323ControlPDU & pdu )
virtual BOOL OnH245Command( const H323ControlPDU & pdu )
virtual BOOL OnH245Indication( const H323ControlPDU & pdu )
virtual BOOL OnH245_SendTerminalCapabilitySet( const H245_SendTerminalCapabilitySet & pdu )
virtual BOOL OnH245_FlowControlCommand( const H245_FlowControlCommand & pdu )
virtual BOOL OnH245_MiscellaneousCommand( const H245_MiscellaneousCommand & pdu )
virtual BOOL OnH245_MiscellaneousIndication( const H245_MiscellaneousIndication & pdu )
virtual BOOL OnH245_JitterIndication( const H245_JitterIndication & pdu )
enum ControlProtocolErrors
virtual BOOL OnControlProtocolError( ControlProtocolErrors errorSource, const void * errorData = NULL )
virtual void OnSendCapabilitySet( H245_TerminalCapabilitySet & pdu )
virtual BOOL OnReceivedCapabilitySet( const H323Capabilities & remoteCaps, const H245_MultiplexCapability * muxCap, H245_TerminalCapabilitySetReject & reject )
muxCap - Transport capability, if present
reject - Rejection PDU (if return FALSE)virtual void SendCapabilitySet( BOOL empty )
virtual void OnSetLocalCapabilities()
BOOL IsH245Master() const
void StartRoundTripDelay()
PTimeInterval GetRoundTripDelay() const
This function must be defined by the descendent class. It is used to select the logical channels to be opened between the two endpoints. There are three ways in which this may be called: when a "fast start" has been initiated by the local endpoint (via SendSignalSetup() function), when a "fast start" has been requested from the remote endpoint (via the OnReceivedSignalSetup() function) or when the H245 capability set (and master/slave) negotiations have completed (via the OnControlChannelOpen() function.
The function would typically examine several member variable to decide which mode it is being called in and what to do. If fastStartState is FastStartDisabled then non-fast start semantics should be used. The H245 capabilities in the remoteCapabilities members should be examined, and appropriate transmit channels started using OpenLogicalChannel().
If fastStartState is FastStartInitiate, then the local endpoint has initiated a call and is asking the application if fast start semantics are to be used. If so it is expected that the function call OpenLogicalChannel() for all the channels that it wishes to be able to be use. A subset (possibly none!) of these would actually be started when the remote endpoint replies.
If fastStartState is FastStartResponse, then this indicates the remote endpoint is attempting a fast start. The fastStartChannels member contains a list of possible channels from the remote that the local endpoint is to select which to accept. For each accepted channel it simply necessary to call the Start() function on that channel eg fastStartChannels[0].Start();
The default behaviour selects the first codec of each session number that is available. This is according to the order of the capabilities in the remoteCapabilities, the local capability table or of the fastStartChannels list respectively for each of the above scenarios.
If this function is called while there is not yet a conenction
established, eg from the OnFastStartLogicalChannels() function, then
a "trial" receiver/transmitter channel is created. This channel is not
started until the remote enpoint has confirmed that they are to start.
Any channels not confirmed are deleted. If this function is called later in the call sequence, eg from
OnSelectLogicalChannels(), then it may only establish a transmit
channel, ie fromRemote must be FALSE.
If the return value is FALSE then the open is rejected using the
errorCode as the cause, this would be a value from the enum
H245_OpenLogicalChannelReject_cause::Choices. The default behaviour simply returns TRUE.
If the return value is FALSE then the open is rejected using the
errorCode as the cause, this would be a value from the enum
H245_OpenLogicalChannelReject_cause::Choices. The default behaviour checks the capability set for if this capability
is allowed to be opened with other channels that may already be open.
The default behaviour does nothing and returns TRUE.
The default behaviour calls the equivalent function on the endpoint.
The default behaviour calls the equivalent function on the endpoint.
The default behaviour does nothing.
The application may get an opportunity to refuse to close the channel by
returning FALSE from this function. The default behaviour returns TRUE.
If channel is NULL, then the bit rate limit applies to all channels. The default behaviour does nothing if channel is NULL, otherwise calls
H323Channel::OnFlowControl() on the specific channel.
If channel is NULL, then the jitter applies to all channels. The default behaviour does nothing if channel is NULL, otherwise calls
H323Channel::OnJitter() on the specific channel.
virtual void SelectDefaultLogicalChannel( unsigned sessionID )
virtual void SelectFastStartChannels( unsigned sessionID, BOOL transmitter, BOOL receiver )
transmitter - Whether to open transmitters
receiver - Whether to open receiversvirtual BOOL OpenLogicalChannel( const H323Capability & capability, unsigned sessionID, H323Channel::Directions dir )
sessionID - Session for the channel
dir - Direction of channelvirtual BOOL OnOpenLogicalChannel( const H245_OpenLogicalChannel & openPDU, H245_OpenLogicalChannelAck & ackPDU, unsigned & errorCode )
ackPDU - PDU to send for acknowledgement
errorCode - Error to return if refusedvirtual BOOL OnConflictingLogicalChannel( H323Channel & channel )
virtual H323Channel* CreateLogicalChannel( const H245_OpenLogicalChannel & open, BOOL startingFast, unsigned & errorCode )
startingFast - Flag for fast/slow starting.
errorCode - Reason for create failurevirtual BOOL OnCreateLogicalChannel( const H323Capability & capability, H323Channel::Directions dir, unsigned & errorCode )
dir - Direction of channel
errorCode - Error to return if refusedvirtual BOOL OnStartLogicalChannel( H323Channel & channel )
virtual BOOL OpenAudioChannel( BOOL isEncoding, unsigned bufferSize, H323AudioCodec & codec )
bufferSize - Size of each sound buffer
codec - codec that is doing the openingvirtual BOOL OpenVideoChannel( BOOL isEncoding, H323VideoCodec & codec )
codec - codec doing the openingvirtual void CloseLogicalChannel( unsigned number, BOOL fromRemote )
fromRemote - Indicates close request of remote channelvirtual void CloseLogicalChannelNumber( const H323ChannelNumber & number )
virtual void OnClosedLogicalChannel( const H323Channel & channel )
virtual BOOL OnClosingLogicalChannel( H323Channel & channel )
virtual void OnLogicalChannelFlowControl( H323Channel * channel, long bitRateRestriction )
bitRateRestriction - Limit for channelvirtual void OnLogicalChannelJitter( H323Channel * channel, DWORD jitter, int skippedFrameCount, int additionalBuffer )
jitter - Estimated received jitter in microseconds
skippedFrameCount - Frames skipped by decodec
additionalBuffer - Additional size of video decoder bufferH323Channel* GetLogicalChannel( unsigned number, BOOL fromRemote ) const
fromRemote - Indicates get a remote channelH323Channel* FindChannel( unsigned sessionId, BOOL fromRemote ) const
fromRemote - Indicates the direction of RTP data.
BOOL UseBandwidth( unsigned bandwidth, BOOL removing )
removing - Flag for adding/removing bandwidth usageunsigned GetBandwidthAvailable() const
BOOL SetBandwidthAvailable( unsigned newBandwidth, BOOL force = FALSE )
force - Force bandwidth limit
An application could do more sophisticated usage by filling in the H245_UserInputIndication structure directly ans using this function.
A duration of zero indicates that no duration is to be indicated.
A non-zero logical channel indicates that the tone is to be syncronised
with the logical channel at the rtpTimestamp value specified. The tone parameter must be one of "0123456789*ABCD!" where '!'indicates a hook flash. If tone is a ' ' character then a
signalUpdate PDU is sent that updates the last tone indication
sent. See the H.245 specifcation for more details on this.
The default behaviour calls the endpoint function of the same name.
The default behaviour calls the endpoint function of the same name.
virtual void SendUserInput( const PString & value )
virtual void SendUserInputTone( char tone, unsigned duration = 0, unsigned logicalChannel = 0, unsigned rtpTimestamp = 0 )
duration - Duration of tone in milliseconds
logicalChannel - Logical channel number for RTP sync.
rtpTimestamp - RTP timestamp in logical channel sync.void SendUserInputHookFlash( int duration = 500 )
virtual void OnUserInputIndication( const H245_UserInputIndication & pdu )
virtual void OnUserInputString( const PString & value )
virtual void OnUserInputTone( char tone, unsigned duration, unsigned logicalChannel, unsigned rtpTimestamp )
duration - Duration of tone in milliseconds
logicalChannel - Logical channel number for RTP sync.
rtpTimestamp - RTP timestamp in logical channel sync.
If this function is used, then the ReleaseSession() function MUST be
called or the session is never deleted for the lifetime of the H323
connection.
The default behaviour calls H323EndPoint::OnRTPStatistics().
H323_RTP_Session* GetSessionCallbacks( unsigned sessionID ) const
RTP_Session* UseSession( unsigned sessionID, const H245_TransportAddress & pdu )
void ReleaseSession( unsigned sessionID )
virtual void OnRTPStatistics( const RTP_Session & session ) const
PString GetSessionCodecNames( unsigned sessionID ) const
BOOL OnRequestModeChange( const H245_RequestMode & pdu, H245_RequestModeAck & ack, H245_RequestModeReject & reject )
ack - Ack PDU to send
reject - Reject PDU to sendvoid OnAcceptModeChange( const H245_RequestModeAck & pdu )
void OnRefusedModeChange( const H245_RequestModeReject * pdu )
productId\tversionId\tt35CountryCode:t35Extension:manufacturerCode
BOOL HadAnsweredCall() const
unsigned GetDistinctiveRing() const
void SetDistinctiveRing(unsigned pattern)
const PString& GetCallToken() const
unsigned GetCallReference() const
const OpalGloballyUniqueID& GetCallIdentifier() const
const OpalGloballyUniqueID& GetConferenceIdentifier() const
const PString& GetLocalPartyName() const
void SetLocalPartyName(const PString & name)
const PString& GetRemotePartyName() const
const PString& GetRemotePartyNumber() const
const PString& GetRemotePartyAddress() const
void SetRemotePartyInfo( const H323SignalPDU & pdu )
const PString& GetRemoteApplication() const
void SetRemoteApplication( const H225_EndpointType & pdu )
const H323Capabilities& GetLocalCapabilities() const
const H323Capabilities& GetRemoteCapabilities() const
unsigned GetRemoteMaxAudioDelayJitter() const
const H323Transport* GetSignallingChannel() const
const H323Transport& GetControlChannel() const
PTime GetConnectionStartTime() const
WORD GetMaxAudioDelayJitter() const
void SetMaxAudioDelayJitter(unsigned jitter)
unsigned GetUUIEsRequested() const
void SetUUIEsRequested(unsigned mask)
const PString GetGkAccessTokenOID() const
void SetGkAccessTokenOID(const PString & oid)
const PBYTEArray& GetGkAccessTokenData() const
Alphabetic index HTML hierarchy of classes or Java