CSTADLL  2.5.0
Public Member Functions | Properties | List of all members
PBXSession Class Reference

Public Member Functions

delegate void AsyncCallback (PBXSession sessionObject, byte[] asyncData)
 
delegate void AsyncExceptionCallback (PBXSession sessionObject, ApplicationException exception)
 
void Close (CSTAContext threadContext)
 
delegate void ConnectionCallback (PBXSession sessionObject)
 
void Open (CSTAContext threadContext)
 
 PBXSession (string pbxSystem, int port)
 
SocketState SendACSEMessage (byte[] message, int messageLength, Constants.ACSEMessageTypes messageType, CSTAContext threadContext)
 
void SendMessage (byte[] message, int messageLength, CSTAContext threadContext)
 
void SendMessage (string messageType, byte[] message, int messageLength, CSTAContext threadContext)
 
void SendXMLMessage (string strMessage, CSTAContext threadContext)
 
void SendXMLMessage (string messageType, string strMessage, CSTAContext threadContext)
 
SocketState SendXMLSession (string strMessage, Constants.XMLSessionMessageTypes enmMessageType, CSTAContext threadContext)
 
void WaitForROSEResponse (CSTAContext threadContext)
 
void WaitForXMLResponse (CSTAContext threadContext)
 
delegate void XMLAsyncCallback (PBXSession sessionObject, string message)
 

Properties

Constants.CallbackInvocationMechanisms CallbackInvocationMechanism [get, set]
 
AsyncCallback CDRCallback [get, set]
 
AsyncCallback ClientCallback [get, set]
 
bool Connected [get, set]
 
ConnectionCallback ConnectionLostCallback [get, set]
 
bool DebugMode [get, set]
 
bool DiscardOldResponses [get, set]
 
AsyncExceptionCallback ExceptionCallback [get, set]
 
int MaxReceiveTimeout [get, set]
 
Constants.Encoding MessageEncoding [get, set]
 
string PBXSystem [get]
 
int Port [get]
 
AsyncCallback SystemStatusCallback [get, set]
 
XMLAsyncCallback XMLCDRCallback [get, set]
 
XMLAsyncCallback XMLClientCallback [get, set]
 
XMLAsyncCallback XMLSystemStatusCallback [get, set]
 

Detailed Description

This class manages communication with a PBX. One instance of this class should be created for each PBX with which a CSTADLL client application needs to exchange CSTA messages.

The CSTA worker classes (e.g., Alcatel4400, PanasonicNCP) hold a reference to a PBXSession object. If the constructor for the worker class that takes a PBX identification and a PBX port is used, a PBXSession object is created. Alternatively, the client application can create a PBXSession instance and pass a reference to the instance to the other worker class constructor signature.

Only one PBXSession instance for a PBX/port combination should be created. The behavior is undefined if multiple PBXSession instances are created for the same PBX and port.

Constructor & Destructor Documentation

◆ PBXSession()

PBXSession ( string  pbxSystem,
int  port 
)

Constructs a PBXSession object.

Parameters
pbxSystemThe name or IP address of the PBX system.
portThe port on the PBX system to which the client is connecting.

Member Function Documentation

◆ AsyncCallback()

delegate void AsyncCallback ( PBXSession  sessionObject,
byte []  asyncData 
)

Declaration of a callback function to be invoked when one of the following messages is received: a monitor event report message, a route message, a CDR Report message, a CDR Notification message, or a system status request.

Parameters
sessionObjectThe session object for the PBX that generated the asynchronous message.
asyncDataThe data received asynchronously from the PBX.

◆ AsyncExceptionCallback()

delegate void AsyncExceptionCallback ( PBXSession  sessionObject,
ApplicationException  exception 
)

Declaration of a callback function to be invoked if a condition is encountered in the asynchronous I/O handler that would otherwise result in an exception being thrown. Note that in a couple of cases the asynchronous code will still throw an exception, even if this callback is defined.

Parameters
sessionObjectThe session object for the PBX that sent a packet that triggered an exception condition.
exceptionThe ApplicationException object that would have been thrown in the asynchronous I/O handling code if this callback were not defined.

◆ Close()

void Close ( CSTAContext  threadContext)

Terminates the session to the PBX. This method can be used to terminate sessions with PBX devices that don't accept ACSE release association requests.

Parameters
threadContextThe context object for the caling thread.

References SocketState.ReadBuffer, and SocketState.TotalLength.

Referenced by GenericXMLed3.StartSession(), and GenericXMLed3.StopSession().

◆ ConnectionCallback()

delegate void ConnectionCallback ( PBXSession  sessionObject)

Declaration of a callback function to be invoked if the connection to the PBX is lost.

Parameters
sessionObjectThe session object for the PBX whose connection was lost.

◆ Open()

void Open ( CSTAContext  threadContext)

This method can be used to establish communication with a PBX device before any messages are actually sent to the device. TCP/IP connectivity is established and an asynchronous read is started to receive messages sent from the PBX.

Parameters
threadContextThe thread context object.

References SocketState.ReadBuffer, and SocketState.TotalLength.

◆ SendACSEMessage()

SocketState SendACSEMessage ( byte []  message,
int  messageLength,
Constants.ACSEMessageTypes  messageType,
CSTAContext  threadContext 
)

This method sends an ACSE message (either Make Association or Release Association) to the PBX and receives the response. This operation is done synchronously. If the Make Association needs to be done (usually it does), it must be done before any threads for sending and receiving CSTA messages are started.

This method is only intended to be used by client code that encodes its own ACSEMakeAssociation or ACSEReleaseAssociation message. Most clients can probably use the MakeACSEAssociation() and ReleaseACSEAssociation() methods that are in each phase's helper classes.

Parameters
messageAn encoded ACSE Make Association or Release Association message.
messageLengthThe length of the encoded message.
messageTypeA constant telling whether the message is an ACSE Make Association or an ACSE Release Association.
threadContextThe thread context object.
Returns
A populated SocketState instance.

References SocketState.ReadBuffer, and SocketState.TotalLength.

◆ SendMessage() [1/2]

void SendMessage ( byte []  message,
int  messageLength,
CSTAContext  threadContext 
)

This method sends a message to the PBX using TCP/IP.

Parameters
messageByte array containing the encoded message to send.
messageLengthThe length of the encoded message.
threadContextThe thread context object.

◆ SendMessage() [2/2]

void SendMessage ( string  messageType,
byte []  message,
int  messageLength,
CSTAContext  threadContext 
)

This method sends a message to the PBX using TCP/IP.

Parameters
messageTypeA string token to help identify the message in the CSTADLL log file.
messageByte array containing the encoded message to send.
messageLengthThe length of the encoded message.
threadContextThe thread context object.

◆ SendXMLMessage() [1/2]

void SendXMLMessage ( string  strMessage,
CSTAContext  threadContext 
)

◆ SendXMLMessage() [2/2]

void SendXMLMessage ( string  messageType,
string  strMessage,
CSTAContext  threadContext 
)

This method sends an XML message to the PBX using TCP/IP.

Parameters
messageTypeA string token to help identify the message in the CSTADLL log file.
strMessageThe XML message to send.
threadContextThe thread context object.

References uaSIPInvite.CallId, uaSIPInvite.Contact, uaSIPInvite.From, uaSIPInvite.InviteTarget, uaSIPInvite.MaxForwards, SocketState.ReadBuffer, SocketState.TotalLength, and uaSIPInvite.Via.

◆ SendXMLSession()

SocketState SendXMLSession ( string  strMessage,
Constants.XMLSessionMessageTypes  enmMessageType,
CSTAContext  threadContext 
)

This method sends an XML session management (ECMA-354) message to the PBX.

Parameters
strMessageThe text of the XML message to send.
enmMessageTypeA constant indicating what kind of session management message is being sent.
threadContextThe thread context object.
Returns
A populated SocketState instance if the message is a StartSession message. Null if the message is StopSession or ResetSession.

References SocketState.ReadBuffer, and SocketState.TotalLength.

Referenced by GenericXMLed3.EncodeSetOrClearFwdRequest(), GenericXMLed3.StartSession(), and GenericXMLed3.StopSession().

◆ WaitForROSEResponse()

void WaitForROSEResponse ( CSTAContext  threadContext)

This method waits for a response to a CSTA message sent with a ROSE header.

Parameters
threadContextThe CSTAContext object associated with the calling thread.

◆ WaitForXMLResponse()

void WaitForXMLResponse ( CSTAContext  threadContext)

◆ XMLAsyncCallback()

delegate void XMLAsyncCallback ( PBXSession  sessionObject,
string  message 
)

Declaration of a callback function to be invoked when an asynchronous XML monitor event or route messae is received.

Parameters
sessionObjectThe session object for the PBX or UA that generated the asynchronous message.
messageThe text of the message received asynchronously from the PBX or UA.

Property Documentation

◆ CallbackInvocationMechanism

Constants.CallbackInvocationMechanisms CallbackInvocationMechanism
getset

Indicates what asynchronous callback invocation mechanism to use. See the documentation on Constants.CallbackInvocationMechanisms for a detailed description of the possible options.

◆ CDRCallback

AsyncCallback CDRCallback
getset

Holds a reference to an asynchronous callback function that will be invoked when CDR information is received asynchronously. This information could take the form of a CDR Report message or a CDR Notification message. If the latter, the application should use the SendStoredCDR() method to request the stored CDRs from the PBX.

◆ ClientCallback

AsyncCallback ClientCallback
getset

Holds a reference to an asynchronous callback function. This function will be invoked if a monitor event or route message is received asynchronously from the PBX.

◆ Connected

bool Connected
getset

Indicates whether the session to the PBX is connected.

◆ ConnectionLostCallback

ConnectionCallback ConnectionLostCallback
getset

Holds a reference to an asynchronous callback function. This function will be invoked if the connection to the PBX is lost.

◆ DebugMode

bool DebugMode
getset

Enables behavior that facilitates debugging of the CSTADLL software. This property is most likely useful only to Objective Systems staff.

◆ DiscardOldResponses

bool DiscardOldResponses
getset

Indicates whether responses to messages that arrive after the timeout indicated by MaxReceiveTimeout should be discarded. Such a scenario might happen if the exception thrown when the timeout occurs simply causes a thread to terminate, and that termination isn't detected.

◆ ExceptionCallback

AsyncExceptionCallback ExceptionCallback
getset

Holds a reference to an asynchronous callback function. This function will be invoked if a condition occurs in the asynchronous I/O handler that otherwise would have resulted in an exception being thrown if this callback were not defined. Note that in a couple of cases the asynchronous code will still throw an exception, even if this callback is defined.

◆ MaxReceiveTimeout

int MaxReceiveTimeout
getset

Specifies the amount of time, in milliseconds, to wait for a respone to arrive from the PBX. The default value is 5,000 milliseconds (5 seconds).

◆ MessageEncoding

Constants.Encoding MessageEncoding
getset

Indicates how messages exchanges with this PBX are encoded.

Referenced by GenericXMLed3.GenericXMLed3().

◆ PBXSystem

string PBXSystem
get

The TCIP/IP address or well-known name of the PBX.

◆ Port

int Port
get

The port where the PBX listens for CSTA messages.

◆ SystemStatusCallback

AsyncCallback SystemStatusCallback
getset

Holds a reference to an asynchronous callback function. This function will be invoked if a BER System Status message is received asynchronously from the PBX. The client application does NOT need to send a System Status Response, since that is taken care of by CSTADLL.

◆ XMLCDRCallback

XMLAsyncCallback XMLCDRCallback
getset

Holds a reference to an asynchronous callback function that will be invoked when XML CDR information is received asynchronously.

This information could take the form of a CDR Report message or a CDR Notification message. If the latter, the application should use the SendStoredCDR() method to request the stored CDRs from the PBX or UA.

◆ XMLClientCallback

XMLAsyncCallback XMLClientCallback
getset

Holds a reference to an asynchronous XML callback function. This function will be invoked if an XML monitor event report message or route message is received asynchronously from the PBX or UA.

◆ XMLSystemStatusCallback

XMLAsyncCallback XMLSystemStatusCallback
getset

Holds a reference to an asynchronous callback function. This function will be invoked if an XML System Status message is received asynchronously from the PBX. The client application does NOT need to send a System Status Response, since that is taken care of by CSTADLL.