class H323GatekeeperServer

This class implements a basic gatekeeper server functionality.

Inheritance:


Public Methods

[more] Construction
[more] Protocol Handler Operations
[more] EndPoint Operations
[more] Call Operations
[more] Routing operations
[more] Policy operations
[more] Security and authentication functions
[more] H.323 Annex G Peer Element support
[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 this 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 ~H323GatekeeperServer()
Destroy gatekeeper

o Protocol Handler Operations

ovirtual H323Transactor* CreateListener( H323Transport* transport )
Create a new H323GatkeeperListener. 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.

o EndPoint Operations

ovirtual H323GatekeeperRequest::Response OnDiscovery( H323GatekeeperGRQ & request )
Handle a discovery GRQ PDU. The default behaviour deals with the authentication scheme nogotiation.

ovirtual H323GatekeeperRequest::Response OnRegistration( H323GatekeeperRRQ & request )
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 H323GatekeeperRequest::Response OnUnregistration( H323GatekeeperURQ & request )
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 H323GatekeeperRequest::Response OnInfoResponse( H323GatekeeperIRR & request )
Handle an info request response IRR PDU. The default behaviour calls the function of the same name in the endpoint instance.

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 BOOL RemoveEndPoint( H323RegisteredEndPoint* ep )
Remove a registered endpoint from the server database

ovirtual H323RegisteredEndPoint* CreateRegisteredEndPoint( H323GatekeeperRRQ & request )
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 PSafePtr<H323RegisteredEndPoint> FindEndPointByIdentifier( const PString & identifier, PSafetyMode mode = PSafeReference )
Find a registered endpoint given its endpoint identifier

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointBySignalAddresses( const H225_ArrayOf_TransportAddress & addresses, PSafetyMode mode = PSafeReference )
Find a registered endpoint given a list of signal addresses

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointBySignalAddress( const H323TransportAddress & address, PSafetyMode mode = PSafeReference )
Find a registered endpoint given its signal address

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointByAliasAddress( const H225_AliasAddress & alias, PSafetyMode mode = PSafeReadWrite )
Find a registered endpoint given its raw alias address

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointByAliasString( const PString & alias, PSafetyMode mode = PSafeReference )
Find a registered endpoint given its simple alias string

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointByPartialAlias( const PString & alias, PSafetyMode mode = PSafeReference )
Find the first registered endpoint given a partial alias string

ovirtual PSafePtr<H323RegisteredEndPoint> FindEndPointByPrefixString( const PString & prefix, PSafetyMode mode = PSafeReference )
Find the first registered endpoint given a number prefix string

oPSafePtr<H323RegisteredEndPoint> GetFirstEndPoint( PSafetyMode mode = PSafeReference )
Get first endpoint for enumeration

o Call Operations

ovirtual H323GatekeeperRequest::Response OnAdmission( H323GatekeeperARQ & request )
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 H323GatekeeperRequest::Response OnDisengage( H323GatekeeperDRQ & request )
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 H323GatekeeperRequest::Response OnBandwidth( H323GatekeeperBRQ & request )
Handle a bandwidth BRQ PDU. The default behaviour finds the call and does some checks then calls the H323GatekeeperCall function of the same name.

ovirtual H323GatekeeperCall* CreateCall( const OpalGloballyUniqueID & callIdentifier, H323GatekeeperCall::Direction direction )
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.

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

ovirtual PSafePtr<H323GatekeeperCall> FindCall( const PString & description, PSafetyMode mode = PSafeReference )
Find the call given the identifier

ovirtual PSafePtr<H323GatekeeperCall> FindCall( const OpalGloballyUniqueID & callIdentifier, BOOL answeringCall, PSafetyMode mode = PSafeReference )
Find the call given the identifier

ovirtual PSafePtr<H323GatekeeperCall> FindCall( const OpalGloballyUniqueID & callIdentifier, H323GatekeeperCall::Direction direction, PSafetyMode mode = PSafeReference )
Find the call given the identifier

oPSafePtr<H323GatekeeperCall> GetFirstCall( PSafetyMode mode = PSafeReference )
Get first endpoint for enumeration

o Routing operations

ovirtual H323GatekeeperRequest::Response OnLocation( H323GatekeeperLRQ & request )
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 TranslateAliasAddress( const H225_AliasAddress & alias, H225_ArrayOf_AliasAddress & aliases, H323TransportAddress & address )
Translate a given alias to an alias set and signal address. This is called by the OnAdmission() handler to fill in the ACF or OnLocation() to fill the LCF 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 calls TranslateAliasAddressToSignalAddress().

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 or OnLocation() to fill the LCF 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 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 Security and authentication functions

ovirtual BOOL GetAdmissionRequestAuthentication( H323GatekeeperARQ & info, H235Authenticators & authenticators )
Get separate H235 authentication for the connection. This allows an individual ARQ to override the authentical credentials used in H.235 based RAS for this particular connection.

A return value of FALSE indicates to use the default credentials of the endpoint, while TRUE indicates that new credentials are to be used.

The default behavour does nothing and returns FALSE.

Parameters:
info - ARQ being constructed
authenticators - New authenticators for ARQ

ovirtual BOOL GetUsersPassword( const PString & alias, PString & password ) const
Get password for user if H235 security active. Returns TRUE if user is found and password returned. Note the password may be empty in which case the user was found but explicitly ddoes not require security, possibly overriding the requireH235 flag.

o H.323 Annex G Peer Element support

oH323PeerElement* GetPeerElement() const
Get the associated peer element for the gatekeeper

ovoid SetPeerElement( H323PeerElement* newPeerElement )
Set the associated peer element for the gatekeeper. The existing peer element is automatically deleted.

ovoid CreatePeerElement( const H323TransportAddress & h501Interface )
Create an associated peer element for the gatekeeper. The existing peer element is checked to be listening on the same interface as specified and if it is not it is changed to the specified address.

oBOOL OpenPeerElement( const H323TransportAddress & remotePeer, BOOL append = FALSE, BOOL keepTrying = TRUE )
Create a new Peer Element and establish a service relationship. If append is FALSE, the existing peer element is automatically deleted and recreated. If append is TRUE then a new service relationship is added to the existing peer element.

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 GetUsedBandwidth() const
Get the total bandwidth used in 100's of bits per second

ounsigned GetDefaultBandwidth() const
Get the default bandwidth for calls

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

ounsigned GetInfoResponseRate() const
Get the default time for monitoring calls via IRR

ovoid SetInfoResponseRate(unsigned seconds)
Set the default time for monitoring calls via IRR

oBOOL IsGatekeeperRouted() const
Get flag for is gatekeeper routed

oBOOL IsRequiredH235() const
Get flag for if H235 authentication is required

ounsigned GetActiveRegistrations() const
Get the currently active registration count

ounsigned GetPeakRegistrations() const
Get the peak registration count

ounsigned GetTotalRegistrations() const
Get the total registrations since start up

ounsigned GetRejectedRegistrations() const
Get the total registrations rejected since start up

ounsigned GetActiveCalls() const
Get the currently active call count

ounsigned GetPeakCalls() const
Get the peak calls count

ounsigned GetTotalCalls() const
Get the total calls since start up

ounsigned GetRejectedCalls() const
Get the total calls rejected since start up


This class has no child classes.
Friends:
class H323GatekeeperRRQ
class H323GatekeeperARQ

Alphabetic index HTML hierarchy of classes or Java



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