class H323GatekeeperServer: public PObject

This class implements a basic gatekeeper server functionality.

Inheritance:


Public

[more] Construction
[more] Protocol Handler Operations
[more] EndPoint Operations
[more] Call Operations
[more] Routing operations
[more] Policy operations
[more] Access functions


Documentation

This class implements a basic gatekeeper server functionality. An instance of this class contains all of the state information and operations for a gatekeeper. Multiple gatekeeper listeners may be using thsi class to link individual UDP (or other protocol) packets from various sources (interfaces etc) into a single instance.

There is typically only one instance of this class, though it is not limited to that. An application would also quite likely descend from this class and override call back functions to implement more complex policy.

o Construction

o H323GatekeeperServer( H323EndPoint & endpoint )
Create a new gatekeeper

o Protocol Handler Operations

oBOOL AddListener( const H323TransportAddress & interfaceName )
Add a gatekeeper listener to this gatekeeper server given the transport address for the local interface

oBOOL AddListener( H323Transport * transport )
Add a gatekeeper listener to this gatekeeper server given the transport. Note that the transport is then owned by the listener and will be deleted automatically when the listener is destroyed. Note also the transport is deleted if this function returns FALSE and no listener was created.

oBOOL AddListener( H323GatekeeperListener * listener )
Add a gatekeeper listener to this gatekeeper server. Note that the gatekeeper listener is then owned by the gatekeeper server and will be deleted automatically when the listener is removed. Note also the listener is deleted if this function returns FALSE and the listener was not used.

ovirtual H323GatekeeperListener* CreateListener( H323Transport * transport )
Create a new H323Gatlistner. The user woiuld not usually use this function as it is used internally by the server when new listeners are added by H323TransportAddress.

However, a user may override this function to create objects that are user defined descendants of H323GatekeeperListener so the user can maintain extra information on a interface by interface basis.

oBOOL RemoveListener( H323GatekeeperListener * listener )
Remove a gatekeeper listener from this gatekeeper server. The gatekeeper listener is automatically deleted.

o EndPoint Operations

ovirtual BOOL OnRegistration( H323RegisteredEndPoint * & ep, const H225_RegistrationRequest & rrq, H225_RegistrationConfirm & rcf, H225_RegistrationReject & rrj )
Call back on receiving a RAS registration for this endpoint. The default behaviour checks if the registered endpoint already exists and if not creates a new endpoint. It then calls the OnRegistration() on that new endpoint instance.

If returns TRUE then a RCF is sent otherwise an RRJ is sent.

ovirtual BOOL OnUnregistration( H323RegisteredEndPoint * ep, const H225_UnregistrationRequest & urq, H225_UnregistrationConfirm & ucf, H225_UnregistrationReject & urj )
Handle an unregistration URQ PDU. The default behaviour removes the aliases defined in the URQ and if all aliases for the registered endpoint are removed then the endpoint itself is removed.

ovirtual void AddEndPoint( H323RegisteredEndPoint * ep )
Add a new registered endpoint to the server database. Once the endpoint has been added it is then owned by the server and will be deleted when it is removed.

The user woiuld not usually use this function as it is used internally by the server when new registration requests (RRQ) are received.

Note that a registered endpoint has no realationship in this software to a H323EndPoint class.

ovirtual void RemoveEndPoint( H323RegisteredEndPoint * ep, BOOL autoDelete = TRUE, BOOL lock = TRUE )
Remove a registered endpoint from the server database

ovirtual void RemoveAlias( const PString & alias, BOOL autoDelete = TRUE )
Remove an alias from the server database. A registered endpoint is searched for and the alias removed from that endpoint. If there are no more aliases left for the endpoint then the registered endpoint itself is removed from the database.

ovirtual H323RegisteredEndPoint* CreateRegisteredEndPoint( const H225_RegistrationRequest & rrq )
Create a new registered endpoint object. The user woiuld not usually use this function as it is used internally by the server when new registration requests (RRQ) are received.

However, a user may override this function to create objects that are user defined descendants of H323RegisteredEndPoint so the user can maintain extra information on a endpoint by endpoint basis.

ovirtual PString CreateEndPointIdentifier()
Create a new unique identifier for the registered endpoint. The returned identifier must be unique over the lifetime of this gatekeeper server.

The default behaviour simply returns the string representation of the member variable nextIdentifier. There could be a problem in this implementation after 4,294,967,296 have been registered.

ovirtual H323RegisteredEndPoint* FindEndPointByIdentifier( const PString & identifier )
Find a registered alias given its endpoint identifier

ovirtual H323RegisteredEndPoint* FindEndPointBySignalAddresses( const H225_ArrayOf_TransportAddress & addresses )
Find a registered alias given a list of signal addresses

ovirtual H323RegisteredEndPoint* FindEndPointBySignalAddress( const H323TransportAddress & address )
Find a registered alias given its signal address

ovirtual H323RegisteredEndPoint* FindEndPointByAliasAddress( const H225_AliasAddress & alias )
Find a registered alias given its raw alias address

ovirtual H323RegisteredEndPoint* FindEndPointByAliasString( const PString & alias )
Find a registered alias given its simple alias string

oH323RegisteredEndPoint* FirstEndPoint()
Get the first registered endpoint in the gatekeeper server database. Note that the database is locked and no access to endpoints may be made until all registered endpoints are enumerated (NextEndPoint() returns NULL) or AbortEnumeration() is called.

oH323RegisteredEndPoint* NextEndPoint()
Get the next registered endpoint in the gatekeeper server database. Note that the database is locked and no access to endpoints may be made until all registered endpoints are enumerated (NextEndPoint() returns NULL) or AbortEnumeration() is called.

ovoid AbortEnumeration()
Abort the enumeration process, unlocking the gatekeeper server database

ovoid AgeEndPoints()
Process all registered endpoints and remove them if they are too old

o Call Operations

ovirtual BOOL OnAdmission( H323RegisteredEndPoint & ep, const H225_AdmissionRequest & arq, H225_AdmissionConfirm & acf, H225_AdmissionReject & arj )
Handle an admission ARQ PDU. The default behaviour verifies that the call is allowed by the policies the gatekeeper server requires, then attempts to look up the required signal address for the call. It also manages bandwidth allocations.

ovirtual BOOL OnDisengage( H323RegisteredEndPoint & ep, const H225_DisengageRequest & drq, H225_DisengageConfirm & dcf, H225_DisengageReject & drj )
Handle a disengage DRQ PDU. The default behaviour finds the call by its id provided in the DRQ and removes it from the gatekeeper server database.

ovirtual BOOL OnBandwidth( H323RegisteredEndPoint & ep, const H225_BandwidthRequest & brq, H225_BandwidthConfirm & bcf, H225_BandwidthReject & brj )
Handle a bandwidth BRQ PDU. The default behaviour adjusts the bandwidth used by the gatekeeper and adjusts the remote endpoit according to those limits.

ovirtual void AddCall( H323GatekeeperCall * call )
Add a new call to the server database. Once the call has been added it is then owned by the server and will be deleted when it is removed.

The user woiuld not usually use this function as it is used internally by the server when new registration requests (RRQ) are received.

ovirtual void RemoveCall( H323GatekeeperCall * call )
Remove a call from the server database

ovirtual H323GatekeeperCall* CreateCall( H323RegisteredEndPoint & endpoint, const OpalGloballyUniqueID & callIdentifier )
Create a new call object. The user woiuld not usually use this function as it is used internally by the server when new calls (ARQ) are made.

However, a user may override this function to create objects that are user defined descendants of H323GatekeeperCall so the user can maintain extra information on a call by call basis.

Parameters:
endpoint - Local endpoint

ovirtual H323GatekeeperCall* FindCall( const OpalGloballyUniqueID & callIdentifier )
Find the call given the identifier

o Routing operations

ovirtual BOOL OnLocation( const H225_LocationRequest & lrq, H225_LocationConfirm & lcf, H225_LocationReject & lrj )
Handle a location LRQ PDU. The default behaviour just uses TranslateAliasAddressToSignalAddress to determine the endpoints location.

It is expected that a user would override this function to implement application specified look up algorithms.

ovirtual BOOL TranslateAliasAddressToSignalAddress( const H225_AliasAddress & alias, H323TransportAddress & address )
Translate a given alias to a signal address. This is called by the OnAdmission() handler to fill in the ACF informing the calling endpoint where to actually connect to.

It is expected that a user would override this function to implement application specified look up algorithms.

The default behaviour checks the isGatekeeperRouted and if TRUE simply returns the gatekeepers associated endpoints (not registered endpoint, but real H323EndPoint) listening address.

If isGatekeeperRouted is FALSE then it looks up the registered endpoints by alias and uses the saved signal address in the database.

If the alias is not registered then the address parameter is not changed and the function returns TRUE if it is a valid address, FALSE if it was empty.

o Policy operations

ovirtual BOOL CheckSignalAddressPolicy( const H323RegisteredEndPoint & ep, const H225_AdmissionRequest & arq, const H323TransportAddress & address )
Check the signal address against the security policy. This validates that the specified endpoint is allowed to make a connection to or from the specified signal address.

It is expected that a user would override this function to implement application specified security policy algorithms.

The default behaviour simply returns TRUE.

ovirtual BOOL CheckAliasAddressPolicy( const H323RegisteredEndPoint & ep, const H225_AdmissionRequest & arq, const H225_AliasAddress & alias )
Check the alias address against the security policy. This validates that the specified endpoint is allowed to make a connection to or from the specified alias address.

It is expected that a user would override this function to implement application specified security policy algorithms.

The default behaviour checks the canOnlyAnswerRegisteredEP or canOnlyCallRegisteredEP meber variables depending on if it is an incoming call and if that is TRUE only allows the call to proceed if the alias is also registered with the gatekeeper.

ovirtual BOOL CheckAliasStringPolicy( const H323RegisteredEndPoint & ep, const H225_AdmissionRequest & arq, const PString & alias )
Check the alias address against the security policy. This validates that the specified endpoint is allowed to make a connection to or from the specified simple alias string.

It is expected that a user would override this function to implement application specified security policy algorithms.

The default behaviour checks the canOnlyAnswerRegisteredEP or canOnlyCallRegisteredEP meber variables depending on if it is an incoming call and if that is TRUE only allows the call to proceed if the alias is also registered with the gatekeeper.

ovirtual BOOL GetUsersPassword( const PString & alias, PString & password ) const
Get password for user if H235 security active. Returns FALSE if security active and user not found. Returns TRUE if security active and user is found. Also returns TRUE if security inactive, and the password is always the empty string.

ovirtual unsigned AllocateBandwidth( unsigned newBandwidth, unsigned oldBandwidth = 0 )
Allocate or change the bandwidth being used. This function modifies the total bandwidth used by the all endpoints registered with this gatekeeper. It is called when ARQ or BRQ PDU's are received.

o Access functions

oconst PString& GetGatekeeperIdentifier() const
Get the identifier name for this gatekeeper

ovoid SetGatekeeperIdentifier( const PString & id, BOOL adjustListeners = TRUE )
Set the identifier name for this gatekeeper. If adjustListeners is TRUE then all gatekeeper listeners that are attached to this gatekeeper server have their identifier names changed as well.

ounsigned GetAvailableBandwidth() const
Get the total bandwidth available in 100's of bits per second

ovoid SetAvailableBandwidth(unsigned bps100)
Set the total bandwidth available in 100's of bits per second

ounsigned GetTimeToLive() const
Get the default time to live for new registered endpoints

ovoid SetTimeToLive(unsigned seconds)
Set the default time to live for new registered endpoints


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java



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