• 4.1.1. General Guidelines
• Using Symbolic Defines
• Including Header Files
• Checking Return Codes
• 4.1.2. Initialization
• Set Configuration
• 4.1.3. Terminating
• 4.1.4. Compiling and Linking
• 4.1.5. Aborting

4. Application Guidelines

This chapter contains suggestions to guide programmers in designing and coding a Dialogic DCB/SC application for Windows.

4.1. Writing a Simple Application

This section provides DCB/SC general and task-specific programming guidelines:

• General Guidelines
• Initialization
• Compiling and Linking
• Aborting

NOTE:

These guidelines are not a comprehensive guide to developing or debugging DCB/SC applications. The examples following each function description in Chapter 3 illustrate proper use of the DCB/SC functions.

4.1.1. General Guidelines

The following general guidelines for writing Dialogic applications are explained in this section:

• Using symbolic defines
• Including header files
• Checking return codes

Using Symbolic Defines

Dialogic does not guarantee the numerical values of defines will remain the same as new versions of a software package are released. In general, do not use a numerical value in your application when an equivalent symbolic define is available. Symbolic defines are found in the dtilib.h, msilib.h, and dcblib.h files.

Including Header Files

Various header files must be included in your application to test for error conditions, to use library functions from other Dialogic products, or to perform event-management and standard-attribute functions. An example is shown below. See Chapter 2 for details.

#include <windows.h>

#include <errno.h>  
#include "srllib.h"  
#include "dtilib.h"  
#include "msilib.h"  
#include "dcblib.h"

NOTE:

To avoid redundancy in the remaining programming examples in this chapter, #include statements will not be shown.

Checking Return Codes

Most Network and DCB/SC Windows library functions return a value of -1 if they fail (extended attribute functions return AT_FAILURE or AT_FAILUREP if they fail). Any call to a library function should therefore check for a return value indicating an error. This can be done using a format similar to the following:

/* call to Dialogic DCB/SC library function */  
if (dcb_xxx(arguments) == -1) {  
	/* error handling routine */  
}  
/* successful function call -  
	continue processing ...  */

Using this technique ensures that all errors resulting from a library call will be trapped and handled properly by the application. In many cases, you can check for a return value of other than zero (0), as shown in the example below. However, this should only be used where a non-zero value is returned when the function fails. For details, see Chapter 2 and Chapter 3.

/* error handling routine */  
void do_error( devh, funcname )  
   int devh;		/* Dialogic device handle */  
   char *funcname;		/* function name */  
{  
   int errorval = ATDV_LASTERR( devh );  
   printf( "Error while calling function %s on device %s.  \n", funcname,  
            ATDV_NAMEP( devh ) );  
   if ( errorval == EDT_SYSTEM ) {  
       printf( "errno = %d\n", errno );  
      ( invalid call remove)  
   } else {  
   printf( "Error value = %d\nError message = %s\n",  
            errorval, ATDV_ERRMSGP( devh ) );  
   }  
   return;  
}  
main( )  
{  
   .  
   .  
   .  
   /* example call to Dialogic DCB/SC library function */  
   if (dcb_setdigitmsk( devh, confid, CBMM_ALL)!= 0) {  
       do_error( devh, "dcb_setdigitmsk()" );  
   }  
   /* successful function call - continue processing */  
   .  
   .  
   .  
}

NOTE:

Calls to dcb_open( ) return either -1 or a non-zero device handle. Therefore, when issuing the dcb_open( ) function, check for a return of -1. The specific error can be found in the global variable errno, contained in errno.h.

4.1.2. Initialization

As a first step, a DCB/SC application must intialize parameters.

Set Configuration

Use dcb_setbrdparm( ) to set active talker and volume control digits. Specific setting choices include:

Active Talker Feature (MSG_ACTID)	Active Talker feature can be enabled or disabled by setting to ACTID_ON or ACTID_OFF.
Volume Control Digits (MSG_VOLDIG)	Defines the volume control status and volume up/down/reset digits.

If the resource assignment table updates are desired by the application, enable event generation using dcb_evtstatus( ).

4.1.3. Terminating

When your process completes, devices should be shut down in an orderly fashion. Tasks that are performed to terminate an application generally include:

• Disabling events
• Stop listening to time slots
• Deleting all conferences
• Closing devices

NOTE:

SRL Event Management functions (such as sr_dishdlr( ), which disables an event handler) must be called before closing the device that is sending the handler event notifications (see Appendix A for SRL details).

4.1.4. Compiling and Linking

To compile and link your application, follow the instructions for your version of the Windows Compiler.

If using Microsoft Visual C++, link with the following libraries when using the DCB/SC board:

libsrlmt.lib  
libdtimt.lib

By default, the files are found in <install drive%>:<install directory>\dialogic\lib. Depending on your application, you may need to link with other libraries. Refer to the appropriate documentation for other Dialogic products.

If using Borland C++, you must include the cross-compatibility library files in your file set. The files are found in <install drive%>:<install directory>\dialogic\lib. You may also use the x-compatibility files when using Microsoft Visual C++.

4.1.5. Aborting

If you abort a DCB/SC Windows application by pressing the interrupt key, the Windows system will terminate the current process but may leave devices in an unknown state. As a result, you may encounter errors the next time the application runs.

To avoid errors of this type, your application should include an event handler that traps the interrupt key and performs the actions listed in Section 4.1.3, Terminating.

Click here to contact Dialogic Customer Engineering