ms_genring( )

---

Termination Events | Cautions | Errors | Example - Synchronous | Example - Asynchronous | See Also

Name:	int ms_genring (devh, len, mode)
Inputs:	int devh	device handle for station
	unsigned short len	length in cycles for ring
	unsigned short mode	asynchronous/synchronous
Returns:	0 on success for asynchronous >0 on success for synchronous -1 on failure
Includes:	srllib.h dtilib.h msilib.h
Category:	Station
Mode:	synchronous/asynchronous
Platform:	DI, HDSI, Springware

Description

The ms_genring( ) function generates ringing to a station. The function will terminate when the phone goes off-hook or the specified number of rings has been generated. ms_genring( ) is only supported on boards that have ringing capability.

Parameter	Description
devh	the station device handle
len	the number of cycles to ring a station; a maximum value of 255 is allowed
mode	the operation mode For synchronous mode, EV_SYNC must be specified as the third parameter. The function will return only on termination of ringing due to an error, off hook, or completion of ring cycles. For asynchronous mode, EV_ASYNC must be specified as the third parameter. The function will return on initiation of ringing or on error. To get the completion status, a termination event is generated.

This function will use the default ring, which is the last distinctive ring that was generated on the station by the ms_genringex( ) function, or if none, the board-level ring cadence as set by the MSG_UDRNGCAD parameter in the ms_setbrdparm( ) function.

A ring duty cycle includes an on time (ring generation) and off time (no ring). If ms_genring( ) is received by the MSI board during off time, ring generation will be delayed until the on time portion of the duty cycle is reached. This delay can be up to approximately four seconds. We recommend specifying a length, or cycle, of at least two rings to make sure that at least one full ring cycle is generated. If you specify one ring, the phone may not ring.

Note: For MSI/SC boards: When you ring a station, a built-in (non-modifiable) 500 ms ring is "splashed" to the station immediately before its ring cadence begins. The splash may make the beginning of the ring cadence sound slightly different from the rest of the cadence. This ring splash serves as a fast way to produce a ring at the station and, therefore, to reduce the glare window. Otherwise, glare could occur when a ring starts in the off-time (non-ringing) portion of the ring cycle (where there is no notification that the phone is being rung) and a person picks up the (silent) phone expecting to get dial tone and instead is connected with a caller.

Termination Events

When this function is called in asynchronous mode, a return value of 0 indicates that the function was initiated, while a return value of -1 indicates error. The following events may be received:

MSEV_RING

Indicates successful completion of ring operation.

MSEV_NORING

Indicates the ring operation was not successful. The event data for MSEV_NORING is:

• MSMM_RNGOFFHK

  Solicited off hook detected

• MSMM_RNGSTOP

  Ringing stopped by ms_stopfn( )

• MSMM_TERM

  Ringing terminated

When this function is called in synchronous mode, a return value of -1 indicates failure and a positive return value (>0) indicates the reason for termination. Reasons for termination are:

MSMM_RNGOFFHK

Solicited off hook detected

MSMM_RNGSTOP

Ringing stopped by ms_stopfn( )

MSMM_TERM

Ringing terminated

Cautions

• A glare condition occurs when two parties seize the same line for different purposes. If glare occurs in your application, the function returns successfully. However, it is followed by the event MSEV_NORING. The data associated with the event is E_MSBADRNGSTA, indicating that the station was off-hook when the ring was attempted.
• This function fails when:
  • Executed on a station currently off hook. The error returned is E_MSBADRNGSTA.
  • The MSI board does not support ringing capabilities
  • The device handle is invalid

Errors

If this function returns -1 to indicate failure, obtain the reason for the error by calling the SRL standard attribute function ATDV_LASTERR( ) or ATDV_ERRMSGP( ) to retrieve either the error code or a pointer to the error description, respectively.

Refer to the error type tables found in Chapter 5, "Error Codes". Error defines can be found in dtilib.h or msilib.h.

Example - Synchronous

#include <windows.h>         /* For Windows applications only */
#include <errno.h>
#include "srllib.h"
#include "dtilib.h"
#include "msilib.h"  
int  dev1;                   /* Station device descriptor */
int  rc;                     /* Return code */  
/* Open board 1, station 1 device */
if ((dev1 = ms_open("msiB1C1",0)) == -1) {
    printf( "Cannot open MSIBC11, station 1,channel 1: errno=%d", errno);
    exit(1);
}  
/*
 * Continue processing
 */
/* Generate ringing for 10 cycles in sync mode*/
if ((rc =ms_genring(dev1,10,EV_SYNC)) == -1) {
    /* process error */
}  
/* If timeout, process the condition */
if (rc=MSMM_TERM) {
    printf("Station not responding");
}  
/*
 * Continue Processing
 */  
 /* Done processing - close device */
if (ms_close(dev1) == -1) {
    printf("Cannot close device msiB1C1. errno = %d", errno);
    exit(1);
}  

Example - Asynchronous

#include <windows.h>         /* For Windows applications only */
#include <errno.h>
#include "srllib.h"
#include "dtilib.h"
#include "msilib.h"  
int  dev1;                   /* Station dev descriptor */
int  srlmode;                /* SRL mode indicator */  
/* Open board 1, station 1 device */
if ((dev1 = ms_open("msiB1C1",0)) == -1) {
    printf( "Cannot open MSIB1C1, station 1,channel 1: errno=%d", errno);
    exit(1);
}  
/* Set up handler function to handle play completion */
if (sr_enbhdlr(dev1,MSEV_RING,sig_hdlr) == -1) {
      /* process error */
}  
/*
 * Continue processing
 */
/* Generate ringing */
if (ms_genring(dev1,10,EV_ASYNC) == -1) {
    printf("Error could not set up ringing. Errno = %d", errno);
    exit(1);
}  
/* On receiving the completion event, MSEV_RING, control is
   transferred to the handler function previously established
   using sr_enbhdlr().
*/  
/*
 *   Continue Processing
 */  
 /* Done processing - close device */
if (ms_close(dev1) == -1) {
    printf("Cannot close device msiB1C1. errno = %d", errno);
    exit(1);
}  
/*
 * Continue processing
 */  
int sig_hdlr()
{
   int   dev = sr_getevtdev();
   unsigned short *sigtype = (unsigned short *)sr_getevtdatap();  
   if (sigtype != NULL) {
      switch (*sigtype) {
      case MSMM_TERM:
          printf("Station does not answer");
          return 0;  
      case MSMM_RNGOFFHK:
          printf("Station offhook detected\n");
          return 0;  
      default:
          return 1;
      }
   }  
   /*
    * Continue processing
    */  
} 

See Also

• ms_genringCallerID( )
• ms_genringex( )
• ms_setbrdparm( )
• ms_setevtmsk( )
• ms_stopfn( )

Click here to contact Telecom Support Resources