SIPCALLBACKPROC

The SIPCALLBACKPROC data type is used by the telephony API to define a callback procedure that is registered with the telephony engine. This callback procedure is specified when application software calls the StartSipTelephony API procedure. This callback procedure is responsible for passing all telephony events back to the application software.

 

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, MakeCallUri, TerminateCall, GoOffHook, AbortIncomingCall, BusyOutLine, HoldLine, ConferenceLine, TransferLine, TransferLineUri, EnableSipRegisterServer and DisableSipRegisterServer.

Note:

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.

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the same handle that was returned when the application software initially called the StartSipTelephony API procedure.

NotificationType

[in] The type of event the telephony engine is sending to the application. For additional information see SIP_NOTIFY_TYPE.

PhoneLine

[in] 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.

TelephonyEvent

[in] The telephony event. For a complete list of return types and event type, see TELEPHONY_RETURN_VALUE

pUserDefinedData

[in] User specified data. This parameter corresponds to the pUserDefinedData member of the START_SIP_TELEPHONY_PARAMS structure.

pEventData

[in] Depending on the event the media engine is sending to your application, this parameter may contain the address of a structure that includes additional information associated with the event. Note: Data that this parameter points to 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.

Return Value:

None.