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

pbxSystem	The name or IP address of the PBX system.
port	The 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

sessionObject	The session object for the PBX that generated the asynchronous message.
asyncData	The 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

sessionObject	The session object for the PBX that sent a packet that triggered an exception condition.
exception	The 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

threadContext The 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

sessionObject The 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

threadContext The 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

message	An encoded ACSE Make Association or Release Association message.
messageLength	The length of the encoded message.
messageType	A constant telling whether the message is an ACSE Make Association or an ACSE Release Association.
threadContext	The 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

message	Byte array containing the encoded message to send.
messageLength	The length of the encoded message.
threadContext	The 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

messageType	A string token to help identify the message in the CSTADLL log file.
message	Byte array containing the encoded message to send.
messageLength	The length of the encoded message.
threadContext	The thread context object.

◆ SendXMLMessage() [1/2]

void SendXMLMessage	(	string	strMessage,
		CSTAContext	threadContext
	)

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

Parameters

strMessage	The XML message to send.
threadContext	The thread context object.

Referenced by GenericXMLed3.AcceptCall(), GenericXMLed3.AnswerCall(), GenericXMLed3.ClearConnection(), GenericXMLed3.ClearDoNotDisturb(), GenericXMLed3.ClearForwarding(), GenericXMLed3.ClearMessageWaiting(), GenericXMLed3.ConferenceCall(), GenericXMLed3.ConsultationCall(), GenericXMLed3.GetAgentState(), GenericXMLed3.GetDoNotDisturb(), GenericXMLed3.GetLogicalDevInfo(), GenericXMLed3.GetPhysicalDevInfo(), GenericXMLed3.GetSFDevices(), GenericXMLed3.HoldCall(), GenericXMLed3.MakeCall(), GenericXMLed3.MonitorStart(), GenericXMLed3.MonitorStop(), GenericXMLed3.MonitorStopAtDevice(), GenericXMLed3.RequestSystemStatus(), GenericXMLed3.RetrieveCall(), GenericXMLed3.RingDevice(), GenericXMLed3.SendData(), GenericXMLed3.SendStoredCDR(), GenericXMLed3.SetAgentState(), GenericXMLed3.SetDisplay(), GenericXMLed3.SetDoNotDisturb(), GenericXMLed3.SetForwarding(), GenericXMLed3.SetMessageWaiting(), GenericXMLed3.SingleStepTransfer(), GenericXMLed3.SnapshotCall(), GenericXMLed3.SnapshotDevice(), GenericXMLed3.StartCDRTransmission(), GenericXMLed3.StartDataPath(), GenericXMLed3.StopCDRTransmission(), GenericXMLed3.StopDataPath(), GenericXMLed3.StopRing(), and GenericXMLed3.TransferCall().

◆ SendXMLMessage() [2/2]

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

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

Parameters

messageType	A string token to help identify the message in the CSTADLL log file.
strMessage	The XML message to send.
threadContext	The 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

strMessage	The text of the XML message to send.
enmMessageType	A constant indicating what kind of session management message is being sent.
threadContext	The 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

threadContext The CSTAContext object associated with the calling thread.

◆ WaitForXMLResponse()

void WaitForXMLResponse ( CSTAContext threadContext )

This method waits for a response to an XML CSTA message.

Parameters

threadContext The CSTAContext object associated with the calling thread.

Referenced by GenericXMLed3.AcceptCall(), GenericXMLed3.AnswerCall(), GenericXMLed3.ClearConnection(), GenericXMLed3.ClearDoNotDisturb(), GenericXMLed3.ClearForwarding(), GenericXMLed3.ClearMessageWaiting(), GenericXMLed3.ConferenceCall(), GenericXMLed3.ConsultationCall(), GenericXMLed3.GetAgentState(), GenericXMLed3.GetDoNotDisturb(), GenericXMLed3.GetLogicalDevInfo(), GenericXMLed3.GetPhysicalDevInfo(), GenericXMLed3.GetSFDevices(), GenericXMLed3.HoldCall(), GenericXMLed3.MakeCall(), GenericXMLed3.MonitorStart(), GenericXMLed3.MonitorStop(), GenericXMLed3.MonitorStopAtDevice(), GenericXMLed3.RequestSystemStatus(), GenericXMLed3.RetrieveCall(), GenericXMLed3.RingDevice(), GenericXMLed3.SendData(), GenericXMLed3.SendStoredCDR(), GenericXMLed3.SetAgentState(), GenericXMLed3.SetDisplay(), GenericXMLed3.SetDoNotDisturb(), GenericXMLed3.SetForwarding(), GenericXMLed3.SetMessageWaiting(), GenericXMLed3.SingleStepTransfer(), GenericXMLed3.SnapshotCall(), GenericXMLed3.SnapshotDevice(), GenericXMLed3.StartCDRTransmission(), GenericXMLed3.StartDataPath(), GenericXMLed3.StopCDRTransmission(), GenericXMLed3.StopDataPath(), GenericXMLed3.StopRing(), and GenericXMLed3.TransferCall().

◆ 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

sessionObject	The session object for the PBX or UA that generated the asynchronous message.
message	The 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.

Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ PBXSession()

Member Function Documentation

◆ AsyncCallback()

◆ AsyncExceptionCallback()

◆ Close()

◆ ConnectionCallback()

◆ Open()

◆ SendACSEMessage()

◆ SendMessage() [1/2]

◆ SendMessage() [2/2]

◆ SendXMLMessage() [1/2]

◆ SendXMLMessage() [2/2]

◆ SendXMLSession()

◆ WaitForROSEResponse()

◆ WaitForXMLResponse()

◆ XMLAsyncCallback()

Property Documentation

◆ CallbackInvocationMechanism

◆ CDRCallback

◆ ClientCallback

◆ Connected

◆ ConnectionLostCallback

◆ DebugMode

◆ DiscardOldResponses

◆ ExceptionCallback

◆ MaxReceiveTimeout

◆ MessageEncoding

◆ PBXSystem

◆ Port

◆ SystemStatusCallback

◆ XMLCDRCallback

◆ XMLClientCallback

◆ XMLSystemStatusCallback