# OpalListener Class Reference

`#include <transports.h>`

Inheritance diagram for OpalListener:

[legend]
Collaboration diagram for OpalListener:
[legend]

## Operations

typedef PNotifierTemplate< const OpalTransportPtr & > | AcceptHandler
enum | ThreadMode { SpawnNewThreadMode, HandOffThreadMode, SingleThreadMode }
virtual bool | Open (const AcceptHandler &acceptHandler, ThreadMode mode=SpawnNewThreadMode)
virtual bool | IsOpen () const =0
virtual void | Close ()=0
virtual OpalTransport * | Accept (const PTimeInterval &timeout)=0
virtual OpalTransport * | CreateTransport (const OpalTransportAddress &localAddress, const OpalTransportAddress &remoteAddress) const =0
virtual OpalTransportAddress | GetLocalAddress (const OpalTransportAddress &remoteAddress=OpalTransportAddress()) const =0
void | CloseWait ()
void | CleanUpOnTermination ()

## Public Member Functions

Construction
| OpalListener (OpalEndPoint &endpoint)
Overrides from PObject
void | PrintOn (ostream &strm) const

## Protected Member Functions

void | ListenForConnections ()
void | TransportThreadMain (OpalTransportPtr transport)

## Protected Attributes

OpalEndPoint & | endpoint
PThread * | thread
AcceptHandler | acceptHandler
ThreadMode | threadMode

## Detailed Description

This class describes a "listener" on a transport protocol. A "listener" is an object that listens for incoming connections on the particular transport. It is executed as a separate thread.

The Main() function is used to handle incoming connections and dispatch them in new threads based on the actual OpalTransport class. This is defined in the descendent class that knows what the low level transport is, eg OpalListenerIP for the TCP/IP protocol.

An application may create a descendent off this class and override functions as required for operating the channel protocol.

## Member Typedef Documentation

typedef PNotifierTemplate<const OpalTransportPtr &> OpalListener::AcceptHandler

## Member Enumeration Documentation

enum OpalListener::ThreadMode

Enumerator:

  SpawnNewThreadMode |
  HandOffThreadMode |
  SingleThreadMode |

## Constructor & Destructor Documentation

OpalListener::OpalListener | ( | OpalEndPoint & | endpoint | ) |

Create a new listener.

Parameters:

  endpoint | Endpoint listener is used for

## Member Function Documentation

virtual OpalTransport* OpalListener::Accept | ( | const PTimeInterval & | timeout | ) | `[pure virtual]`

Accept a new incoming transport.

Parameters:

  timeout | Time to wait for incoming connection

Implemented in OpalListenerTCP, and OpalListenerUDP.

void OpalListener::CleanUpOnTermination | ( |  | ) | `[inline]`

Close channel and wait for associated thread to terminate. For backward compatibility with OpenH323, now deprecated.

virtual void OpalListener::Close | ( |  | ) | `[pure virtual]`

Stop the listener thread and no longer accept incoming connections.

Implemented in OpalListenerTCP, and OpalListenerUDP.

void OpalListener::CloseWait | ( |  | ) |

Close channel and wait for associated thread to terminate.

virtual OpalTransport* OpalListener::CreateTransport | ( | const OpalTransportAddress & | localAddress,
|  | const OpalTransportAddress & | remoteAddress |
| ) |  |  | const`[pure virtual]`

Create a transport compatible with this listener.

Implemented in OpalListenerTCP, and OpalListenerUDP.

virtual OpalTransportAddress OpalListener::GetLocalAddress | ( | const OpalTransportAddress & | remoteAddress = `OpalTransportAddress()` | ) | const`[pure virtual]`

Get the local transport address on which this listener may be accessed. If remoteAddress is present and is an address that requires NAT for connectivity, then the returned address is adjusted to return the external address and port.

Implemented in OpalListenerIP, and OpalListenerUDP.

virtual bool OpalListener::IsOpen | ( |  | ) | const`[pure virtual]`

Indicate if the listener is open.

Implemented in OpalListenerTCP, and OpalListenerUDP.

void OpalListener::ListenForConnections | ( |  | ) | `[protected]`

Handle incoming connections and dispatch them in new threads based on the OpalTransport class. This is defined in the descendent class that knows what the low level transport is, eg OpalListenerTCP for the TCP/IP protocol.

Note this function does not return until the Close() function is called or there is some other error.

virtual bool OpalListener::Open | ( | const AcceptHandler & | acceptHandler,
|  | ThreadMode | mode = `SpawnNewThreadMode` |
| ) |  |  | `[virtual]`

Open the listener. A thread is spawned to listen for incoming connections. The notifier function acceptHandler is called when a new connection is created. The INT parameter to the acceptHandler is a pointer to the new OpalTransport instance created by the listener. If this is NULL then it indicates an error occurred during the accept.

If singleThread is false the acceptHandler function is called in the context of a new thread and the continues to listen for more connections. If true, then the acceptHandler function is called from within the listener threads context and no more connections are created. That is only a single connection is ever created by this listener.

Parameters:

  acceptHandler | Handler function for new connections
  mode | How handler function is called thread wise

void OpalListener::PrintOn | ( | ostream & | strm | ) | const

Print the description of the listener to the stream.

void OpalListener::TransportThreadMain | ( | OpalTransportPtr | transport | ) | `[protected]`

## Field Documentation

AcceptHandler OpalListener::acceptHandler `[protected]`

OpalEndPoint& OpalListener::endpoint `[protected]`

PThread* OpalListener::thread `[protected]`

ThreadMode OpalListener::threadMode `[protected]`

The documentation for this class was generated from the following file:

- transports.h