BOOL UseGatekeeper( const PString & address = PString::Empty(), const PString & identifier = PString::Empty(), const PString & localAddress = PString::Empty() )
- Use and register with an explicit gatekeeper.
This will call other functions according to the following table:
address identifier function
empty empty DiscoverGatekeeper()
non-empty empty SetGatekeeper()
empty non-empty LocateGatekeeper()
non-empty non-empty SetGatekeeperZone()
The localAddress field, if non-empty, indicates the interface on which
to look for the gatekeeper. An empty string is equivalent to "ip$*:*"
which is any interface or port.
If the endpoint is already registered with a gatekeeper that meets
the same criteria then the gatekeeper is not changed, otherwise it is
deleted (with unregistration) and new one created and registered to.
- Parameters:
- address - Address of gatekeeper to use.
identifier - Identifier of gatekeeper to use.
localAddress - Local interface to use.
BOOL SetGatekeeper( const PString & address, H323Transport* transport = NULL )
- Select and register with an explicit gatekeeper.
This will use the specified transport and a string giving a transport
dependent address to locate a specific gatekeeper. The endpoint will
register with that gatekeeper and, if successful, set it as the current
gatekeeper used by this endpoint.
Note the transport being passed in will be deleted by this function or
the H323Gatekeeper object it becomes associated with. Also if transport
is NULL then a H323TransportUDP is created.
- Parameters:
- address - Address of gatekeeper to use.
transport - Transport over which to talk to gatekeeper.
BOOL SetGatekeeperZone( const PString & address, const PString & identifier, H323Transport* transport = NULL )
- Select and register with an explicit gatekeeper and zone.
This will use the specified transport and a string giving a transport
dependent address to locate a specific gatekeeper. The endpoint will
register with that gatekeeper and, if successful, set it as the current
gatekeeper used by this endpoint.
The gatekeeper identifier is set to the spplied parameter to allow the
gatekeeper to either allocate a zone or sub-zone, or refuse to register
if the zones do not match.
Note the transport being passed in will be deleted by this function or
the H323Gatekeeper object it becomes associated with. Also if transport
is NULL then a H323TransportUDP is created.
- Parameters:
- address - Address of gatekeeper to use.
identifier - Identifier of gatekeeper to use.
transport - Transport over which to talk to gatekeeper.
BOOL LocateGatekeeper( const PString & identifier, H323Transport* transport = NULL )
- Locate and select gatekeeper.
This function will use the automatic gatekeeper discovery methods to
locate the gatekeeper on the particular transport that has the specified
gatekeeper identifier name. This is often the "Zone" for the gatekeeper.
Note the transport being passed in will be deleted becomes owned by the
H323Gatekeeper created by this function and will be deleted by it. Also
if transport is NULL then a H323TransportUDP is created.
- Parameters:
- identifier - Identifier of gatekeeper to locate.
transport - Transport over which to talk to gatekeeper.
BOOL DiscoverGatekeeper( H323Transport* transport = NULL )
- Discover and select gatekeeper.
This function will use the automatic gatekeeper discovery methods to
locate the first gatekeeper on a particular transport.
Note the transport being passed in will be deleted becomes owned by the
H323Gatekeeper created by this function and will be deleted by it. Also
if transport is NULL then a H323TransportUDP is created.
- Parameters:
- transport - Transport over which to talk to gatekeeper.
virtual H323Gatekeeper* CreateGatekeeper( H323Transport* transport )
- Create a gatekeeper.
This allows the application writer to have the gatekeeper as a
descendent of the H323Gatekeeper in order to add functionality to the
base capabilities in the library.
The default creates an instance of the H323Gatekeeper class.
- Parameters:
- transport - Transport over which gatekeepers communicates.
H323Gatekeeper* GetGatekeeper() const
- Get the gatekeeper we are registered with
BOOL IsRegisteredWithGatekeeper() const
- Return if endpoint is registered with gatekeeper
BOOL RemoveGatekeeper( int reason = -1 )
- Unregister and delete the gatekeeper we are registered with.
The return value indicates FALSE if there was an error during the
unregistration. However the gatekeeper is still removed and its
instance deleted regardless of this error.
- Parameters:
- reason - Reason for gatekeeper removal
virtual void SetGatekeeperPassword( const PString & password )
- Set the H235 password for the gatekeeper
virtual const PString& GetGatekeeperPassword() const
- Get the H235 password for the gatekeeper
virtual H235Authenticators CreateAuthenticators()
- Create a list of authenticators for gatekeeper
BOOL StartListener( H323Listener* listener )
- Add a listener to the endpoint.
This allows for the automatic creating of incoming call connections. An
application should use OnConnectionEstablished() to monitor when calls
have arrived and been successfully negotiated.
Note if this returns TRUE, then the endpoint is responsible for
deleting the H323Listener listener object. If FALSE is returned then
the object is not deleted and it is up to the caller to release the
memory allocated for the object.
If a listener already exists on the same transport address then it is
ignored, but TRUE is still returned. The caller does not need to delete
the object.
- Parameters:
- listener - Transport dependent listener.
BOOL StartListener( const H323TransportAddress & iface )
- Add a listener to the endpoint.
This allows for the automatic creating of incoming call connections. An
application should use OnConnectionEstablished() to monitor when calls
have arrived and been successfully negotiated.
If a listener already exists on the same address then it is ignored,
but TRUE is still returned.
If the iface string is empty then "*" is assumed which will listen on
the standard TCP port on INADDR_ANY.
- Parameters:
- iface - Address of interface to listen on.
BOOL StartListeners( const H323TransportAddressArray & ifaces )
- Add listeners to the endpoint.
Set the collection of listeners which will allow the automatic
creating of incoming call connections. An application should use
OnConnectionEstablished() to monitor when calls have arrived and been
successfully negotiated.
If a listener already exists on the interface specified in the list
then it is ignored. If a listener does not yet exist a new one is
created and if a listener is running that is not in the list then it
is stopped and removed.
If the array is empty then the string "*" is assumed which will listen
on the standard TCP port on INADDR_ANY.
Returns TRUE if at least one interface was successfully started.
- Parameters:
- ifaces - Interfaces to listen on.
BOOL RemoveListener( H323Listener* listener )
- Remove a listener from the endpoint.
If the listener parameter is NULL then all listeners are removed.
- Parameters:
- listener - Transport dependent listener.
H323TransportAddressArray GetInterfaceAddresses( BOOL excludeLocalHost = TRUE, H323Transport* associatedTransport = NULL )
- Return a list of the transport addresses for all listeners on this endpoint
- Parameters:
- excludeLocalHost - Flag to exclude 127.0.0.1
associatedTransport - Associated transport for precedence and translation
H323Connection* MakeCall( const PString & remoteParty, PString & token, void* userData = NULL )
- Make a call to a remote party. An appropriate transport is determined
from the remoteParty parameter. The general form for this parameter is
[alias@][transport$]host[:port] where the default alias is the same as
the host, the default transport is "ip" and the default port is 1720.
This function returns almost immediately with the call occurring in a
new background thread. Note that the call could be created and cleared
ie OnConnectionCleared is called BEFORE this function returns. It is
guaranteed that the token variable is set before OnConnectionCleared
called.
Note, the returned pointer to the connection is not locked and may be
deleted at any time. This is extremely unlikely immediately after the
function is called, but you should not keep this pointer beyond that
brief time. The the FindConnectionWithLock() function for future
references to the connection object. It is recommended that
MakeCallLocked() be usedin instead.
- Parameters:
- remoteParty - Remote party to call
token - String to receive token for connection
userData - user data to pass to CreateConnection
H323Connection* MakeCall( const PString & remoteParty, H323Transport* transport, PString & token, void* userData = NULL )
- Make a call to a remote party using the specified transport.
The remoteParty may be a hostname, alias or other user name that is to
be passed to the transport, if present.
If the transport parameter is NULL the transport is determined from the
remoteParty description.
This function returns almost immediately with the call occurring in a
new background thread. Note that the call could be created and cleared
ie OnConnectionCleared is called BEFORE this function returns. It is
guaranteed that the token variable is set before OnConnectionCleared
called.
Note, the returned pointer to the connection is not locked and may be
deleted at any time. This is extremely unlikely immediately after the
function is called, but you should not keep this pointer beyond that
brief time. The the FindConnectionWithLock() function for future
references to the connection object. It is recommended that
MakeCallLocked() be usedin instead.
- Parameters:
- remoteParty - Remote party to call
transport - Transport to use for call.
token - String to receive token for connection
userData - user data to pass to CreateConnection
H323Connection* MakeCallLocked( const PString & remoteParty, PString & token, void* userData = NULL, H323Transport* transport = NULL )
- Make a call to a remote party using the specified transport.
The remoteParty may be a hostname, alias or other user name that is to
be passed to the transport, if present.
If the transport parameter is NULL the transport is determined from the
remoteParty description.
This function returns almost immediately with the call occurring in a
new background thread. However the call will not progress very far
- Parameters:
- remoteParty - Remote party to call
token - String to receive token for connection
userData - user data to pass to CreateConnection
transport - Transport to use for call.
virtual H323Connection* SetupTransfer( const PString & token, const PString & callIdentity, const PString & remoteParty, PString & newToken, void* userData = NULL )
- Setup the transfer of an existing call (connection) to a new remote party
using H4502. This sends a Call Transfer Setup Invoke message from the
B-Party (transferred endpoint) to the C-Party (transferred-to endpoint).
If the transport parameter is NULL the transport is determined from the
remoteParty description. The general form for this parameter is
[alias@][transport$]host[:port] where the default alias is the same as
the host, the default transport is "ip" and the default port is 1720.
This function returns almost immediately with the transfer occurring in a
new background thread.
Note, the returned pointer to the connection is not locked and may be
deleted at any time. This is extremely unlikely immediately after the
function is called, but you should not keep this pointer beyond that
brief time. The the FindConnectionWithLock() function for future
references to the connection object.
This function is declared virtual to allow an application to override
the function and get the new call token of the forwarded call.
- Parameters:
- token - Existing connection to be transferred
callIdentity - Call identity of the secondary call (if it exists)
remoteParty - Remote party to transfer the existing call to
newToken - String to receive token for the new connection
userData - user data to pass to CreateConnection
void TransferCall( const PString & token, const PString & remoteParty, const PString & callIdentity = PString::Empty() )
- Initiate the transfer of an existing call (connection) to a new remote
party using H4502. This sends a Call Transfer Initiate Invoke
message from the A-Party (transferring endpoint) to the B-Party
(transferred endpoint).
- Parameters:
- token - Existing connection to be transferred
remoteParty - Remote party to transfer the existing call to
callIdentity - Call Identity of secondary call if present
void ConsultationTransfer( const PString & primaryCallToken, const PString & secondaryCallToken )
- Transfer the call through consultation so the remote party in the
primary call is connected to the called party in the second call
using H4502. This sends a Call Transfer Identify Invoke message
from the A-Party (transferring endpoint) to the C-Party
(transferred-to endpoint).
- Parameters:
- primaryCallToken - Token of primary call
secondaryCallToken - Token of secondary call
void HoldCall( const PString & token, BOOL localHold )
- Place the call on hold, suspending all media channels (H4504)
NOTE: Only Local Hold is implemented so far.
- Parameters:
- token - Existing connection to be transferred
localHold - true for Local Hold, false for Remote Hold
H323Connection* IntrudeCall( const PString & remoteParty, PString & token, unsigned capabilityLevel, void* userData = NULL )
- Initiate Call intrusion
Designed similar to MakeCall function
- Parameters:
- remoteParty - Remote party to intrude call
token - String to receive token for connection
capabilityLevel - Capability level
userData - user data to pass to CreateConnection
BOOL ParsePartyName( const PString & party, PString & alias, H323TransportAddress & address )
- Parse a party address into alias and transport components.
An appropriate transport is determined from the remoteParty parameter.
The general form for this parameter is [alias@][transport$]host[:port]
where the default alias is the same as the host, the default transport
is "ip" and the default port is 1720.
- Parameters:
- party - Party name string.
alias - Parsed alias name
address - Parsed transport address
virtual BOOL ClearCall( const PString & token, H323Connection::CallEndReason reason = H323Connection::EndedByLocalUser )
- Clear a current connection.
This hangs up the connection to a remote endpoint. Note that this function
is asynchronous
- Parameters:
- token - Token for identifying connection
reason - Reason for call clearing
virtual BOOL ClearCallSynchronous( const PString & token, H323Connection::CallEndReason reason = H323Connection::EndedByLocalUser )
- Clear a current connection.
This hangs up the connection to a remote endpoint. Note that these functions
are synchronous
- Parameters:
- token - Token for identifying connection
reason - Reason for call clearing
virtual void ClearAllCalls( H323Connection::CallEndReason reason = H323Connection::EndedByLocalUser, BOOL wait = TRUE )
- Clear all current connections.
This hangs up all the connections to remote endpoints. The wait
parameter is used to wait for all the calls to be cleared and their
memory usage cleaned up before returning. This is typically used in
the destructor for your descendant of H323EndPoint.
- Parameters:
- reason - Reason for call clearing
wait - Flag for wait for calls to e cleared.
virtual BOOL HasConnection( const PString & token )
- Determine if a connection is active.
- Parameters:
- token - Token for identifying connection
H323Connection* FindConnectionWithLock( const PString & token )
- Find a connection that uses the specified token.
This searches the endpoint for the connection that contains the token
as provided by functions such as MakeCall() (as built by the
BuildConnectionToken() function). if not found it will then search for
the string representation of the CallIdentifier for the connection, and
finally try for the string representation of the ConferenceIdentifier.
Note the caller of this function MUSt call the H323Connection::Unlock()
function if this function returns a non-NULL pointer. If it does not
then a deadlock can occur.
- Parameters:
- token - Token to identify connection
PStringList GetAllConnections()
- Get all calls current on the endpoint
virtual BOOL OnIncomingCall( H323Connection & connection, const H323SignalPDU & setupPDU, H323SignalPDU & alertingPDU )
- Call back for incoming call.
This function is called from the OnReceivedSignalSetup() function
before it sends the Alerting PDU. It gives an opportunity for an
application to alter the reply before transmission to the other
endpoint.
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent.
The default behaviour simply returns TRUE.
- Parameters:
- connection - Connection that was established
setupPDU - Received setup PDU
alertingPDU - Alerting PDU to send
virtual BOOL OnCallTransferInitiate( H323Connection & connection, const PString & remoteParty )
- Handle a connection transfer.
This gives the application an opportunity to abort the transfer.
The default behaviour just returns TRUE.
- Parameters:
- connection - Connection to transfer
remoteParty - Party transferring to.
virtual BOOL OnCallTransferIdentify( H323Connection & connection )
- Handle a transfer via consultation.
This gives the transferred-to user an opportunity to abort the transfer.
The default behaviour just returns TRUE.
- Parameters:
- connection - Connection to transfer
virtual H323Connection::AnswerCallResponse OnAnswerCall( H323Connection & connection, const PString & callerName, const H323SignalPDU & setupPDU, H323SignalPDU & connectPDU )
- Call back for answering an incoming call.
This function is called from the OnReceivedSignalSetup() function
before it sends the Connect PDU. It gives an opportunity for an
application to alter the reply before transmission to the other
endpoint.
It also gives an application time to wait for some event before
signalling to the endpoint that the connection is to proceed. For
example the user pressing an "Answer call" button.
If AnswerCallDenied is returned the connection is aborted and a Release
Complete PDU is sent. If AnswerCallNow is returned then the H.323
protocol proceeds. Finally if AnswerCallPending is returned then the
protocol negotiations are paused until the AnsweringCall() function is
called.
The default behaviour simply returns AnswerNow.
- Parameters:
- connection - Connection that was established
callerName - Name of caller
setupPDU - Received setup PDU
connectPDU - Connect PDU to send.
virtual BOOL OnAlerting( H323Connection & connection, const H323SignalPDU & alertingPDU, const PString & user )
- Call back for remote party being alerted.
This function is called from the SendSignalSetup() function after it
receives the optional Alerting PDU from the remote endpoint. That is
when the remote "phone" is "ringing".
If FALSE is returned the connection is aborted and a Release Complete
PDU is sent.
The default behaviour simply returns TRUE.
- Parameters:
- connection - Connection that was established
alertingPDU - Received Alerting PDU
user - Username of remote endpoint
virtual BOOL OnConnectionForwarded( H323Connection & connection, const PString & forwardParty, const H323SignalPDU & pdu )
- A call back function when a connection indicates it is to be forwarded.
An H323 application may handle this call back so it can make
complicated decisions on if the call forward ius to take place. If it
decides to do so it must call MakeCall() and return TRUE.
The default behaviour simply returns FALSE and that the automatic
call forwarding should take place. See ForwardConnection()
- Parameters:
- connection - Connection to be forwarded
forwardParty - Remote party to forward to
pdu - Full PDU initiating forwarding
virtual BOOL ForwardConnection( H323Connection & connection, const PString & forwardParty, const H323SignalPDU & pdu )
- Forward the call using the same token as the specified connection.
Return TRUE if the call is being redirected.
The default behaviour will replace the current call in the endpoints
call list using the same token as the call being redirected. Not that
even though the same token is being used the actual object is
completely mad anew.
- Parameters:
- connection - Connection to be forwarded
forwardParty - Remote party to forward to
pdu - Full PDU initiating forwarding
virtual void OnConnectionEstablished( H323Connection & connection, const PString & token )
- A call back function whenever a connection is established.
This indicates that a connection to a remote endpoint was established
with a control channel and zero or more logical channels.
The default behaviour does nothing.
- Parameters:
- connection - Connection that was established
token - Token for identifying connection
virtual BOOL IsConnectionEstablished( const PString & token )
- Determine if a connection is established.
- Parameters:
- token - Token for identifying connection
virtual void OnConnectionCleared( H323Connection & connection, const PString & token )
- A call back function whenever a connection is broken.
This indicates that a connection to a remote endpoint is no longer
available.
The default behaviour does nothing.
- Parameters:
- connection - Connection that was established
token - Token for identifying connection
static PString BuildConnectionToken( const H323Transport & transport, unsigned callReference, BOOL fromRemote )
- Build a unique token for the connection.
This identifies the call using the Q931 transport host name and the
Q931 call reference number.
- Parameters:
- transport - Transport for connection
callReference - Call reference of Q.931 link
fromRemote - Call reference is from remote endpoint
H323Connection* OnIncomingConnection( H323Transport* transport, H323SignalPDU & setupPDU )
- Handle a new incoming connection.
This will examine the setup PDU and either attach the signalling
transport to an existing connection that has the same Q.931 call
reference, or creates a new connection using CreateConnection().
- Parameters:
- transport - Transport for connection
setupPDU - Setup PDU
virtual H323Connection* CreateConnection( unsigned callReference, void* userData, H323Transport* transport, H323SignalPDU* setupPDU )
- Create a connection that uses the specified call reference.
- Parameters:
- callReference - Call reference to use
userData - user data to pass to CreateConnection
transport - Transport for connection
setupPDU - Setup PDU, NULL if outgoing call
void CleanUpConnections()
- Clean up connections.
This function is called from a background thread and checks for closed
connections to clean up.
This would not normally be called by an application.