5.5. Asynchronous with Win32 Synchronization Model

• Asynchronous with Win32 Synchronization Model Advantages
• Asynchronous with Win32 Synchronization Model Programming Notes
• Asynchronous with Win32 Synchronization Model Example

The Asynchronous with Win32 Synchronization model allows an asynchronous application to receive SRL event notification through standard Win32 synchronization mechanisms. The two mechanisms supported are Reset Events and I/O Completion Ports. In this model, the application informs the SRL to signal the specified Reset Event or I/O Completion Point when an event occurs on a Dialogic device. When the application receives notification, it calls standard Dialogic event retrieval functions to process the event.

Choose the Asynchronous with Win32 Synchronization model for an application that needs the tightest possible integration with other Win32 devices.

Asynchronous with Win32 Synchronization Model Advantages

• Because the Asynchronous with Win32 Synchronization model uses one thread for all Dialogic devices, it requires a lower level of system resources than does the Synchronous model; thus, Asynchronous with Win32 Synchronization model allows for greater scalability in growing systems.
• Provides a single point of event synchronization for devices of separate sources, including DM3 devices.
• Minimizes inter-thread communication because all devices can be controlled within a single thread.
• Provides a high level of scalability to multi-processing platforms. This is especially true for I/O Completion Ports.

Asynchronous with Win32 Synchronization Model Programming Notes

For reset events, an application should perform the following operations.

When the application initializes:

1. Use the Win32 CreateEvent( ) function to create the event.
2. Fill in the SRLWIN32INFO structure to indicate that reset events are being used. The dwHandleType field must be set to SR_RESETEVENT. The ObjectHandle field must be set to the event handle returned by the CreateEvent( ) function.
3. Call the sr_setparm( ) function with the parameter number argument set to SR_WIN32INFO.

To wait for event notification:

1. Call the Win32 WaitForSingleObject( ) or WaitForMultipleObjects( ) function. The WaitForMultipleObjects( ) function is most commonly used because the application can wait for event notification from multiple sources.
2. At notification, if the event source is a Dialogic device, call the sr_waitevt( ) function, with a zero timeout, to retrieve the event from the Dialogic event queue. To identify the Dialogic device and event, use the sr_getevtdev( ) and sr_getevttype( ) functions.

For I/O Completion Ports, an application should perform the following operations:

When the application initializes:

1. Use the Win32 CreateIoCompletionPort( ) function to create the Completion Port.
2. Fill in the SRLWIN32INFO structure to indicate that I/O Completion Points are being used. The dwHandleType field must be set to SR_IOCOMPLETIONPORT. The ObjectHandle field contains the Completion Port handle returned by the CreateIoCompletionPort( ) function. The dwUserKey field must be set to the user-specified key that is returned at the time of event notification. The lpOverlapped field may be set to an optional user-specified OVERLAPPED structure.
3. Call the sr_setparm( ) function with the parameter number argument set to SR_WIN32INFO.

To wait for event notification:

1. Call the Win32 GetQueuedCompletionStatus( ) to wait for events from multiple sources, including SRL devices.
2. At notification, if the event source is a Dialogic device, call the sr_waitevt( ) function, with a zero timeout, to retrieve the event from the Dialogic event queue. To identify the Dialogic device and event, use the sr_getevtdev( ) and sr_getevttype( ) functions.

Asynchronous with Win32 Synchronization Model Example

An example of the Asynchronous with Win32 Synchronization model is shown below:

/*  
 * This asynchronous with Win32 synchronization sample application was  
 * designed to work with D/41ESC, VFX/40ESC, LSI/81SC, LSI/161SC and  
 * D/160SC-LS boards only.  It was compiled using MS-VC++.  
 */  
/* C includes */  
#include <stdio.h>  
#include <process.h>  
#include <conio.h>  
#include <ctype.h>  
#include <windows.h>  
/* Dialogic includes */  
#include <srllib.h>  
#include <dxxxlib.h>  
/* Defines */  
#define MAX_CHAN     4 /* maximun number of voice channels in system */  
#define DIALOGIC_KEY      0  /* Index for Dialogic reset event */  
#define KEYBOARD_KEY      1  /* Index for keyboard reset event */  
#define MAX_RESET_EVENTS  2  /* number of reset events */  
/* Globals */  
int Kbhit_flag = 0;  
HANDLE hEvent[MAX_RESET_EVENTS];  
/* Prototypes */  
int main();  
DWORD WINAPI sample_begin(LPVOID);  
/****************************************************************  
*        NAME : int main()  
* DESCRIPTION : create reset events, create thread and  
*             : poll for keyboard input  
*       INPUT : none  
*      OUTPUT : none  
*     RETURNS : 0 on success; 1 if a failure was encountered  
*    CAUTIONS : none  
****************************************************************/  
int main()  
{  
   HANDLE thread_handle;  
   DWORD threadID;  
   DWORD Index;  
   /* show application's title */  
   printf("Async with Win32 Sychronization Sample Application - hit any key to exit...\n");  
   /* create the reset events */  
   for (Index = 0; Index < MAX_RESET_EVENTS; Index++) {  
      hEvent[Index] = CreateEvent((LPSECURITY_ATTRIBUTES)NULL,  
                                   FALSE,  
                                   FALSE,  
                                   NULL);  
   }  
   /* create one thread to process all the voice channels */  
   if ((thread_handle = (HANDLE)_beginthreadex(NULL,  
                                 0,  
                                 sample_begin,  
                                 (LPVOID)NULL,  
                                 0,  
                                 &threadID)) == (HANDLE)-1) {  
         /* Perform system error processing */  
         exit(1);  
   }  
   /* wait for Keyboard input to shutdown program */  
   getch();  
   Kbhit_flag++;  /* let thread know it's time to abort */  
   SetEvent( hEvent[KEYBOARD_KEY] );  
   /* sleep here until thread has terminated */  
   if (WaitForMultipleObjects(1, &thread_handle, TRUE, INFINITE)  
         == WAIT_FAILED) {  
       printf("ERROR: Failed WaitForMultipleObjects(): error = %ld\n",  
              GetLastError());  
   }  
   return(0);  
}  
/****************************************************************  
*        NAME : DWORD WINAPI sample_begin(LPVOID argp)  
* DESCRIPTION : do all channel specific processing  
*       INPUT : LPVOID argp - NULL pointer (not used)  
*      OUTPUT : none  
*     RETURNS : 0 on success; 1 if a failure was encountered  
*    CAUTIONS : none  
****************************************************************/  
DWORD WINAPI sample_begin(LPVOID argp)  
{  
   char channame[20];  
   int chdesc;  
   int cnt;  
   int hDevice[MAX_CHAN];  
   long EventCode;  
   int Index;  
   SRLWIN32INFO SrlWin32Info;  
   /*  
    * First thing is to inform SRL to signal the reset event  
    * when a Dialogic event occurs  
    */  
   SrlWin32Info.dwTotalSize  = sizeof(SRLWIN32INFO);  
   SrlWin32Info.dwHandleType = SR_RESETEVENT;  
   SrlWin32Info.ObjectHandle = hEvent[DIALOGIC_KEY];  
   if ( sr_setparm(SRL_DEVICE, SR_WIN32INFO, (void *)&SrlWin32Info)  
             == -1) {  
       printf("SRL - FAILED sr_setparm( SR_WIN32INFO ): %s (error #%d)\n",  
                ATDV_ERRMSGP(SRL_DEVICE), ATDV_LASTERR(SRL_DEVICE));  
       return(1);  
   }  
   for (cnt = 0; cnt < MAX_CHAN; cnt++) {  
      /* build name of voice channel */  
      sprintf(channame, "dxxxB%dC%d", (cnt / 4) + 1,  
                                      (cnt % 4) + 1);  
      /* open voice channel */  
      if ((chdesc = dx_open(channame, 0)) == -1) {  
         printf("%s - FAILED: dx_open(): system error = %d\n",  
                 channame, dx_fileerrno());  
         return(1);  
      }  
      hDevice[cnt] = chdesc;  
      printf("%s - Voice channel opened\n", ATDV_NAMEP(chdesc));  
      /* kick off the state machine by going offhook asynchronously */  
      if (dx_sethook(chdesc, DX_OFFHOOK, EV_ASYNC) == -1) {  
         printf("%s - FAILED: dx_sethook(DX_OFFHOOK): %s (error #%d)\n",  
                 ATDV_NAMEP(chdesc), ATDV_ERRMSGP(chdesc), ATDV_LASTERR(chdesc));  
         return(1);  
      }  
      printf("%s - Voice channel off-hook initialized\n",ATDV_NAMEP(chdesc));  
   }  
   /* loop until Keyboard input is received */  
   while (!Kbhit_flag) {  
      /*  
       * Wait on the reset events  
       */  
      if ((Index = WaitForMultipleObjects(MAX_RESET_EVENTS,  
                                          hEvent,  
                                          FALSE,  
                                          INFINITE)) == WAIT_FAILED) {  
         printf("ERROR: Failed WaitForMultipleObjects(): error = %ld\n",  
                GetLastError());  
      }  
      /* check if it is because of a key hit */  
      if (Index == KEYBOARD_KEY) {  
         continue;  
      }  
      /* must be a Dialogic event so process it */  
      sr_waitevt(0);  
      /*  
       * gather data about the event  
       */  
      chdesc = sr_getevtdev(0);  
      EventCode = sr_getevttype(0);  
      switch(EventCode) {  
      case TDX_SETHOOK:  
         if (ATDX_HOOKST(chdesc) == DX_OFFHOOK) {  
            printf("%s - Voice channel off-hook\n",ATDV_NAMEP(chdesc));  
            /* we went off hook so start dialing */  
            if (dx_dial(chdesc, "12025551212", NULL, EV_ASYNC) == -1) {  
               printf("%s - FAILED: dx_dial(): %s (error #%d)\n",  
                  ATDV_NAMEP(chdesc), ATDV_ERRMSGP(chdesc), ATDV_LASTERR(chdesc));  
               return(1);  
            }  
            printf("%s - Voice channel dialing initialized\n",ATDV_NAMEP(chdesc));  
         } else {  
            /* we went on hook so go off hook again */  
            printf("%s - Voice channel on-hook\n",ATDV_NAMEP(chdesc));  
            /* set the voice channel off-hook */  
            if (dx_sethook(chdesc, DX_OFFHOOK, EV_ASYNC) == -1) {  
               printf("%s - FAILED: dx_sethook(DX_OFFHOOK): %s (error #%d)\n",  
                  ATDV_NAMEP(chdesc), ATDV_ERRMSGP(chdesc), ATDV_LASTERR(chdesc));  
               return(1);  
            }  
            printf("%s - Voice channel off-hook initialized\n",ATDV_NAMEP(chdesc));  
         }  
         break;  
      case TDX_DIAL:  
         printf("%s - Voice channel Done dialing\n",ATDV_NAMEP(chdesc));  
         /* done dialing so set the voice channel on-hook */  
         if (dx_sethook(chdesc, DX_ONHOOK, EV_ASYNC) == -1) {  
            printf("%s - FAILED: dx_sethook(DX_ONHOOK): %s (error #%d)\n",  
               ATDV_NAMEP(chdesc), ATDV_ERRMSGP(chdesc), ATDV_LASTERR(chdesc));  
            return(1);  
         }  
         printf("%s - Voice channel on-hook initialized\n",ATDV_NAMEP(chdesc));  
         break;  
      default:  
         printf("Received unexpected event 0x%X on device %d\n", EventCode, chdesc);  
         break;  
      }  
   }  
   for (cnt = 0; cnt < MAX_CHAN; cnt++) {  
      /* close the voice channel */  
      chdesc = hDevice[cnt];  
      printf("%s - Voice channel closing\n",ATDV_NAMEP(chdesc));  
      if (dx_close(chdesc) == -1) {  
         printf("%s - FAILED: dx_close(): %s (error #%d)\n",  
                 ATDV_NAMEP(chdesc), ATDV_ERRMSGP(chdesc), ATDV_LASTERR(chdesc));  
         return(1);  
      }  
   }  
   return(0);  
}

Click here to contact Dialogic Customer Engineering