You should try to minimize the processing you perform in this event callback procedure. If you perform minimum event processing in this callback, the telephony engine will be able to process calls quickly. Spending too much time in this callback will slow down call session negotiations and call setup completion. If slower call setup is not critical to your application, you can spend as much time as required in this callback.
To allow the telephony engine to perform its tasks as smoothly and as quickly as possible, it is recommended that the PHONE_LINE_NOTIFICATION and GLOBAL_NOTIFICATION event notifications received by your callback be put into a fifo queue. Your application should then have one of its own threads process the fifo event data as appropriate.
|IMPORTANT - Thread Deadlock Information:|
Internally the VOIP Media Engine is fully multi-threaded. The event callback mechanism is non-reentrant. Some media engine API procedures cannot be called from within the main media engine callback procedure. As a general rule: Any API procedure that can generate additional events cannot be called in the "main event handler" when processing the current event. If you call an API procedure that generates additional events while you are executing in the callback procedure, your VOIP application can deadlock. This is by design. Any API procedure that generates events back to your application must be executed by some other thread in your application. Some of the media engine API procedures that will generate events are: MakeCall(String, String, UInt32, Int32, Boolean, UInt32), MakeCallUri(String, Boolean, Int32, Boolean, UInt32), TerminateCall(Int32, Boolean, UInt32), GoOffHook(Int32), AbortIncomingCall(Int32, Int32, String), BusyOutLine(Int32, Boolean), HoldLine(Int32, Boolean), ConferenceLine(Int32, Boolean), TransferLine(String, String, Int32, Int32), TransferLineUri(String, Boolean, Int32), EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) and DisableSipRegisterServer()()().
|If your application registers the same callback procedure with multiple instances of the telephony engine, you should use a critical section object to manage access to the callback procedure's code/data. Each instance of the telephony engine will execute your callback procedure using a differed thread context.|
Assembly: LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700
public delegate void SIPCALLBACKPROC( VoipMediaEngine..::.SIP_NOTIFY_TYPE NotifyType, int PhoneLine, VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TelephonyEvent, Object UserDefinedData, Object EventData )
|Visual Basic (Declaration)|
Public Delegate Sub SIPCALLBACKPROC ( _ NotifyType As VoipMediaEngine..::.SIP_NOTIFY_TYPE, _ PhoneLine As Integer, _ TelephonyEvent As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE, _ UserDefinedData As Object, _ EventData As Object _ )
public delegate void SIPCALLBACKPROC( VoipMediaEngine..::.SIP_NOTIFY_TYPE NotifyType, int PhoneLine, VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TelephonyEvent, Object^ UserDefinedData, Object^ EventData )
/** @delegate */ public delegate void SIPCALLBACKPROC( VoipMediaEngine..::.SIP_NOTIFY_TYPE NotifyType, int PhoneLine, VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TelephonyEvent, Object UserDefinedData, Object EventData )
- Type: LanScape..::.VoipMediaEngine..::.SIP_NOTIFY_TYPE
When your delegate is called by the media engine, this parameter will be set to the notify type. For further information, see the VoipMediaEngine..::.SIP_NOTIFY_TYPE class.
- Type: System..::.Int32
If the NotificationType parameter has a value of PHONE_LINE_NOTIFICATION, this parameter will be the zero based phone line the event is associated with. If the NotificationType parameter has a value of GLOBAL_NOTIFICATION, this parameter does not apply and will always have a value of -1 (undefined). If the NotificationType parameter has a value of IMMEDIATE_NOTIFICATION, this parameter will have a value of -1 (undefined) or will be the zero based phone line the event is associated with.
- Type: LanScape..::.VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
The telephony event. For a complete list of return types and event types, see VoipMediaEngine..::.TELEPHONY_RETURN_VALUE.
- Type: System..::.Object
User specified data. This parameter corresponds to the UserDefinedData member of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS class.
- Type: System..::.Object
Depending on the event the media engine is sending to your application, this parameter may contain a reference to an object that includes additional information associated with the event.
Note: Data that this parameter references is only available and valid at the time of the event. This parameter value is valid during IMMEDIATE_NOTIFICATION events and is NULL for all other event classes. For further details, see the information on Immediate Events in the Software Developer's Reference.