dt_casmgmt( )

Description | Caution | Example | Errors

Name:	int dt_casmgmt (devh,cmdmsgp, replymsgp)
Inputs:	int devh	Valid DTI board or time slot device handle
	void *cmdmsgp	Pointer to command message block
	void *replymsgp	Pointer to reply message block buffer
Returns:	0 on success -1 on failure
Includes:	dtilib.h ditcas.h
Category:	I/O
Mode:	synchronous

Description

The dt_casmgmt( ) function is used to manage the CAS DTI templates used for the detection and transmission of signaling patterns with precise time intervals. Timing constraints in signaling protocols may make it very difficult to detect or transmit a signal at the application level and respond quickly. It is also difficult to ensure accurate timing between signal transitions, pulses or trains. This function allows the application to predefine a signal set (a set templates of signal transitions, pulses and/or trains and times to remain at each signal state) in the board's firmware, effectively offloading signal detection and transmission from the host. Signal templates, once created, apply to all channels on a board. Each signal template is enabled or disabled on a per channel basis. The signal detection and transmission characteristics are communicated to the board via the command message blocks describe below.

Each template created for a signal set must have a distinct identifier. The creation and deletion of a template is initiated by a command from the application. The changing of the parameters of a template is done by deleting the old template and adding a new template. Once defined, each template has all channels disabled, and must be enabled or disabled individually for each channel which it is intended. If a template is deleted by the application, all signal matching or transmission for that template on all channels is abandoned and the application will not be notified. If a template is disabled on a specific channel by the application, all signal matching or transmission for that template on that specific channel is abandoned and the application will not be notified.

For signal detection, once a template is enabled on a channel, all incoming signaling changes are matched against the template on that channel. If more than one template is enabled on a channel, incoming signaling changes are matched against all templates on that channel. As soon as all the parameters on a template(s) are matched, an unsolicited event (DTEV_CASTEVT) is sent to the application. The event data contains the identifier of the template that was detected. The firmware will send the event each time a transition, pulse or train of pulses is received and validated.

For signal transmission, once a template is defined and enabled, an application can transmit signals matching that template using a subcommand DTCAS_TRANSMIT_TEMPLATE. The board immediately acknowledges the send command with DTCAS_TRANSMIT_TEMPLATE_COMPLETE. The application receives an unsolicited event (DTEV_CASSENDENDEVT) after send command succeeds.

Signal detection or transmission is terminated when any of the following conditions are satisfied:

• The template is disabled or deleted
• A change in the detected signal is detected

This function operates in the synchronous (blocking) mode, however, signal detection or transmission once enabled, occurs asynchronously. All data structures used for creating a template, deleting a template, enabled a template, disabling a template, detecting a signal, and transmitting a signal are defined in dticas.h.

Parameter	Description
devh	Specifies the valid board or time slot device handle returned by the call to dt_open( ). The type of handle depends on the cmdmsgp argument.
cmdmsgp	Points to the command message block. Descriptions of valid command message blocks are listed in Appendix B - Message Blocks. Although the number of fields and their meaning are different for each command message block, they all contain one or more of the data types described in the Common Data Types section.
replymsgp	Points to the reply message block buffer supplied by the application. If the function returns 0, this buffer is filled with the reply message block. Descriptions of the reply message block expected by each command is listed in Appendix B - Message Blocks. Although the number of fields and their meaning are different for each reply message block, they all contain one or more of the data types described in the Common Data Types section.

WARNING

The application is responsible for allocating a reply message block buffer of sufficient length.

If event handling is set up properly for your application, the sr_getevttype( ) function included in the SRL will return DTEV_CASTEVT, when a signal pattern match occurs and DTEV_CASSENDENDEVT, when signal transmission is complete . The DTEV_CASTEVT and DTEV_CASTSENDENDEVT event blocks are described in Appendix B - Message Blocks.

Although each message block is different, they all contain one or more of the following data types, however, there are three fields that are common to each parameter follows:

Table 4. Common Data Types

template_id	A template identifier which is a two byte quantity with no implicit value or order. It is used to identify the template in recognition events and to select the template in transmission commands. The application is free to use it for any unique identifier. However, it is recommended that the following convention be used: The 2-byte template IDs should consist of the high byte being a protocol number and the low byte being the template "meaning" (1=idle, 2=ring, 3=seize, etc.).
prefixCode	The signal pattern for matching and setting templates. This is a bit pattern that represents the signaling bits, and is used as a building block to specify templates. This parameter is similar to the dt_settssigsim( ) bitmask. The prefixCode can be 0 or a logical OR of one or more of the following values:
	DTB_AON - A signaling bit on   DTB_AOFF - A signaling bit off   DTB_BON - B signaling bit on   DTB_BOFF - B signaling bit off   DTB_CON - C signaling bit on (E-1 only)   DTB_COFF - C signaling bit off (E-1 only)   DTB_DON - D signaling bit on (E-1 only)   DTB_DOFF - D signaling bit off (E-1 only)
	NOTE: It is incorrect to OR ON and OFF states for the same signaling bit, i.e., it is incorrect to OR DTB_AON and DTB_AOFF. The ON state will be the one matched.
prefixInterval	The time interval. Time intervals are specified in units of 1ms, however due to the internal clock mechanism this value may vary _5ms. The maximum value which can be specified is 63 seconds.

Caution

This function will fail under the following conditions:

• An invalid device handle is specified
• Signaling insertion is not enabled - the time slot must be in signaling insertion mode before this function is called. Signaling insertion mode is enabled using the dt_setsigmod( ) function.
• An application initiates a transmit command before the completion of a progressing transmission

Example

#include "stdio.h"  
#include "errno.h"  
#include "srllib.h"  
#include "dtilib.h"  
   
/*  
 * CAS DTI event handler  
 */  
casdti_handler( )  
{  
   int tsdev = sr_getevtdev();  
   int len = sr_getevtlen();  
   long event = sr_getevttype();  
   DTCAS_DETECTED_MSG *dmsgp;  
   
   switch ( event ) {  
      case DTEV_CASTEVT:  
         printf("%s: Signaling completed\n", ATDV_NAMEP(tsdev));  
         dmsgp = (DTCAS_DETECTED_MSG *)sr_getevtdatap();  
         printf("DTEV_CASTEVT detected Template ID = %d\t  
                 Result Code = %d\n",dmsgp->template_id,dmsgp->result);  
         break;  
   
      case DTEV_CASSENDENDEVT:  
         printf("%s: Signal Transmission completed\n", ATDV_NAMEP(tsdev));  
         dmsgp = (DTCAS END_TRANSMIT_MSG *)sr_getevtdatap();  
         printf("DTEV_ CASSENDENDEVT detected Template ID = %d\t  
                 Result Code = %d\n",dmsgp->template_id,dmsgp->result);  
         break;  
   
      default:  
         fprintf(stderr,"%s: EVENT ERROR: Unknown event = 0x%lx\t  
                 Data Length = %d\n",ATDV_NAMEP(tsdev),sr_getevttype(),len);  
         break;  
   }  
   
   return 0;  
}  
main()  
{  
   int   srlmode;  
   int   devh;         /* DTI board device descriptor */  
   int   tsdevh;       /* DTI channel device descriptor */  
   DTCAS_CREATE_PULSE_MSG  
         cpmsg;        /* Pulse template message */  
   DTCAS_REPLY_MSG  
         cpcmsg;       /* Reply buffer for pulse template complete message */  
   DTCAS_ENA_DIS_TEMPLATE_MSG  
         etmsg;        /* Enable template message */  
   DTCAS_REPLY_MSG  
         etcmsg;       /* Reply buffer for enable template complete message */  
   
   /*  
    * Set SRL to run in polled mode.  
    */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE,SR_MODEID,&srlmode) == -1) {  
      fprintf(stderr,"ERROR: Failed to set SRL in SR_POLLMODE\n");  
      exit(1);  
   }  
   
   /*  
    * Open DTI board device.  
    */  
   if ((devh = dt_open("dtiB1",0)) == -1) {  
      fprintf(stderr,"Cannot open dtiB1: error=%d", errno);  
      exit(1);  
   }  
   
   /*  
    * Open DTI board 1, tslot 1.  
    */  
   if ((tsdevh = dt_open("dtiB1T1",0)) == -1) {  
      fprintf(stderr,"Cannot open dtiB1T1: errno=%d", errno);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Using sr_enbhndlr(), set up handler function to handle events  
    * on this device.  
    */  
   if (sr_enbhdlr(tsdevh, DTEV_CASTEVT|DTEV_CASSENDENDEVT,  
 (long(*)())casdti_handler) == -1) {  
      fprintf(stderr,"sr_enbhdlr ERROR %d: %s\n",  
              ATDV_LASTERR(tsdevh),ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Set signaling mode to signaling insertion  
    */  
   if (dt_setsigmod(tsdevh, DTM_SIGINS) == -1) {  
      fprintf(stderr,"dt_setsigmod ERROR %d: %s\n",  
              ATDV_LASTERR(tsdevh),ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Define a pulse using the pulse template message block.  
    */  
   cpmsg.msg_code = DTCAS_CREATE_PULSE;  
   cpmsg.rfu = 0;  
   cpmsg.template_id = 1;  
   cpmsg.OffPulseCode = (DTB_AON|DTB_BOFF);  
   cpmsg.OnPulseCode = (DTB_AOFF|DTB_BON);  
   cpmsg.PrePulseInterval = 0;  
   cpmsg.PrePurseIntervalNom  = 0;  
   cpmsg.PulseIntervalMin     = 120;  
   cpmsg.PulseIntervalNom     = 150;  
   cpmsg.PulseIntervalMax     = 170;  
   cpmsg.PostPulseInterval    = 0;  
   cpmsg.PostPulseIntervalNom = 0;  
   
   /*  
    * Add pulse template to signal set.  
    */  
   if (dt_castmgmt(devh, &cpmsg, &cpcmsg) == -1){  
      fprintf(stderr,"Error Message = %s",ATDV_ERRMSGP(devh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Check if operation was successful.  
    */  
   if (cpcmsg.result != 0) {  
      fprintf(stderr,"Error Message = %s",ATDV_ERRMSGP(devh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Enable template id 1.  
    */  
   etmsg.msg_code = DTCAS_ENABLE_TEMPLATE;  
   etmsg.rfu = 0;  
   etmsg.template_id = 1;  
   
   /*  
    * Enable template.  
    */  
   if (dt_castmgmt(tsdevh, &etmsg, &etcmsg) == -1){  
      printf("Error Message = %s",ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Check if the operation was successful.  
    */  
   if (etcmsg.result != 0) {  
      fprintf(stderr,"Error Message = %s",ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Send Signal for Template ID 1.  
    */  
   etmsg.msg_code = DTCAS_TRANSMIT_TEMPLATE;  
   etmsg.rfu = 0;  
   etmsg.template_id = 1;  
   etmsg.pulse_count = 1;  
   
   /*  
    * Send template.  
    */  
   if (dt_castmgmt(tsdevh, &etmsg, &etcmsg) == -1){  
      printf("Error Message = %s",ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   /*  
    * Check if the operation was successful.  
    */  
   if (etcmsg.result != 0) {  
      fprintf(stderr,"Error Message = %s",ATDV_ERRMSGP(tsdevh));  
      dt_close(tsdevh);  
      dt_close(devh);  
      exit(1);  
   }  
   
   for (;;) {  
      sr_waitevt(-1);  
   }  
}

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error types.

• EDT_BADBRDERR - DTI/2xx missing or defective
• EDT_BADCMDERR - Invalid or undefined command to driver
• EDT_DATTO - Data reception timed out
• EDT_FWERR - Firmware returned an error
• EDT_PARMERR - Invalid parameter
• EDT_RANGEERR - Bad/overlapping physical memory range
• EDT_SIZERR - Message too big or too small
• EDT_SKIPRPLYERR - A required reply was skipped
• EDT_SYSTEM - System error - check the global variable errno for more information about the error
• EDT_TMOERR - Timed out waiting for reply from firmware
• EDT_INVTS - Invalid time slot device handle
• EDT_SIGINS - Signaling insertion not enabled
• EDT_INVMSG - Invalid message

Click here to contact Dialogic Customer Engineering