docs/Overview.htm

   1 <html>
   2   <head>
   3     <title>Open Phone Abstraction Library</title>
   4     <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
   5   </head>
   6   <body lang="EN-AU">
   7     <h1>Open Phone Abstraction Library</h1>
   8     <p>OPAL is a C++ class library for normalising the numerous telephony protocols
   9       into a single integrated call model. The following is a general overview of the
  10       library.</p>
  11     <p align="center">
  12       <img width="519" height="165" src="./diagram.gif"></p>
  13     <P>Which is your typical layered approach to a system. The application layer is
  14       presented with a unified model for making calls over whatever underlying
  15       protocol or hardware by the so the calls can be placed and media flow handled
  16       in, as much as possible, an&nbsp;identical manner.</P>
  17     <P>A <I>Call</I> is defined as the connection between two or more <I>Addresses</I>
  18       each through a <I>Connection</I> created by an <I>Endpoint.</I> The call
  19       usually has multiple <I>Media Streams</I> transferring information (eg voice)
  20       of a particular <EM>Media Format</EM> from one endpoint to another. The data is
  21       copied from a <EM>Source Media Stream </EM>to a <EM>Sink Media Stream</EM> via
  22       a <EM>Media Patch</EM> thread.
  23     </P>
  24     <P>An application can control the connection between endpoints according to its
  25       own logic. For example all incoming calls are routed to the POTS port.</P>
  26     <h2>Protocol Abstractions</h2>
  27     <p>A protocol is abstracted into several entities representing aspects of the
  28       call model. These are defined as the <EM>Address</EM>, <EM>Endpoint</EM>, <EM>Connection</EM>,
  29       <EM>Call </EM>&amp; <EM>MediaStream</EM>.</p>
  30     <h3>Addresses</h3>
  31     <p>A call <i>Address</i> is a string consisting of a unique string identifier for
  32       the protocol or endpoint type to be used followed by a colon and a string that
  33       is dependent on that line for its format. For instance a PSTN line would expect
  34       a simple phone number. As it is a text string, the address maximises
  35       portability and useability for user interfaces. For example, a call to a number
  36       using a PSTN endpoint would be “pstn:555-1234” or “pstn:555-1234@line1” where
  37       “line1” is the name of a specific instance of a PSTN endpoint. Another example
  38       would be “h323:phone.quicknet.net” or “h323:derhart@gk.quicknet.net” where the
  39       second form indicates a gateway to use for the specified alias.</p>
  40     <h3>Endpoint</h3>
  41     <p>An <i>Endpoint</i> embodies the permanent aspects of a telephone abstraction
  42       for a particular protocol. There is usually one and only one instance of each
  43       specific endpoint class. Its lifetime is usually the duration of the
  44       application.</p>
  45     <p>There are two broad types of endpoints, a <i>Terminal Endpoint</i> and a <i>Network
  46         Endpoint.</i> A terminal endpoint is one where a call usually ends, for
  47       example a POTS port with a phone handset attached. A network endpoint is one
  48       that connects through a network of some form, not necessarily a LAN or
  49       Internet. For example, H.323 protocol stack or a PSTN line.</p>
  50     <p>Each endpoint has a set of attributes that can control its default behaviour.
  51       For example whether it is a terminal or network endpoint. An endpoint may
  52       support a single (eg PSTN/POTS), dual (eg ISDN BRI) or many (eg H.323/SIP)
  53       simultaneous connections. An endpoint may only accept incoming calls (SIP
  54       server), only be able to make calls (SIP client, or Net2phone) or both
  55       depending on the semantics of the underlying protocol. All of these attributes
  56       are abstracted for default behaviour that the application can override through
  57       the use of call back functions.</p>
  58     <p>The classes H323EndPoint and OpalLIDEndPoint are examples of endpoints.</p>
  59     <h3>Connection</h3>
  60     <p>A <i>Connection</i> embodies the more ephemeral attributes of the telephone
  61       call when a connection is active from this application using the specified
  62       protocol. This contains all of the state information for maintaining the
  63       connection to whatever the protocol dictates is the “remote”.</p>
  64     <p>For example a call linking a remote H.323 endpoint to a simple telephone
  65       handset would have a H323Connection and an OpalLIDConnection. The
  66       H323Connection contains such things as the sockets to maintain the signalling
  67       and control channels from this host to the remote H.323 host. The
  68       OpalLIDConnection contains a pointer to a OpalLineInterfaceDevice and has such
  69       things as its current state eg ringing, playing engaged tone etc.</p>
  70     <p>This objects lifetime is for the duration of the connection and is usually
  71       dictated by external influences, eg picking up the handset and then replacing
  72       it. The <i>Endpoint</i> creates and deletes the <i>Connection</i> as required,
  73       though the application can get involved in this processing if it needs to, eg
  74       to add extra information on a connection by connection basis.</p>
  75     <h3>Call</h3>
  76     <p>A <i>Call</i> is the entity that connects two or more connections together.
  77       This is typically created by the application in response to call backs for an
  78       incoming connection on a protocol. The application can decide routing by
  79       whatever means and create a second connection using a protocol of its choice.
  80       Then the call is created with the two connections.</p>
  81     <p>The lifetime of the call is controlled by the application, but is typically
  82       for as long as there is at least one connection that attached to it.</p>
  83     <h3>Media Streams</h3>
  84     <p>A <i>Media Stream</i> embodies a source or sink of data of a particular <i>Media
  85         Format</i>, eg, audio data (G.711), video data (H.261) or T.120 conferencing
  86       data.</p>
  87     <p>Each protocol utilises a particular type of media stream. For example the
  88       H.323 protocol would create media streams that utilise an RTP session. The
  89       Telephone Line protocol creates media streams that use an
  90       OpalLineInterfaceDevice for its I/O.</p>
  91     <p>The lifetime of the media stream is highly dependent on the protocol. They may
  92       come and go on demand as dictated by the underlying protocol. For example a
  93       H.323 video media stream is not created immediately on the call beginning, but
  94       later on user request. And when the user closes the video window the video
  95       media stream is then closed and deleted. However, the media streams for a
  96       Telephone Line would be created with its connection and remain for the duration
  97       of the connection as there is always a fixed one to two relationship between a
  98       Telephone Line and its media streams (source and sink).</p>
  99     <p>When data is transferred from a source media stream to a sink media stream,
 100       there may be required software conversion of the media format. For example if
 101       an H.323 connection was providing a source media stream that used the G.711
 102       media format, and the sink media stream was a LID connection using a line
 103       interface device that supported G.711 directly, then data may be simply copied
 104       from one to the other. If however, the sink is a sound card then a software
 105       codec, or <i>Transcoder</i>, is required to convert the G.711 media format to
 106       the PCM-16 media format. If there is no transcoder available then the media
 107       stream fails to open and is removed.</p>
 108     <h3>Manager</h3>
 109     <p>There is one more entity in the OPAL architecture. The OpalManager is
 110       essentially just a target for numerous call back functions that the system can
 111       generate. An application would have a single instance of a descendant of this
 112       class and would typically hang all of its control logic in there. At the very
 113       least handling functions such as OnIncomingConnection and routing this to
 114       another protocol endpoint to complete a call.</p>
 115     <h2>Call Scenarios</h2>
 116     <p>Here are some typical scenarios to show how the various entities operate
 117       together.</p>
 118     <p>The scenarios here are based on an “OpenPhone” style application that has
 119       H.323 and LID (PhoneJACK etc) support.</p>
 120     <h3>Initialisation</h3>
 121     <p>Upon start up instances of three endpoints are created: one for H.323, one for
 122       a Telephone Line and one for the PC sound system.</p>
 123     <p>The H.323 endpoint creates a background thread to listen for incoming calls.
 124       Typically this is TCP port 1720. As many threads and “listeners” may be created
 125       for different interfaces, ports or protocol (eg Ipv6).</p>
 126     <p>The Telephone Line endpoint creates a background thread that monitors the Line
 127       Interface Device state, eg on or off hook etc. Note that the Telephone Line
 128       endpoint can have multiple LIDs and each LID can have multiple physical lines,
 129       so quite a few Telephone Lines can be monitored by this endpoint.</p>
 130     <p>The PC sound system would nor create any background threads as its control
 131       actions (on/off hook equivalent) are all done though call back functions that
 132       interface to the applications user interface threads. For example when a button
 133       is pressed in a make call dialog then a function is called on the PCSS endpoint
 134       and its internal state is changed to “off hook”. The thread that controls this
 135       is the user interface thread.</p>
 136     <h3>Establishing a call</h3>
 137     <table border="1" cellspacing="1" cellpadding="2">
 138       <tr>
 139         <td width="393" valign="top">
 140           <h4>Call Model</h4>
 141         </td>
 142         <td width="393" valign="top">
 143           <p><b>POTS to H.323</b></p>
 144         </td>
 145         <td width="393" valign="top">
 146           <p><b>H.323 to POTS</b></p>
 147         </td>
 148       </tr>
 149       <tr>
 150         <td width="393" valign="top">
 151           <p>Connection detected.</p>
 152           <p>An endpoint detects a new connection via some means and creates a connection
 153             object.</p>
 154         </td>
 155         <td width="393" valign="top">
 156           <p>When the user picks up the handset the Telephone Line Endpoints background
 157             thread detects this and creates a Telephone Line Connection object. The
 158             Telephone Line Endpoint must remember this object as it continues to monitor
 159             the line for the user placing the receiver back on hook.</p>
 160         </td>
 161         <td width="393" valign="top">
 162           <p>The background thread of the H.323 endpoint accepts an incoming TCP connection
 163             and after reading the first SETUP PDU it creates a H.323 connection object. The
 164             created H.323 connection creates a new thread to look after the
 165             H.225/Q.931signalling channel, and possibly a second thread to look after the
 166             H.245 control channel if tunnelling is not available. This thread will cause
 167             call back functions on the connection to be called.</p>
 168         </td>
 169       </tr>
 170       <tr>
 171         <td width="393" valign="top">
 172           <p>Upon creation of the new connection object this is passed to the manager call
 173             back OnIncomingConnection. An application could override this function for any
 174             special treatment, for example getting a account number and PIN code via the
 175             use of the endpoints GetUserIndication function. The default behaviour would
 176             call the connections GetDestinationAddress function
 177           </p>
 178         </td>
 179         <td width="393" valign="top">
 180           <p>The Line connection GetUserIndication gets a DTMF tone from the LID.</p>
 181           <p>The Line connection GetDestinationAddress gathers a sequence of DTMF digits
 182             from the LID.</p>
 183         </td>
 184         <td width="393" valign="top">
 185           <p>The H.323 connection GetUserIndication returns the last value received in the
 186             H.245 UserIndication PDU.</p>
 187           <p>The H.323 connection GetDestinationAddress looks at the various fields of the
 188             last received SETUP PDU such as destinationAlias to determine a destination
 189             address.</p>
 190         </td>
 191       </tr>
 192       <tr>
 193         <td width="393" valign="top">
 194           <p>Now the manager’s OnRouteConnection is called given the connection a source
 195             address and a destination address. An application would invariably override
 196             this function as the default behaviour can only attempt to route the call to
 197             the first endpoint type that is not the same type.</p>
 198         </td>
 199         <td width="393" valign="top">
 200           <p>The OnRouteConnection function looks up speed dial list given the destination
 201             address, which are the digits gathered from the handset. A new H.323 connection
 202             created by the H.323 endpoint and the address looked up from the speed dial
 203             passed to it.</p>
 204           <p>The created H.323 connection creates a new thread to look after the
 205             H.225/Q.931signalling channel, and possibly a second thread to look after the
 206             H.245 control channel if tunnelling is not available. This thread will cause
 207             call back functions on the connection to be called.</p>
 208         </td>
 209         <td width="393" valign="top">
 210           <p>The Line endpoint is asked to create a new connection object using to the
 211             first POTS line that is not already in use.</p>
 212           <p>Note that this is even though the handset is not off hook. The Line endpoint
 213             thread must be aware that the next time the handset is picked up it is in
 214             response to an incoming call rather than initiating a new connection.</p>
 215         </td>
 216       </tr>
 217       <tr>
 218         <td width="393" valign="top">
 219           <p>Then the manager’s OnNewCall function is executed to combine the two
 220             connections. The application may override this function to create its own Call
 221             class descendent if it requires application specific state information for the
 222             call, or to intercept a number of call back functions available on this object.</p>
 223           <p>For each connection the AttachCall function is executed to indicate to the
 224             connection the call to be used for some call back functions.</p>
 225           <p>The remainder of the signalling sequence is now executed.</p>
 226         </td>
 227         <td width="393" valign="top">
 228           <p>For H.323 connections the AttachCall also involves building the local H.323
 229             capability set and fast start list from a combination of the other connections
 230             GetMediaFormats list and the available transcoders.</p>
 231         </td>
 232         <td width="393" valign="top">
 233           <p>For H.323 connections the AttachCall also involves building the local H.323
 234             capability set from the other connections GetMediaFormats list and the
 235             available transcoders.</p>
 236           <p>If the SETUP PDU had fast start elements then the audio and video elements to
 237             be initially started are selected.</p>
 238         </td>
 239       </tr>
 240       <tr>
 241         <td width="393" valign="top">
 242           <p>The SetUp function on the destination connection is called.</p>
 243         </td>
 244         <td width="393" valign="top">
 245           <p>The SetUp function starts the H.323 signalling channel background thread,
 246             which send the SETUP PDU and awaits replies.</p>
 247           <p>Note that to support fast start the media stream selection function described
 248             below is done now, creating some media streams but not starting them.</p>
 249         </td>
 250         <td width="393" valign="top">
 251           <p>The SetUp function for Line connection begins ringing the handset via the LID.
 252             I then calls the OnAlerting function on the Line connection.</p>
 253         </td>
 254       </tr>
 255       <tr>
 256         <td width="393" valign="top">
 257           <p>The new destination connection, which just had the SetUp function called,
 258             detects that the entity it represents has begun alerting its user and calls the
 259             connections OnAlerting function. Which calls the Call objects OnAlerting
 260             function, which in turn calls the source connections DoAlerting function.</p>
 261         </td>
 262         <td width="393" valign="top">
 263           <p>When the H.323 signalling thread reads an ALERTING PDU it calls the H.323
 264             connection OnAlerting function.</p>
 265           <p>The Line connection DoAlerting function plays the Ring Back tone on the LID.</p>
 266         </td>
 267         <td width="393" valign="top">
 268           <p>On a Line connection, the SetUp function called in the previous phase calls
 269             the OnAlerting function.</p>
 270           <p>The H.323 connection DoAlerting function sends an ALERTING PDU to the remote
 271             endpoint.</p>
 272         </td>
 273       </tr>
 274       <tr>
 275         <td width="393" valign="top">
 276           <p>The destination connection detects that the user has answered the call. It
 277             calls the OnConnected function, which calls the Call objects OnConnected
 278             function, which calls the source connections Connected function.</p>
 279         </td>
 280         <td width="393" valign="top">
 281           <p>The H.323 signalling thread then receives the CONNECT PDU which calls the
 282             H.323 connection OnConnected function.</p>
 283           <p>The Line connection Connected function just stops the ring back tone on the
 284             LID.</p>
 285         </td>
 286         <td width="393" valign="top">
 287           <p>The Line endpoint’s thread then detects the handset go off hook, which calls
 288             the Line connection OnConnected function.</p>
 289           <p>The H..323 Connected function sends the CONNECT PDU to the remote endpoint.</p>
 290         </td>
 291       </tr>
 292       <tr>
 293         <td width="393" valign="top">
 294           <p>The SelectMediaStreams function is called on both connections of a call for
 295             them to create all source (transmitter) media streams.</p>
 296         </td>
 297         <td width="393" valign="top">
 298           <p>An H.323 connection creates an RTP media stream. If there had been fast start
 299             elements returned from the remote endpoint, the SelectMediaStreams will create
 300             media streams for those media formats. Otherwise it chooses the first entry in
 301             the remote endpoints capability set.</p>
 302           <p>For the Line connection a LID media stream is created selected from the first
 303             media format available in the H.323 connections GetMediaFormats list.
 304           </p>
 305         </td>
 306         <td width="393" valign="top">
 307           <p>An H.323 connection creates an RTP media stream. If there had been fast start
 308             elements in the SETUP PDU, the SelectMediaStreams will create media streams for
 309             the media formats that were selected earlier in this sequence. Otherwise it
 310             chooses the first entry in the remote endpoints capability set.</p>
 311           <p>For the Line connection a LID media stream is created selected from the first
 312             media format available in the H.323 connections GetMediaFormats list.</p>
 313         </td>
 314       </tr>
 315       <tr>
 316         <td width="393" valign="top">
 317           <p>The sink (receiver) media stream are created when the source media stream is
 318             started. The OnPatchMediaStream call back on the <u>other</u> connection object
 319             to the source media stream is called to create the media stream.</p>
 320         </td>
 321         <td width="393" valign="top">
 322           <p>An H.323 connection creates an RTP media stream.</p>
 323           <p>For the Line connection a LID media stream is created.</p>
 324         </td>
 325         <td width="393" valign="top">
 326           <p>An H.323 connection creates an RTP media stream.</p>
 327           <p>For the Line connection a LID media stream is created.</p>
 328         </td>
 329       </tr>
 330       <tr>
 331         <td width="393" valign="top">
 332           <p>At this point we have an established call and the connections OnEstablished
 333             functions as well as the managers OnCallEstablished function is called
 334             completing the call establishment.</p>
 335         </td>
 336         <td width="393" valign="top">
 337           <p>&nbsp;</p>
 338         </td>
 339         <td width="393" valign="top">
 340           <p>&nbsp;</p>
 341         </td>
 342       </tr>
 343     </table>
 344     <h3>Clearing a call</h3>
 345     <table border="0" cellspacing="0" cellpadding="0">
 346       <tr>
 347         <td width="393" valign="top">
 348           <h4>Call Model</h4>
 349         </td>
 350         <td width="393" valign="top">
 351           <p><b>POTS</b></p>
 352         </td>
 353         <td width="393" valign="top">
 354           <p><b>H.323</b></p>
 355         </td>
 356       </tr>
 357       <tr>
 358         <td width="393" valign="top">
 359           <p>One of the connections detects that the call is to be cleared and call the
 360             connections Clear function.</p>
 361         </td>
 362         <td width="393" valign="top">
 363           <p>The Line endpoints thread detects the handset has gone on hook and calls Clear
 364             on the Line connection.</p>
 365         </td>
 366         <td width="393" valign="top">
 367           <p>The H.323 connection calls the Clear function when it received a H.245 end
 368             session or a H.225 Release Complete or a gatekeeper DRQ is received or the
 369             signalling and control TCP connections unexpectedly shut down.</p>
 370           <p>Then a background thread is signalled to complete the shutting down of the
 371             connection. This cleans up any resources it has used.</p>
 372         </td>
 373       </tr>
 374       <tr>
 375         <td width="393" valign="top">
 376           <p>The connection is shut down, closing all media streams that it is associated
 377             with.</p>
 378           <p>Closing a source media stream will then wait for its associated thread to
 379             terminate.</p>
 380         </td>
 381         <td width="393" valign="top">
 382           <p>Media streams are closed and deleted.</p>
 383         </td>
 384         <td width="393" valign="top">
 385           <p>Media streams are closed and deleted when the logical channels are closed.</p>
 386           <p>The signalling and control channels are closed, waiting for its threads to
 387             terminate.</p>
 388         </td>
 389       </tr>
 390       <tr>
 391         <td width="393" valign="top">
 392           <p>After the connection is shut down the OnClearedConnection function is executed
 393             on the call object. This allows an application to intercept this event for its
 394             own purposes. The default behaviour is to call Clear on the remaining
 395             connection.</p>
 396         </td>
 397         <td width="393" valign="top">
 398           <p>Called from the connections Clear function.</p>
 399         </td>
 400         <td width="393" valign="top">
 401           <p>Called from the background thread.</p>
 402         </td>
 403       </tr>
 404       <tr>
 405         <td width="393" valign="top">
 406           <p>When the last connection in a call is cleared then the managers OnCallCleared
 407             function is executed. The default behaviour is to delete the call, which in
 408             turn deletes the connections.</p>
 409         </td>
 410         <td width="393" valign="top">
 411           <p>&nbsp;</p>
 412         </td>
 413         <td width="393" valign="top">
 414           <p>&nbsp;</p>
 415         </td>
 416       </tr>
 417     </table>
 418     <p>&nbsp;</p>
 419     <h3>Establishing a call from POTS to H.323</h3>
 420     <p>When the user hangs up the handset the Telephone Line Endpoints background
 421       thread detects this and calls the Clear function on the Line connection.</p>
 422     <h2>Application Overview</h2>
 423     <p>An application would create an instance of an OpalManager and then instances
 424       of various OpalEndpoint descendants that it wishes to support. The endpoints
 425       may have protocol specific initialisation. For example with H.323 this could be
 426       the connection to a gatekeeper and logging into it. For LID endpoints it may be
 427       the programming of country specific data for each PSTN line.</p>
 428     <p>After this, the system is ready to accept or make calls.</p>
 429     <h2>Main Classes</h2>
 430     <h3>OpalManager</h3>
 431     <p>An application would typically create a single instance of a descendent of
 432       this class, which manages all of the endpoints and calls between endpoints
 433       within the overall library. This class has many virtual functions for allowing
 434       the application to obtain notification of events within each of the endpoints
 435       as they occur.</p>
 436     <h3>OpalEndpoint</h3>
 437     <p>An application, upon creating the OpalManager, would then create all of the
 438       endpoints it is going to support. These instances are descended from this
 439       class. For example the H323Endpoint class is a descendent from OpalEndpoint and
 440       represents an endpoint for the H.323 protocol.</p>
 441     <p>The main functionality available on an endpoint is as follows. Note that each
 442       function is context sensitive and each of the specific endpoint types (H.323
 443       etc) will act according to its exact semantics.</p>
 444     <p>
 445       <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
 446         <TR>
 447           <TD width="50" height="40">State</TD>
 448           <TD height="40">
 449             <P>Get or set the state of the endpoint. The set state is only possible on a
 450               network endpoint and may be subject to other restrictions depending on the
 451               semantics of the underlying protocol. The get state returns the current state
 452               which may not be the same as that used in a set state call as it always
 453               reflects the actual state of endpoint. The states are:</P>
 454             <UL dir="ltr" style="MARGIN-RIGHT: 0px">
 455               <LI>
 456                 Inactive&nbsp;Endpoint is down and cannot make calls.
 457               </LI>
 458               <LI>
 459                 Idle&nbsp;Endpoint is available but not in use</LI>
 460               <LI>
 461                 Ringing&nbsp;Endpoint has an incoming call.
 462               </LI>
 463               <LI>
 464                 CallProceeding&nbsp;Endpoint is connecting to a remote party.
 465               </LI>
 466               <LI>
 467                 Alerting&nbsp;Remote party is being alerted.
 468               </LI>
 469               <LI>
 470                 CallEstablished&nbsp;Call is established.</LI></UL>
 471           </TD>
 472         </TR>
 473         <TR>
 474           <TD width="50">Register</TD>
 475           <TD>Register the endpoint with its terminal or network. If successful, it
 476             typically moves the endpoint from the Inactive to Idle states. A local
 477             identifier may be provided which indicates how the endpoint is advertised to
 478             the outside world. For a terminal endpoint this would only be used for internal
 479             switching algorithms. For network endpoints this may not be adjustable, for
 480             example the phone number of a PSTN endpoint may be set within the context of
 481             the library, but changing the value does not change what the endpoint is
 482             physically attached to.</TD>
 483         </TR>
 484         <TR>
 485           <TD width="50">Unregister</TD>
 486           <TD>Unregister the endpoint from its terminal or network. This will drop any
 487             existing calls and move the endpoint to the inactive state.</TD>
 488         </TR>
 489         <TR>
 490           <TD width="50">Remote ID</TD>
 491           <TD>Get or set the remote identifier used on the endpoint. For an incoming call
 492             on a network endpoint, this would be the Caller ID. Doing a set remote
 493             identifier on a terminal endpoint would send the Caller ID to the terminal. A
 494             set for a network endpoint would be ignored.</TD>
 495         </TR>
 496         <TR>
 497           <TD width="50">Connect</TD>
 498           <TD>Establish a connection to an address on a network endpoint. For a terminal
 499             line it will cause the line to ring.</TD>
 500         </TR>
 501         <TR>
 502           <TD width="50">Answer</TD>
 503           <TD>Establish a connection to an incoming call on a network line.</TD>
 504         </TR>
 505         <TR>
 506           <TD width="50">Disconnect</TD>
 507           <TD>Drop an established connection on a line. If this leaves only one line left
 508             in a call, then that line is disconnected as well and the call is cleared.</TD>
 509         </TR>
 510         <TR>
 511           <TD width="50">Indications</TD>
 512           <TD>Send and receive user indications. For example DTMF tones on a PSTN line.</TD>
 513         </TR>
 514         <TR>
 515           <TD width="50">Media Format</TD>
 516           <TD>Get or set the encoding schemes used for transferring media data. An endpoint
 517             may encode several channels of media data, each of which may be one of many
 518             encoding methods.</TD>
 519         </TR>
 520         <TR>
 521           <TD width="50">Capabilities</TD>
 522           <TD>Functions for determining what the specific line class is capable of.</TD>
 523         </TR>
 524         <TR>
 525           <TD width="50">Monitors</TD>
 526           <TD>Call back functions to allow the application to be informed of events and
 527             state changes in the line.</TD>
 528         </TR>
 529       </TABLE>
 530       &nbsp;</p>
 531     <p>
 532       &nbsp;</p>
 533     <h3>H323Endpoint</h3>
 534     <p>An endpoint for the H.323 protocol.</p>
 535     <h3>SipServerEndpoint</h3>
 536     <p>An endpoint for incoming SIP protocol calls.</p>
 537     <h3>SipClientEndpoint</h3>
 538     <p>An endpoint for outgoing SIP protocol calls.</p>
 539     <h3>LIDEndpoint</h3>
 540     <p>An endpoint for OpalLineInterfaceDevice lines. A number of LIDs may be
 541       attached to this endpoint</p>
 542     <h3>OpalLineInterfaceDevice</h3>
 543     <p>The PSTN and POTS line types are built on a further sub-system that defines a <i style='mso-bidi-font-style:
 544 normal'>Line Interface Device</i>. This abstracts a hardware device that embodies
 545       PSTN or POTS lines. A single instance of a LID may controls one or more
 546       physical lines.</p>
 547     <h3>PCEndpoint</h3>
 548     <p>A simulated terminal endpoint based on standard personal computer user
 549       interface components. Audio media is via standard sound cards, video media to
 550       the screen, user indications and control signalling are via keyboard or GUI
 551       based controls. An application would typically create a descendent of this
 552       class to implement the details of the user interface.</p>
 553     <h3>OpalCall</h3>
 554     <p>This is the class that embodies a call that is currently in progress. It
 555       essentially consists of zero or more instances of OpalConnection descendent
 556       classes, for example a H323Connection. A conference can be supported when more
 557       than two connections are involved in a call. This could also support
 558       forwarding, hold and similar call management functions.</p>
 559     <h3>OpalConnection</h3>
 560     <p>This class is that part of a call being a connection to a specific endpoint.
 561       The connection consists of some state information, source and destination
 562       addresses/aliases and zero or more media channels. A connections lifetime is
 563       the duration of the call.</p>
 564     <h3>OpalMediaStream</h3>
 565     <p>This represents a media stream to or from a connection. For example there is a
 566       one to one relationship between an OpalMediaStream class and a H.323 Logical
 567       Channel. A channel may be a source or a sink of media data. The source</p>
 568     <h3>OpalMediaPatch</h3>
 569     <p>This is the class that implements the linking of media streams. It contains
 570       the thread of control that reads from a source media stream, optionally
 571       converts its format using the transcoder library, then writes the media data to
 572       the sink media stream. A jitter buffer may also be inserted into the pipeline.</p>
 573     <h3>OpalTranscoder</h3>
 574     <p>This represents a media conversion function. This may be used to match the
 575       media data format provided by media streams. This contains all the state
 576       information for the appropriate translation algorithm. Instances of this class
 577       only exist for the duration of a media patch that requires conversion of data
 578       from the source stream to the destination stream.</p>
 579   </body>
 580 </html>