ms_genringex( )

---

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

Name:	int ms_genringex (devh, len, mode, cadid)
Inputs:	int devh	device handle for station
	unsigned short len	length in cycles for ring
	unsigned short mode	asynchronous/synchronous
	unsigned short cadid	cadence ID for distinctive ring
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 or asynchronous
Platform:	DI, HDSI, Springware

Description

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

A distinctive ring becomes that station's default ring. If you generate a distinctive ring on a station by setting the cadid parameter to a cadence ID, the specified distinctive ring becomes the default ring cadence for that station. Future rings generated either by the ms_genringex( ) function when cadid is set to MS_RNG_DEFAULT or by the ms_genring( ) function will use the default ring cadence. The default ring cadence is either the last distinctive ring that was generated on the station, or if none, the board-level ring cadence as set by the MSG_UDRNGCAD parameter in the ms_setbrdparm( ) function.

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.
cadid	the cadence ID for distinctive ringing. Range: 1 - 8. See ms_setbrdparm( ) MSG_DISTINCTRNG for information on initializing distinctive ring and assigning cadence IDs. Note: The following distinctive rings are not supported on DM3 boards:MS_RNGA_SPLASH3 and MS_RNGA_SPLASH4. Set cadid to MS_RNG_DEFAULT to use the default ring for that station. Rings generated either by the ms_genring( ) function or by ms_genringex( ) function when cadid is set to MS_RNG_DEFAULT will use the default ring cadence of 2 seconds ON, 4 seconds OFF. For MSI boards, you can change the default ring cadence length using the download parameter file, RING.PRM (see the DCM on-line help for more information).

A ring duty cycle includes an on time (ring generation) and off time (no ring). If ms_genringex( ) 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.
• ms_genringex( ) will fail when specifying an invalid cadid or if distinctive ring has not been initialized with the ms_setbrdparm( ) MSG_DISTINCTRNG parameter. The error returned is E_MSBADRNGCAD.
• 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.

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 */
MS_CADENCE cadence;
BYTE       pattern;  
/* 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);
}  
/*
 * Setup distinctive cadence
 */
cadence.cadid = 1; /* First distinctive cadence */
cadence.cadlength = MS_RNGA_CADLEN;
pattern = MS_RNGA_TWOSEC;
cadence.cadpattern = &pattern; /* Pattern (secs) : 2 on 4 off */  
/* Set 1st ring cadence to MS_RNGA_TWOSEC */
if (ms_setbrdparm(devh, MSG_DISTINCTRNG, (void *)&cadence)) == -1){
   printf("Error setting board parameter : %s\n",
           ATDV_ERRMSGP(devh));
   exit(1);
}  
/*
 * Continue processing
 */  
/* Generate ringing using distinctive ring 1 */
if ((rc =ms_genringex(dev1,10,EV_SYNC,1)) == -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 */
MS_CADENCE cadence;
BYTE       pattern;  
/* 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 */
}  
/* Setup distinctive cadence 1 */
cadence.cadid = 1; /* First distinctive cadence */
cadence.cadlength = MS_RNGA_CADLEN;
pattern = MS_RNGA_TWOSEC;
cadence.cadpattern = &pattern; /* Pattern (secs) : 2 on 4 off */  
/* Set 1st ring cadence to MS_RNGA_TWOSEC */
if (ms_setbrdparm(devh, MSG_DISTINCTRNG, (void *)&cadence)) == -1){
   printf("Error setting board parameter : %s\n", ATDV_ERRMSGP(devh));
   exit(1);
}  
/*
 *   Continue processing
 */  
/* Generate asynchronous ringing using distinctive ring 1 */
if ((rc = ms_genringex(dev1,10,EV_ASYNC,1)) == -1) {
    /* process error */
}  
/* Use sr_waitevt to wait for the completion of ms_genring().
   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_genring( )
• ms_genringCallerID( )
• ms_setbrdparm( )
• ms_setevtmsk( )
• ms_stopfn( )

Click here to contact Telecom Support Resources