ipm_ReceiveDigits( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int ipm_ReceiveDigits(nDeviceHandle, *pDigitInfo, usMode)
Inputs:	int nDeviceHandle	IP Media device handle
	IPM_DIGIT_INFO *pDigitInfo	pointer to digit info structure
	unsigned short usMode	async or sync mode setting
Returns:	0 on success -1 on failure
Includes:	srllib.h ipmlib.h
Category:	I/O
Mode:	asynchronous or synchronous
Platform:	DM/IP, IPT, HMP

Description

The ipm_ReceiveDigits( ) function enables the IP channel to receive digits from the IP network or the TDM bus. The receive operation continues until ipm_Stop( ) is called with the eSTOP_RECEIVE_DIGITS flag set.

Note: Digits are always received asynchronously, even though this function may be called in either asynchronous or synchronous mode. If this function is called synchronously and returns 0, it does not indicate that the digits have been received but that the function was successfully processed by the firmware. The application must enable event reporting and check for the IPMEV_DIGITS_RECEIVED event.

Parameter	Description
nDeviceHandle	handle of the IP Media device
pDigitInfo	pointer to structure that contains digit type, direction, and digits; see IPM_DIGIT_INFO for details. Note that all fields are filled in upon successful function return.
usMode	operation mode. Set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution.

Termination Events

IPMEV_RECEIVE_DIGITS

indicates function was successfully processed but does not indicate digits were received. This event does not return data.

IPMEV_ERROR

indicates the function failed.

Note: IPMEV_DIGITS_RECEIVED is an unsolicited event that may be reported after the ipm_ReceiveDigits( ) function is called either synchronously or asynchronously. An event is reported for each digit that was received. The event data indicates the digit origin via the eIPM_DIGIT_DIRECTION enumeration.

Cautions

• The only supported value for eIPM_DIGIT_DIRECTION is to receive digits from the TDM bus.
• The IPM_DIGIT_INFO struct must have the unNumberOfDigits set to 1.
• The ipm_ReceiveDigits( ) function returns valid data only if the digits are being transmitted in out-of-band mode. For more information on setting DTMF mode, see the IP Media Library API Programming Guide.

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_INTERNAL

Internal error

EIPM_INV_STATE

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

EIPM_SYSTEM

System error

Example

#include <ipmlib.h>
#include <srllib.h>
#include <stdio.h> 
typedef long int(*HDLR)(unsigned long);
void CheckEvent(); 
void main()
{
   int nDeviceHandle;
   IPM_DIGIT_INFO myDigitInfo; 
   // Register event handler function with srl
   sr_enbhdlr( EV_ANYDEV ,EV_ANYEVT ,(HDLR)CheckEvent); 
   /*
   .
   .
    Main Processing 
   .
   .
   .
   */ 
   /*
    Enable an IP device handle, nDeviceHandle, to receive a specified set of digits.
    ASSUMPTION:  A valid nDeviceHandle was obtained from prior call to ipm_Open(). 
   */ 
   myDigitInfo.eDigitType = DIGIT_ALPHA_NUMERIC;
   myDigitInfo.eDigitDirection = DIGIT_TDM; 
   if(ipm_ReceiveDigits(nDeviceHandle, &myDigitInfo, EV_ASYNC) == -1)
   {
      printf("ipm_ReceiveDigits failed for device name = %s with error = %d\n", 
             ATDV_NAMEP(nDeviceHandle), ATDV_LASTERR(nDeviceHandle));
      /*
      .
      .
      Perform Error Processing
      .
      .
      */
   }
   /*
   .
    Continue processing
   .
   */
} 
void CheckEvent()
{ 
   IPM_DIGIT_INFO *pDigitInfo;
   int nDeviceID  = sr_getevtdev();
   int nEventType = sr_getevttype();
   void* pVoid    = sr_getevtdatap(); 
   switch(nEventType)
   {
      /*
      .
      .
      . Other events
      .
      .
      */ 
      //Successful reply to ipm_ReceiveDigits()
      case IPMEV_RECEIVE_DIGITS:
         printf("Received IPMEV_RECEIVE_DIGITS for device = %s\n",
                ATDV_NAMEP(nDeviceID));
         break; 
      //Unsolicited event, retrieve digits
      case IPMEV_DIGITS_RECEIVED:
         printf("Received IPM_DIGITS_RECEIVED for device = %s\n",
                ATDV_NAMEP(nDeviceID));
         pDigitInfo = (IPM_DIGIT_INFO*)pVoid;
         printf("Number of digits = %d, digit=%s on device %s\n",
                pDigitInfo->unNumberOfDigits, pDigitInfo->cDigits,
                ATDV_NAMEP(nDeviceID));
         break; 
     default:
         printf("Received unknown event = %d for device = %s\n",
                nEventType, ATDV_NAMEP(nDeviceID));
         break;
   }
} 

See Also

• ipm_SendDigits( )

Click here to contact Telecom Support Resources