class H323Connection: public PObject

This class represents a particular H323 connection between two endpoints.

Inheritance:


Public

[more] Construction
[more] Signalling Channel
[more] Control Channel
[more] Logical Channel Management
[more] Bandwidth Management
[more] Indications
[more] RTP Session Management
[more] Request Mode Changes
[more] Member variable access


Documentation

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.
o Construction

o H323Connection( H323EndPoint & endpoint, unsigned callReference, BOOL disableFastStart = FALSE, BOOL disableTunneling = FALSE )
Create a new connection.
Parameters:
endpoint - H323 End Point object
callReference - Call reference
disableFastStart - Flag to prevent fast start operation
disableTunneling - Flag to prevent H.245 tunneling

o ~H323Connection()
Destroy the connection

oBOOL Lock()
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.

Returns FALSE if the lock was not obtainable due to the connection being shut down.

ovoid Unlock()
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.

ovirtual void OnEstablished()
Called when a connection is established. Defautl behaviour is to call H323Connection::OnConnectionEstablished

ovirtual void OnCleared()
Called when a connection is cleared, just after CleanUpOnCallEnd() Default behaviour is to call H323Connection::OnConnectionCleared

oBOOL IsEstablished() const
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.

ovirtual void InternalEstablishedConnectionCheck()
Inernal function to check if call established. This checks all the criteria for establishing a call an initiating the starting of media channels, if they have not already been started vi the fast start algorithm.

oenum CallEndReason
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.

o EndedByNoAccept
Local endpoint application cleared call

o EndedByAnswerDenied
Local endpoint did not accept call OnIncomingCall()=FALSE

o EndedByRemoteUser
Local endpoint declined to answer call

o EndedByRefusal
Remote endpoint application cleared call

o EndedByNoAnswer
Remote endpoint refused call

o EndedByCallerAbort
Remote endpoint did not answer in required time

o EndedByTransportFail
Remote endpoint stopped calling

o EndedByConnectFail
Transport error cleared call

o EndedByGatekeeper
Transport connection failed to establish call

o EndedByNoUser
Gatekeeper has cleared call

o EndedByNoBandwidth
Call failed as could not find user (in GK)

o EndedByCapabilityExchange
Call failed as could not get enough bandwidth

o EndedByCallForwarded
Could not find common capabilities

o EndedBySecurityDenial
Call was forwarded using FACILITY message

o EndedByLocalBusy
Call failed a security check and was ended

o EndedByLocalCongestion
Local endpoint busy

o EndedByRemoteBusy
Local endpoint congested

o EndedByRemoteCongestion
Remote endpoint busy

o EndedByUnreachable
Remote endpoint congested

o EndedByNoEndPoint
Could not reach the remote party

o EndedByHostOffline
The remote party is not running an endpoint

o NumCallEndReasons
The remote party host off line

oCallEndReason GetCallEndReason() const
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.

ovoid SetCallEndReason( CallEndReason reason, PSyncPoint * sync = NULL )
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.
Parameters:
reason - Reason for clearance of connection.
sync - syncpoint to use for synchronous destruction

ovirtual BOOL ClearCall( CallEndReason reason = EndedByLocalUser )
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.
Parameters:
reason - Reason for call clearing

ovirtual BOOL ClearCallSynchronous( PSyncPoint * sync, CallEndReason reason = EndedByLocalUser )
Clear a current connection, synchronously
Parameters:
reason - Reason for call clearing

ovirtual void CleanUpOnCallEnd()
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.

o Signalling Channel

ovoid AttachSignalChannel( H323Transport * channel, BOOL answeringCall )
Attach a transport to this connection as the signalling channel.
Parameters:
channel - Transport for the PDU's
answeringCall - Flag for if incoming/outgoing call.

oBOOL WriteSignalPDU( H323SignalPDU & pdu )
Write a PDU to the signalling channel.
Parameters:
pdu - PDU to write.

ovirtual BOOL OnReceivedSignalSetup( const H323SignalPDU & pdu )
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.

Parameters:
pdu - Received setup PDU

ovirtual BOOL OnReceivedSignalSetupAck( const H323SignalPDU & pdu )
Handle an incoming Q931 setup acknowledge PDU. If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

The default behaviour does nothing.

Parameters:
pdu - Received setup PDU

ovirtual BOOL OnReceivedSignalInformation( const H323SignalPDU & pdu )
Handle an incoming Q931 information PDU. If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

The default behaviour does nothing.

Parameters:
pdu - Received setup PDU

ovirtual BOOL OnReceivedCallProceeding( const H323SignalPDU & 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.

Parameters:
pdu - Received call proceeding PDU

ovirtual BOOL OnReceivedProgress( const H323SignalPDU & pdu )
Handle an incoming Q931 progress 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.

Parameters:
pdu - Received call proceeding PDU

ovirtual BOOL OnReceivedAlerting( const H323SignalPDU & 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().

Parameters:
pdu - Received connect PDU

ovirtual BOOL OnReceivedSignalConnect( const H323SignalPDU & 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.

Parameters:
pdu - Received connect PDU

ovirtual BOOL OnReceivedFacility( const H323SignalPDU & 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.

Parameters:
pdu - Received connect PDU

ovirtual BOOL OnReceivedSignalNotify( const H323SignalPDU & pdu )
Handle an incoming Q931 Notify PDU. If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

The default behaviour simply returns TRUE.

Parameters:
pdu - Received connect PDU

ovirtual BOOL OnReceivedSignalStatus( const H323SignalPDU & pdu )
Handle an incoming Q931 Status PDU. If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

The default behaviour simply returns TRUE.

Parameters:
pdu - Received connect PDU

ovirtual BOOL OnReceivedStatusEnquiry( const H323SignalPDU & 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.

Parameters:
pdu - Received connect PDU

ovirtual void OnReceivedReleaseComplete( const H323SignalPDU & pdu )
Handle an incoming Q931 Release Complete PDU. The default behaviour calls Clear() using reason code based on the Release Complete Cause field and the current connection state.
Parameters:
pdu - Received connect PDU

ovirtual BOOL OnUnknownSignalPDU( const H323SignalPDU & 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.

Parameters:
pdu - Received PDU

ovirtual BOOL OnIncomingCall( const H323SignalPDU & setupPDU, H323SignalPDU & alertingPDU )
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.

Parameters:
setupPDU - Received setup PDU
alertingPDU - Alerting PDU to send

ovirtual BOOL ForwardCall( const PString & forwardParty )
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.

Parameters:
forwardParty - Party to forward call to.

ovoid TransferCall( const PString & remoteParty )
Initiate the transfer of an existing call (connection) to a new remote party using H4502. This sends a Call Transfer Initiate Invoke message from the A-Party (transferring endpoint) to the B-Party (transferred endpoint).
Parameters:
remoteParty - Remote party to transfer the existing call to

oBOOL IsTransferringCall() const
Determine whether this connection is being transferred

oBOOL IsTransferredCall() const
Determine whether this connection is the result of a transferred call

ovoid HandleTransferCall( const PString & token, const PString & identity )
Handle the transfer of an existing connection to a new remote. This is an internal function and it is not expected the user will call it directly.

oint GetCallTransferInvokeId()
Get transfer invoke ID dureing trasfer. This is an internal function and it is not expected the user will call it directly.

ovoid HoldCall( BOOL localHold )
Place the call on hold, suspending all media channels (H4504) NOTE: Only Local Hold is implemented so far.
Parameters:
localHold - true for Local Hold, false for Remote Hold

ovoid RetrieveCall( bool localHold )
Retrieve the call from hold, activating all media channels (H4504) NOTE: Only Local Hold is implemented so far.
Parameters:
localHold - true for Local Hold, false for Remote Hold

oBOOL IsLocalHold() const
Determine if held

oBOOL IsRemoteHold() const
Determine if held

ovirtual AnswerCallResponse OnAnswerCall( const PString & callerName, const H323SignalPDU & setupPDU, H323SignalPDU & connectPDU )
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.

Parameters:
callerName - Name of caller
setupPDU - Received setup PDU
connectPDU - Connect PDU to send.

o AnswerCallDenied
Answer the call continuing with the connection.

o AnswerCallPending
Refuse the call sending a release complete.

o AnswerCallDeferred
Send an Alerting PDU and wait for AnsweringCall()

o AnswerCallAlertWithMedia
As for AnswerCallPending but does not send Alerting PDU

o AnswerCallDeferredWithMedia
As for AnswerCallPending but starts media channels

o NumAnswerCallResponses
As for AnswerCallDeferred but starts media channels

ovoid AnsweringCall( AnswerCallResponse response )
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.

Parameters:
response - Answer response to incoming call

ovirtual CallEndReason SendSignalSetup( const PString & alias, const H323TransportAddress & address )
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.

Parameters:
alias - Name of remote party
address - Address of destination

ovirtual BOOL OnSendSignalSetup( H323SignalPDU & setupPDU )
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.

Parameters:
setupPDU - Setup PDU to send

ovirtual BOOL OnSendCallProceeding( H323SignalPDU & callProceedingPDU )
Adjust call proceeding PDU being sent. This function is called from the OnReceivedSignalSetup() function before it sends the Call Proceeding PDU. It gives an opportunity for an application to alter the request before transmission to the other endpoint. If this function returns FALSE then the Call Proceeding PDU is not sent at all.

The default behaviour simply returns TRUE.

Parameters:
callProceedingPDU - Call Proceeding PDU to send

ovirtual BOOL OnSendReleaseComplete( H323SignalPDU & releaseCompletePDU )
Call back for Release Complete being sent. This allows an application to add things to the release complete before it is sent to the remote endpoint.

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.

Parameters:
releaseCompletePDU - Release Complete PDU to send

ovirtual BOOL OnAlerting( const H323SignalPDU & alertingPDU, const PString & user )
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.

Parameters:
alertingPDU - Received Alerting PDU
user - Username of remote endpoint

ovirtual BOOL OnInsufficientDigits()
This function is called when insufficient digits have been entered. This supports overlapped dialling so that a call can begin when it is not known how many more digits are to be entered in a phone number.

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.

ovirtual void SendMoreDigits( const PString & digits )
This function is called when sufficient digits have been entered. This supports overlapped dialling so that a call can begin when it is not known how many more digits are to be entered in a phone number.

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.

Parameters:
digits - Extra digits

ovirtual BOOL OnOutgoingCall( const H323SignalPDU & connectPDU )
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.

If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

The default behaviour simply returns TRUE.

Parameters:
connectPDU - Received Connect PDU

ovirtual BOOL SendFastStartAcknowledge( H225_ArrayOf_PASN_OctetString & array )
Send an the acknowldege of a fast start. This function is called when the fast start channels provided to this connection by the original SETUP PDU have been selected and opened and need to be sent back to the remote endpoint.

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.

Parameters:
array - Array of H245_OpenLogicalChannel

ovirtual BOOL HandleFastStartAcknowledge( const H225_ArrayOf_PASN_OctetString & array )
Handle the acknowldege of a fast start. This function is called from one of a number of functions after it receives a PDU from the remote endpoint that has a fastStart field. It is in response to a request for a fast strart from the local endpoint.

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.

Parameters:
array - Array of H245_OpenLogicalChannel

ovirtual BOOL StartControlChannel()
Start a separate H245 channel. This function is called from one of a number of functions when it needs to create the h245 channel for the remote endpoint to connect back to.

If FALSE is returned the connection is aborted and a Release Complete PDU is sent.

ovirtual BOOL StartControlChannel( const H225_TransportAddress & h245Address )
Start a separate H245 channel. This function is called from one of a number of functions after it receives a PDU from the remote endpoint that has a h245Address field.

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.

Parameters:
h245Address - H245 address

o Control Channel

oBOOL WriteControlPDU( const H323ControlPDU & pdu )
Write a PDU to the control channel. If there is no control channel open then this will tunnel the PDU into the signalling channel.

oBOOL StartControlNegotiations()
Start control channel negotiations

ovirtual void HandleControlChannel()
Handle reading data on the control channel

ovirtual BOOL HandleControlData( PPER_Stream & strm )
Handle incoming data on the control channel. This decodes the data stream into a PDU and calls HandleControlPDU().

If FALSE is returned the connection is aborted. The default behaviour returns TRUE.

ovirtual BOOL HandleControlPDU( const H323ControlPDU & pdu )
Handle incoming PDU's on the control channel. Dispatches them to the various virtuals off this class.

If FALSE is returned the connection is aborted. The default behaviour returns TRUE.

ovirtual BOOL OnUnknownControlPDU( const H323ControlPDU & pdu )
This function is called from the HandleControlPDU() 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.

The default behaviour send a FunctioNotUnderstood indication back to the sender, and returns TRUE to continue operation.

Parameters:
pdu - Received PDU

ovirtual BOOL OnH245Request( const H323ControlPDU & pdu )
Handle incoming request PDU's on the control channel. Dispatches them to the various virtuals off this class.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245Response( const H323ControlPDU & pdu )
Handle incoming response PDU's on the control channel. Dispatches them to the various virtuals off this class.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245Command( const H323ControlPDU & pdu )
Handle incoming command PDU's on the control channel. Dispatches them to the various virtuals off this class.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245Indication( const H323ControlPDU & pdu )
Handle incoming indication PDU's on the control channel. Dispatches them to the various virtuals off this class.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245_SendTerminalCapabilitySet( const H245_SendTerminalCapabilitySet & pdu )
Handle H245 command to send terminal capability set.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245_FlowControlCommand( const H245_FlowControlCommand & pdu )
Handle H245 command to control flow control. This function calls OnLogicalChannelFlowControl() with the channel and bit rate restriction.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245_MiscellaneousCommand( const H245_MiscellaneousCommand & pdu )
Handle H245 miscellaneous command. This function passes the miscellaneous command on to the channel defined by the pdu.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245_MiscellaneousIndication( const H245_MiscellaneousIndication & pdu )
Handle H245 miscellaneous indication. This function passes the miscellaneous indication on to the channel defined by the pdu.
Parameters:
pdu - Received PDU

ovirtual BOOL OnH245_JitterIndication( const H245_JitterIndication & pdu )
Handle H245 indication of received jitter. This function calls OnLogicalChannelJitter() with the channel and estimated jitter.
Parameters:
pdu - Received PDU

oenum ControlProtocolErrors
Error discriminator for the OnControlProtocolError() function

ovirtual BOOL OnControlProtocolError( ControlProtocolErrors errorSource, const void * errorData = NULL )
This function is called from the HandleControlPDU() function or any of its sub-functions for protocol errors, eg unhandled PDU types.

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.

ovirtual void OnSendCapabilitySet( H245_TerminalCapabilitySet & pdu )
This function is called from the HandleControlPDU() function when it is about to send the Capabilities Set to the remote endpoint. This gives the application an oppurtunity to alter the PDU to be sent.

The default behaviour will make ädjustments" for compatibiliry with some broken remote endpoints.

Parameters:
pdu - PDU to send

ovirtual BOOL OnReceivedCapabilitySet( const H323Capabilities & remoteCaps, const H245_MultiplexCapability * muxCap, H245_TerminalCapabilitySetReject & reject )
This function is called when the remote endpoint sends its capability set. This gives the application an opportunity to determine what codecs are available and if it supports any of the combinations of codecs.

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.

Parameters:
remoteCaps - Capability combinations remote supports
muxCap - Transport capability, if present
reject - Rejection PDU (if return FALSE)

ovirtual void SendCapabilitySet( BOOL empty )
Send a new capability set.
Parameters:
empty - Send an empty set.

ovirtual void OnSetLocalCapabilities()
Call back to set the local capabilities. This is called just before the capabilties are required when a call is begun. It is called when a SETUP PDU is received or when one is about to be sent, so that the capabilities may be adjusted for correct fast start operation.

The default behaviour does nothing.

oBOOL IsH245Master() const
Return if this H245 connection is a master or slave

ovoid StartRoundTripDelay()
Start the round trip delay calculation over the control channel

oPTimeInterval GetRoundTripDelay() const
Get the round trip delay over the control channel

o Logical Channel Management

ovirtual void OnSelectLogicalChannels()
Call back to select logical channels to start.

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.

ovirtual void SelectDefaultLogicalChannel( unsigned sessionID )
Select default logical channel for normal start.
Parameters:
sessionID - Session ID to find default logical channel.

ovirtual void SelectFastStartChannels( unsigned sessionID, BOOL transmitter, BOOL receiver )
Select default logical channel for fast start.
Parameters:
sessionID - Session ID to find default logical channel.
transmitter - Whether to open transmitters
receiver - Whether to open receivers

ovirtual BOOL OpenLogicalChannel( const H323Capability & capability, unsigned sessionID, H323Channel::Directions dir )
Open a new logical channel. This function will open a channel between the endpoints for the specified capability.

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.

Parameters:
capability - Capability to open channel with
sessionID - Session for the channel
dir - Direction of channel

ovirtual BOOL OnOpenLogicalChannel( const H245_OpenLogicalChannel & openPDU, H245_OpenLogicalChannelAck & ackPDU, unsigned & errorCode )
This function is called when the remote endpoint want's to open a new channel.

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.

Parameters:
openPDU - Received PDU for the channel open
ackPDU - PDU to send for acknowledgement
errorCode - Error to return if refused

ovirtual BOOL OnConflictingLogicalChannel( H323Channel & channel )
Callback for when a logical channel conflict has occurred. This is called when the remote endpoint, which is a master, rejects our transmitter channel due to a resource conflict. Typically an inability to do asymmetric codecs. The local (slave) endpoint must then try and open a new transmitter channel using the same codec as the receiver that is being opened.
Parameters:
channel - Channel that conflicted

ovirtual H323Channel* CreateLogicalChannel( const H245_OpenLogicalChannel & open, BOOL startingFast, unsigned & errorCode )
Create a new logical channel object. This is in response to a request from the remote endpoint to open a logical channel.
Parameters:
open - Parameters for opening channel
startingFast - Flag for fast/slow starting.
errorCode - Reason for create failure

ovirtual BOOL OnCreateLogicalChannel( const H323Capability & capability, H323Channel::Directions dir, unsigned & errorCode )
This function is called when the remote endpoint want's to create a new channel.

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.

Parameters:
capability - Capability for the channel open
dir - Direction of channel
errorCode - Error to return if refused

ovirtual BOOL OnStartLogicalChannel( H323Channel & channel )
Call back function when a logical channel thread begins.

The default behaviour does nothing and returns TRUE.

Parameters:
channel - Channel that has been started.

ovirtual BOOL OpenAudioChannel( BOOL isEncoding, unsigned bufferSize, H323AudioCodec & codec )
Open a channel for use by an audio codec. The H323AudioCodec class will use this function to open the channel to read/write PCM data.

The default behaviour calls the equivalent function on the endpoint.

Parameters:
isEncoding - Direction of data flow
bufferSize - Size of each sound buffer
codec - codec that is doing the opening

ovirtual BOOL OpenVideoChannel( BOOL isEncoding, H323VideoCodec & codec )
Open a channel for use by an video codec. The H323VideoCodec class will use this function to open the channel to read/write image data.

The default behaviour calls the equivalent function on the endpoint.

Parameters:
isEncoding - Direction of data flow
codec - codec doing the opening

ovirtual void CloseLogicalChannel( unsigned number, BOOL fromRemote )
Close a logical channel.
Parameters:
number - Channel number to close.
fromRemote - Indicates close request of remote channel

ovirtual void CloseLogicalChannelNumber( const H323ChannelNumber & number )
Close a logical channel by number.
Parameters:
number - Channel number to close.

ovirtual void OnClosedLogicalChannel( const H323Channel & channel )
This function is called when the remote endpoint has closed down a logical channel.

The default behaviour does nothing.

Parameters:
channel - Channel that was closed

ovirtual BOOL OnClosingLogicalChannel( H323Channel & channel )
This function is called when the remote endpoint request the close of a logical channel.

The application may get an opportunity to refuse to close the channel by returning FALSE from this function.

The default behaviour returns TRUE.

Parameters:
channel - Channel that is to be closed

ovirtual void OnLogicalChannelFlowControl( H323Channel * channel, long bitRateRestriction )
This function is called when the remote endpoint wishes to limit the bit rate being sent on a channel.

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.

Parameters:
channel - Channel that is to be limited
bitRateRestriction - Limit for channel

ovirtual void OnLogicalChannelJitter( H323Channel * channel, DWORD jitter, int skippedFrameCount, int additionalBuffer )
This function is called when the remote endpoint indicates the level of jitter estimated by the receiver.

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.

Parameters:
channel - Channel that is to be limited
jitter - Estimated received jitter in microseconds
skippedFrameCount - Frames skipped by decodec
additionalBuffer - Additional size of video decoder buffer

oH323Channel* GetLogicalChannel( unsigned number, BOOL fromRemote ) const
Get a logical channel. Locates the specified channel number and returns a pointer to it.
Parameters:
number - Channel number to get.
fromRemote - Indicates get a remote channel

oH323Channel* FindChannel( unsigned sessionId, BOOL fromRemote ) const
Find a logical channel. Locates a channel give a RTP session ID. Each session would usually have two logical channels associated with it, so the fromRemote flag bay be used to distinguish which channel to return.
Parameters:
sessionId - Session ID to search for.
fromRemote - Indicates the direction of RTP data.

o Bandwidth Management

ounsigned GetBandwidthUsed() const
Get the bandwidth currently used. This totals the open channels and returns the total bandwidth used in 100's of bits/sec

oBOOL UseBandwidth( unsigned bandwidth, BOOL removing )
Request use the available bandwidth in 100's of bits/sec. If there is insufficient bandwidth available, FALSE is returned. If sufficient bandwidth is available, then TRUE is returned and the amount of available bandwidth is reduced by the specified amount.
Parameters:
bandwidth - Bandwidth required
removing - Flag for adding/removing bandwidth usage

ounsigned GetBandwidthAvailable() const
Get the available bandwidth in 100's of bits/sec

oBOOL SetBandwidthAvailable( unsigned newBandwidth, BOOL force = FALSE )
Set the available bandwidth in 100's of bits/sec. Note if the force parameter is TRUE this function will close down active logical channels to meet the new bandwidth requirement.
Parameters:
newBandwidth - New bandwidth limit
force - Force bandwidth limit

o Indications

ovirtual void SendUserInputIndication( const H245_UserInputIndication & pdu )
Send a user input indication to the remote endpoint. The two forms are for basic user input of a simple string using the SendUserInput() function or a full DTMF emulation user input using the SendUserInputTone() function.

An application could do more sophisticated usage by filling in the H245_UserInputIndication structure directly ans using this function.

Parameters:
pdu - Full user indication PDU

ovirtual void SendUserInput( const PString & value )
Send a user input indication to the remote endpoint. This is for sending arbitrary strings as user indications. Simple DTMF tones can be sent this way with the tone value being a single character string.
Parameters:
value - String value of indication

ovirtual void SendUserInputTone( char tone, unsigned duration = 0, unsigned logicalChannel = 0, unsigned rtpTimestamp = 0 )
Send a user input indication to the remote endpoint. This sends DTMF emulation user input. If something more sophisticated than the simple tones that can be sent using the SendUserInput() 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.

Parameters:
tone - DTMF tone code
duration - Duration of tone in milliseconds
logicalChannel - Logical channel number for RTP sync.
rtpTimestamp - RTP timestamp in logical channel sync.

ovoid SendUserInputHookFlash( int duration = 500 )
Send a user input indication to the remote endpoint. This sends a Hook Flash emulation user input.
Parameters:
duration - Duration of tone in milliseconds

ovirtual void OnUserInputIndication( const H245_UserInputIndication & pdu )
Call back for remote enpoint has sent user input. The default behaviour calls OnUserInputString() if the PDU is of the alphanumeric type, or OnUserInputTone() if of a tone type.
Parameters:
pdu - Full user indication PDU

ovirtual void OnUserInputString( const PString & value )
Call back for remote enpoint has sent user input as a string.

The default behaviour calls the endpoint function of the same name.

Parameters:
value - String value of indication

ovirtual void OnUserInputTone( char tone, unsigned duration, unsigned logicalChannel, unsigned rtpTimestamp )
Call back for remote enpoint has sent user input.

The default behaviour calls the endpoint function of the same name.

Parameters:
tone - DTMF tone code
duration - Duration of tone in milliseconds
logicalChannel - Logical channel number for RTP sync.
rtpTimestamp - RTP timestamp in logical channel sync.

o RTP Session Management

oRTP_Session* GetSession( unsigned sessionID ) const
Get an RTP session for the specified ID. If there is no session of the specified ID, NULL is returned.

oH323_RTP_Session* GetSessionCallbacks( unsigned sessionID ) const
Get an H323 RTP session for the specified ID. If there is no session of the specified ID, NULL is returned.

oRTP_Session* UseSession( unsigned sessionID, const H245_TransportAddress & pdu )
Use an RTP session for the specified ID. If there is no session of the specified ID, a new one is created using the information prvided in the H245_TransportAddress PDU. If the system does not support the specified transport, NULL is returned.

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.

ovoid ReleaseSession( unsigned sessionID )
Release the session. If the session ID is not being used any more any clients via the UseSession() function, then the session is deleted.

ovirtual void OnRTPStatistics( const RTP_Session & session ) const
Callback from the RTP session for statistics monitoring. This is called every so many packets on the transmitter and receiver threads of the RTP session indicating that the statistics have been updated.

The default behaviour calls H323EndPoint::OnRTPStatistics().

Parameters:
session - Session with statistics

oPString GetSessionCodecNames( unsigned sessionID ) const
Get the names of the codecs in use for the RTP session. If there is no session of the specified ID, an empty string is returned.

o Request Mode Changes

ovoid RequestModeChange()
Make a request to mode change to remote

oBOOL OnRequestModeChange( const H245_RequestMode & pdu, H245_RequestModeAck & ack, H245_RequestModeReject & reject )
Received request for mode change from remote.
Parameters:
pdu - Received PDU
ack - Ack PDU to send
reject - Reject PDU to send

ovoid OnAcceptModeChange( const H245_RequestModeAck & pdu )
Received acceptance of last mode change request from remote.
Parameters:
pdu - Received PDU

ovoid OnRefusedModeChange( const H245_RequestModeReject * pdu )
Received reject of last mode change request from remote.
Parameters:
pdu - Received PDU, if NULL is a timeout

o Member variable access

oH323EndPoint& GetEndPoint() const
Get the owner endpoint for this connection

oBOOL HadAnsweredCall() const
Get the call direction for this connection

ounsigned GetDistinctiveRing() const
Get the distinctive ring code for incoming call. This returns an integer from 0 to 7 that may indicate to an application that different ring cadences are to be used.

ovoid SetDistinctiveRing(unsigned pattern)
Set the distinctive ring code for outgoing call. This sets the integer from 0 to 7 that will be used in the outgoing Setup PDU. Note this must be called either immediately after construction or during the OnSendSignalSetup() callback function so the member variable is set befor ethe PDU is sent.

oconst PString& GetCallToken() const
Get the internal OpenH323 call token for this connection

ounsigned GetCallReference() const
Get the call reference for this connection

oconst OpalGloballyUniqueID& GetCallIdentifier() const
Get the call identifier for this connection

oconst OpalGloballyUniqueID& GetConferenceIdentifier() const
Get the conference identifier for this connection

oconst PString& GetLocalPartyName() const
Get the local name/alias

ovoid SetLocalPartyName(const PString & name)
Set the local name/alias from information in the PDU

oconst PString& GetRemotePartyName() const
Get the remote party name. This returns a string indicating the remote parties names and aliases. This can be a complicated string containing all the aliases and the remote host name. For example: "Fred Nurk (fred, 5551234) [fred.nurk.com]"

oconst PString& GetRemotePartyNumber() const
Get the remote party number, if there was one one. If the remote party has indicated an e164 number as one of its aliases or as a field in the Q.931 PDU, then this function will return it.

oconst PString& GetRemotePartyAddress() const
Get the remote party address. This will return the "best guess" at an address to use in a H323EndPoint::MakeCall() function to call the remote party back again. Note that due to the presence of gatekeepers/proxies etc this may not always be accurate.

ovoid SetRemotePartyInfo( const H323SignalPDU & pdu )
Set the name/alias of remote end from information in the PDU.
Parameters:
pdu - PDU from which to extract party info.

oconst PString& GetRemoteApplication() const
Get the remote application name and version. This information is obtained from the sourceInfo field of the H.225 Setup PDU or the destinationInfo of the call proceeding or alerting PDU's. The general format of the string will be information extracted from the VendorIdentifier field of the EndpointType. In partcular:

productId\tversionId\tt35CountryCode:t35Extension:manufacturerCode

ovoid SetRemoteApplication( const H225_EndpointType & pdu )
Set the name/alias of remote end from information in the PDU.
Parameters:
pdu - PDU from which to extract application info.

oconst H323Capabilities& GetLocalCapabilities() const
Get the remotes capability table for this connection

oconst H323Capabilities& GetRemoteCapabilities() const
Get the remotes capability table for this connection

ounsigned GetRemoteMaxAudioDelayJitter() const
Get the maximum audio jitter delay

oconst H323Transport* GetSignallingChannel() const
Get the signalling channel being used

oconst H323Transport& GetControlChannel() const
Get the control channel being used (may return signalling channel)

oPTime GetConnectionStartTime() const
Get the time at which the connection was established

oWORD GetMaxAudioDelayJitter() const
Get the default maximum audio delay jitter parameter

ovoid SetMaxAudioDelayJitter(unsigned jitter)
Set the default maximum audio delay jitter parameter

ounsigned GetUUIEsRequested() const
Get the UUIE PDU monitor bit mask

ovoid SetUUIEsRequested(unsigned mask)
Set the UUIE PDU monitor bit mask

oconst PString GetGkAccessTokenOID() const
Get the iNow Gatekeeper Access Token OID

ovoid SetGkAccessTokenOID(const PString & oid)
Set the iNow Gatekeeper Access Token OID

oconst PBYTEArray& GetGkAccessTokenData() const
Get the iNow Gatekeeper Access Token data


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.