ipm_EnableEvents( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int ipm_EnableEvents(nDeviceHandle, *pEvents, unNumOfEvents, usMode)
Inputs:	int nDeviceHandle	IP Media device handle
	eIPM_EVENT *pEvents	specifies events to enable
	unsigned int unNumOfEvents	number of events to enable
	unsigned short usMode	async or sync mode setting
Returns:	0 on success -1 on failure
Includes:	srllib.h ipmlib.h
Category:	System Control
Mode:	asynchronous or synchronous
Platform:	DM/IP, IPT, HMP

Description

The ipm_EnableEvents( ) function enables IP notification events. Some events are used to indicate status, for example, if fax tone has been detected. Other events are used for Quality of Service (QoS) notifications on a particular media channel.

Notification events (solicited events) are different from asynchronous function termination events, such as IPMEV_OPEN, which cannot be disabled. Once notification events are successfully enabled, if any of the specified events occur, the application is notified via SRL event management functions.

Parameter	Description
nDeviceHandle	handle of the IP Media device
pEvents	pointer to enumeration that specifies the events to enable Note: EVT_DTMFDISCARDED is not supported on Intel® NetStructure™ IPT Series boards.EVT_ROUNDTRIPLATENCY is not supported on Intel® NetStructure™ DM/IP Series boards. The eIPM_EVENT data type is an enumeration that defines the following values: EVT_DTMFDISCARDED number of lost DTMF digits since the beginning of the call EVT_LOSTPACKETS percent of lost packets since the beginning of the call EVT_JITTER average jitter since the beginning of the call (in msec) EVT_ROUNDTRIPLATENCY RTP packet latency EVT_FAXTONE fax tone from TDM EVT_RFC2833 RFC 2833 events EVT_T38FAXTONE fax tone message from T.38 UDP packet EVT_T38CALLSTATE T.38 call state events
unNumOfEvents	number of events to enable
usMode	operation mode. Set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution.

Termination Events

IPMEV_EVENT_ENABLED

indicates successful completion, that is, specified events were enabled. This event does not return any data.

IPMEV_ERROR

indicates the function failed.

Cautions

None.

Errors

If the function returns -1 to indicate failure, call ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to return one of the following errors:

EIPM_BADPARM

Invalid parameter

EIPM_EVT_EXIST

Event already enabled

EIPM_EVT_LIST_FULL

Too many events

EIPM_INTERNAL

Internal error

EIPM_INV_EVT

Invalid event

EIPM_INV_STATE

Invalid state. Initial command did not complete before another function call was made.

EIPM_SYSTEM

System error

EIPM_UNSUPPORTED

Function unsupported

Example

#include <stdio.h>
#include <srllib.h>
#include <ipmlib.h> 
typedef long int(*HDLR)(unsigned long);
void CheckEvent(); 
void main()
{
    int nDeviceHandle;
    eIPM_EVENT myEvents[3] ={EVT_DTMFDISCARDED, EVT_LOSTPACKETS, EVT_JITTER};
    // Register event handler function with srl
    sr_enbhdlr( EV_ANYDEV ,EV_ANYEVT ,(HDLR)CheckEvent);
    /*
    .
    .
    Main Processing
    .
    .
    .
    */
    /*
    Need to enable three events for IP device handle, nDeviceHandle.
    ASSUMPTION: A valid nDeviceHandle was obtained from prior call to ipm_Open().
    */
    if(ipm_EnableEvents(nDeviceHandle, myEvents, 3, EV_ASYNC) == -1)
    {
        printf("ipm_EnableEvents failed for device name %s with error = %d\n",
            ATDV_NAMEP(nDeviceHandle), ATDV_LASTERR(nDeviceHandle));
        /*
        .
        .
        Perform Error Processing
        .
        .
        */
    }
    /*
    .
    . Continue Processing
    .
    */
} 
void CheckEvent()
{
    int nEventType = sr_getevttype();
    int nDeviceID = sr_getevtdev();
    switch(nEventType)
    {
        /*
        .
        . List of expected events
        .
        */
        /* Expected reply to ipm_EnableEvents() */
        case IPMEV_EVENT_ENABLED:
            printf("Received IPMEV_EVENT_ENABLED for device = %s\n",
                ATDV_NAMEP(nDeviceID));
            break;
        default:
            printf("Received unknown event = %d for device = %s\n",
                nEventType, ATDV_NAMEP(nDeviceID));
            break;
    }
} 

See Also

• ipm_DisableEvents( )

Click here to contact Telecom Support Resources