Event Handlers

SK400VOP uses callbacks to exchange asynchronous events between the signaling module and the application. A call context accompanies call-related events so the application can correlate events when multiple calls are active.

For normal outgoing-call creation, use ippStartCall(). After that call, the application should process call progress and state changes through the event callback.

Header is authoritative. Event identifiers can vary between SK400VOP releases. Use the constants declared by the headers supplied with your licensed build when an identifier in application code differs from this reference.

Application event-handler callback

The application implements EVENT_HANDLER_CB to receive asynchronous events from the signaling module.

Include

#include "ippapi.h"

Prototype

typedef void (*EVENT_HANDLER_CB)(
    void *iface,
    UInt32 event,
    UInt32 context,
    void *args
);

Parameters

Name	Description
iface	Interface pointer supplied by the signaling module. It provides the application with the signaling event interface used for follow-on actions. Cast it to the interface type defined by the supplied headers before use.
event	Event identifier. Common signaling-to-application events are listed below.
context	Call context associated with the event. Preserve it for subsequent operations on the same call.
args	Optional event-specific argument. Its type and validity depend on event.

Returns

None.

Signaling events delivered to the application

Event	Arguments	Description
SIG2UI_EV_CALL_ESTABLISHED	None	The call has been established.
SIG2UI_EV_INCOMING_CALL	Caller ID / caller information	A new incoming call has been received.
SIG2UI_EV_ERROR	Event-specific	An error occurred while processing a previous request.
SIG2UI_EV_BUSY	None	The called party or destination reported busy.
SIG2UI_EV_RINGBACK	None	Call setup is in progress and ringback has been reported.
SIG2UI_EV_HANGUP	None	The remote party terminated the call.
SIG2UI_EV_REGISTERED	None	Registration with the configured server completed successfully.
SIG2UI_EV_DEREGISTERED	None	The registration was removed or expired.
SIG2UI_EV_END_SESSION	None	The call session is no longer valid and should be released by the application.
SIG2UI_EV_IM*	Pointer to message data	An incoming instant message was received.

* Older copies of this documentation showed this identifier as SIG2UI_EV__IM. Verify the exact spelling in the ippapi.h supplied with your build before changing existing application code.

Signaling event interface

The signaling module provides an event interface to the application. The interface is passed through the first parameter of the application callback.

A representative declaration is:

typedef struct ipp_interface_t {
    UInt32 (*eventHandler)(UInt32 event, UInt32 *context, void *args);
} IPPInterface, *pIPPInterface;

The exact declaration in the supplied header should be used when compiling an application.

Callback prototype

UInt32 (*eventHandler)(UInt32 event, UInt32 *context, void *args);

Parameters

Name	Description
event	Application-to-signaling event identifier.
context	Pointer to the call context to which the event applies. Some operations may update or consume the context according to the event contract.
args	Optional event-specific argument.

Returns

UInt32. The exact success/error values are defined by the SK400VOP headers and event implementation for the supplied build.

Application events delivered to signaling

Event	Arguments	Description
UI2SIG_EV_NEW	Called number / URI	Requests creation of a new outgoing call. Prefer ippStartCall() for normal application use.
UI2SIG_EV_HANGUP	None	Terminates the call identified by the supplied context.
UI2SIG_EV_ANSWER	None	Accepts an incoming call.
UI2SIG_EV_REJECT	None	Rejects an incoming call.
UI2SIG_EV_START_VOICE	None	Starts media streaming for a newly accepted call.
UI2SIG_EV_HOLD	None	Places the specified call on hold. Media streaming is paused.
UI2SIG_EV_UNHOLD	None	Removes the specified call from hold.
UI2SIG_EV_SEND_DTMF	DTMF-specific argument	Sends a DTMF digit or event for the specified call.
UI2SIG_EV_SEND_IM	Message data	Sends an instant message.

Context-handling rule

Treat the call context as opaque application state owned by the signaling integration contract. Store it with the application's call object and pass it back unchanged unless the specific API or event contract explicitly states otherwise.