The SetCallStateRecording procedure is called by application software to enable or disable call state recording for the specified phone line. This API procedure should be called before the phone line is used by the application for incoming or outgoing calls.

Call state recording allows VOIP applications to view all call states a phone line progresses through as the call is being connected and terminated. This capability is most useful while developing and debugging your VOIP application.

If your VOIP call fails, all you have to do is enable call state recording and all the state transitions for the phone line will be recorded for the duration of the call. The call state list that is created can be inspected to locate error states that may help you in determining the exact cause of the call failure. This is especially useful if your application asynchronously uses the media engine API.

Call state recording can also be used to show you the call states that a phone line transitions through during normal call operations. This ability can be used as a learning tool to better understand the calls states of the VOIP Media Engine.

The internal call state list for the phone line is initially cleared. Your application code calls the SetCallStateRecording API procedure to enable call state recording for the phone line. During an incoming or outgoing call, all call states are recorded until the phone line transitions back to the "on hook" state. At that time, application software may call the GetNumRecordedCallStates(Int32, Int32%) and GetRecordedCallStates(Int32, array<VoipMediaEngine..::.TELEPHONY_RETURN_VALUE>[]()[]) API procedure to access the recorded call state data. Finally, your application software must call the ClearRecordedCallStates(Int32) API procedure to clear the previously recorded call states.

Caution:
Important Note:

Before the phone line can be used again, application software must call the ClearRecordedCallStates(Int32) API procedure to clear the previously recorded call states. No inconming call will be assigned to the phone line until the ClearRecordedCallStates(Int32) API procedure is called. Likewise, if you attempt to make an outgoing call using a phone line that does not have its call states cleared (from a previous call), you will receive the SipCallStateHistoryMustBeRead error return value from the "Make Call" API procedures.

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetCallStateRecording(
	int PhoneLine,
	bool EnableState
)
Visual Basic (Declaration)
Public Function SetCallStateRecording ( _
	PhoneLine As Integer, _
	EnableState As Boolean _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetCallStateRecording(
	int PhoneLine, 
	bool EnableState
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetCallStateRecording(
	int PhoneLine,
	boolean EnableState
)

Parameters

PhoneLine
Type: System..::.Int32
The zero based phone line to use.
EnableState
Type: System..::.Boolean
Sets the enable state of call state recording.

Return Value

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipInvalidHandle
Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software.

(API return value)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

Remarks

None.

See Also