Architectural layout
Architectural layout
Which is your typical layered approach to a system. The application layer is presented with a unified model for making calls over whatever underlying protocol or hardware by the so the calls can be placed and media flow handled in, as much as possible, an identical manner.
OpalCall is defined as the connection between two or more Addresses each through an OpalConnection created by an OpalEndpoint The OpalCall usually has multiple OpalMediaStreams transferring information (eg voice) of a particular OpalMediaFormat from one OpalEndPoint to another. The data is copied from a Source Media Stream to a Sink Media Stream via a OpalMediaPatch thread.
An application can control the connection between endpoints according to its own logic. For example all incoming calls are routed to the POTS port.
pstn:555-1234 or pstn:555-1234 where line1 is the name of a specific instance of a PSTN endpoint. Another example would be h323:phone.quicknet.net or h323:derhart@gk.quicknet.net where the second form indicates a gateway to use for the specified alias.There are two broad types of endpoints, a Terminal Endpoint and a Network Endpoint. A terminal endpoint is one where a call usually ends, for example a POTS port with a phone handset attached. A network endpoint is one that connects through a network of some form, not necessarily a LAN or Internet. For example, H.323 protocol stack or a PSTN line.
Each endpoint has a set of attributes that can control its default behaviour. For example whether it is a terminal or network endpoint. An endpoint may support a single (eg PSTN/POTS), dual (eg ISDN BRI) or many (eg H.323/SIP) simultaneous connections. An endpoint may only accept incoming calls (SIP server), only be able to make calls (SIP client, or Net2phone) or both depending on the semantics of the underlying protocol. All of these attributes are abstracted for default behaviour that the application can override through the use of call back functions.
The classes H323EndPoint and OpalLIDEndPoint are examples of endpoints.
For example a call linking a remote H.323 endpoint to a simple telephone handset would have a H323Connection and an OpalLIDConnection. The H323Connection contains such things as the sockets to maintain the signalling and control channels from this host to the remote H.323 host. The OpalLIDConnection contains a pointer to a OpalLineInterfaceDevice and has such things as its current state eg ringing, playing engaged tone etc.
This objects lifetime is for the duration of the connection and is usually dictated by external influences, eg picking up the handset and then replacing it. The Endpoint creates and deletes the Connection as required, though the application can get involved in this processing if it needs to, eg to add extra information on a connection by connection basis.
The lifetime of the call is controlled by the application, but is typically for as long as there is at least one connection that attached to it.
Each protocol utilises a particular type of media stream. For example the H.323 protocol would create media streams that utilise an RTP session. The Telephone Line protocol creates media streams that use an OpalLineInterfaceDevice for its I/O.
The lifetime of the media stream is highly dependent on the protocol. They may come and go on demand as dictated by the underlying protocol. For example a H.323 video media stream is not created immediately on the call beginning, but later on user request. And when the user closes the video window the video media stream is then closed and deleted. However, the media streams for a Telephone Line would be created with its connection and remain for the duration of the connection as there is always a fixed one to two relationship between a Telephone Line and its media streams (source and sink).
When data is transferred from a source media stream to a sink media stream, there may be required software conversion of the media format. For example if an H.323 connection was providing a source media stream that used the G.711 media format, and the sink media stream was a LID connection using a line interface device that supported G.711 directly, then data may be simply copied from one to the other. If however, the sink is a sound card then a software codec, or Transcoder , is required to convert the G.711 media format to the PCM-16 media format. If there is no transcoder available then the media stream fails to open and is removed.
The scenarios here are based on an OpenPhone style application that has H.323 and LID (PhoneJACK etc) support.
The H.323 endpoint creates a background thread to listen for incoming calls. Typically this is TCP port 1720. As many threads and listeners may be created for different interfaces, ports or protocol (eg Ipv6).
The Telephone Line endpoint creates a background thread that monitors the Line Interface Device state, eg on or off hook etc. Note that the Telephone Line endpoint can have multiple LIDs and each LID can have multiple physical lines, so quite a few Telephone Lines can be monitored by this endpoint.
The PC sound system would nor create any background threads as its control actions (on/off hook equivalent) are all done though call back functions that interface to the applications user interface threads. For example when a button is pressed in a make call dialog then a function is called on the OpalPCSSEndpoint and its internal state is changed to off hook. The thread that controls this is the user interface thread.
| Call Model | POTS to H.323 | H.323 to POTS |
| Connection detected. An endpoint detects a new connection via some means and creates a connection object. | When the user picks up the handset the Telephone Line Endpoints background thread detects this and creates a Telephone Line Connection object. The Telephone Line Endpoint must remember this object as it continues to monitor the line for the user placing the receiver back on hook. | The background thread of the H.323 endpoint accepts an incoming TCP connection and after reading the first SETUP PDU it creates a H.323 connection object. The created H.323 connection creates a new thread to look after the H.225/Q.931signalling channel, and possibly a second thread to look after the H.245 control channel if tunnelling is not available. This thread will cause call back functions on the connection to be called. |
| Upon creation of the new connection object this is passed to the manager call back OnIncomingConnection. An application could override this function for any special treatment, for example getting a account number and PIN code via the use of the endpoints GetUserIndication function. The default behaviour would call the connections GetDestinationAddress function
| The Line connection GetUserIndication gets a DTMF tone from the LID. The Line connection GetDestinationAddress gathers a sequence of DTMF digits from the LID. | The H.323 connection GetUserIndication returns the last value received in the H.245 UserIndication PDU. The H.323 connection GetDestinationAddress looks at the various fields of the last received SETUP PDU such as destinationAlias to determine a destination address. |
| Now the manager's OnRouteConnection is called given the connection a source address and a destination address. An application would invariably override this function as the default behaviour can only attempt to route the call to the first endpoint type that is not the same type. | The OnRouteConnection function looks up speed dial list given the destination address, which are the digits gathered from the handset. A new H.323 connection created by the H.323 endpoint and the address looked up from the speed dial passed to it. The created H.323 connection creates a new thread to look after the H.225/Q.931signalling channel, and possibly a second thread to look after the H.245 control channel if tunnelling is not available. This thread will cause call back functions on the connection to be called. | The Line endpoint is asked to create a new connection object using to the first POTS line that is not already in use. Note that this is even though the handset is not off hook. The Line endpoint thread must be aware that the next time the handset is picked up it is in response to an incoming call rather than initiating a new connection. |
| Then the manager's OnNewCall function is executed to combine the two connections. The application may override this function to create its own Call class descendent if it requires application specific state information for the call, or to intercept a number of call back functions available on this object. For each connection the AttachCall function is executed to indicate to the connection the call to be used for some call back functions. The remainder of the signalling sequence is now executed. | For H.323 connections the AttachCall also involves building the local H.323 capability set and fast start list from a combination of the other connections GetMediaFormats list and the available transcoders. | For H.323 connections the AttachCall also involves building the local H.323 capability set from the other connections GetMediaFormats list and the available transcoders. If the SETUP PDU had fast start elements then the audio and video elements to be initially started are selected. |
| The SetUp function on the destination connection is called. | The SetUp function starts the H.323 signalling channel background thread, which send the SETUP PDU and awaits replies. Note that to support fast start the media stream selection function described below is done now, creating some media streams but not starting them. | The SetUp function for Line connection begins ringing the handset via the LID. I then calls the OnAlerting function on the Line connection. |
| The new destination connection, which just had the SetUp function called, detects that the entity it represents has begun alerting its user and calls the connections OnAlerting function. Which calls the Call objects OnAlerting function, which in turn calls the source connections DoAlerting function. | When the H.323 signalling thread reads an ALERTING PDU it calls the H.323 connection OnAlerting function. The Line connection DoAlerting function plays the Ring Back tone on the LID. | On a Line connection, the SetUp function called in the previous phase calls the OnAlerting function. The H.323 connection DoAlerting function sends an ALERTING PDU to the remote endpoint. |
| The destination connection detects that the user has answered the call. It calls the OnConnected function, which calls the Call objects OnConnected function, which calls the source connections Connected function. | The H.323 signalling thread then receives the CONNECT PDU which calls the H.323 connection OnConnected function. The Line connection Connected function just stops the ring back tone on the LID. | The Line endpoint’s thread then detects the handset go off hook, which calls the Line connection OnConnected function. The H..323 Connected function sends the CONNECT PDU to the remote endpoint. |
| The SelectMediaStreams function is called on both connections of a call for them to create all source (transmitter) media streams. | An H.323 connection creates an RTP media stream. If there had been fast start elements returned from the remote endpoint, the SelectMediaStreams will create media streams for those media formats. Otherwise it chooses the first entry in the remote endpoints capability set. For the Line connection a LID media stream is created selected from the first media format available in the H.323 connections GetMediaFormats list.
| An H.323 connection creates an RTP media stream. If there had been fast start elements in the SETUP PDU, the SelectMediaStreams will create media streams for the media formats that were selected earlier in this sequence. Otherwise it chooses the first entry in the remote endpoints capability set. For the Line connection a LID media stream is created selected from the first media format available in the H.323 connections GetMediaFormats list. |
| The sink (receiver) media stream are created when the source media stream is started. The OnPatchMediaStream call back on the other connection object to the source media stream is called to create the media stream. | An H.323 connection creates an RTP media stream. For the Line connection a LID media stream is created. | An H.323 connection creates an RTP media stream. For the Line connection a LID media stream is created. |
| At this point we have an established call and the connections OnEstablished functions as well as the managers OnCallEstablished function is called completing the call establishment. |
Call Model
| POTS | H.323 |
| One of the connections detects that the call is to be cleared and call the connections Clear function. | The Line endpoints thread detects the handset has gone on hook and calls Clear on the Line connection. | The H.323 connection calls the Clear function when it received a H.245 end session or a H.225 Release Complete or a gatekeeper DRQ is received or the signalling and control TCP connections unexpectedly shut down. Then a background thread is signalled to complete the shutting down of the connection. This cleans up any resources it has used. |
| The connection is shut down, closing all media streams that it is associated with. Closing a source media stream will then wait for its associated thread to terminate. | Media streams are closed and deleted. | Media streams are closed and deleted when the logical channels are closed. The signalling and control channels are closed, waiting for its threads to terminate. |
| After the connection is shut down the OnClearedConnection function is executed on the call object. This allows an application to intercept this event for its own purposes. The default behaviour is to call Clear on the remaining connection. | Called from the connections Clear function. | Called from the background thread. |
| When the last connection in a call is cleared then the managers OnCallCleared function is executed. The default behaviour is to delete the call, which in turn deletes the connections. |
1.5.1