• 4.6.1. Files Used by the Demo
• 4.6.2. Programming Model
• 4.6.3. Demo-Related Initialization (Appinit.c)
• 4.6.4. IPLink-Related Initialization
• 4.6.5. Voice-Related Initialization
• 4.6.6. Data Structures
  • Session:
  • IPPARAMS
  • VOICEPARAMS
  • MailBox
• 4.6.7. Event Mechanism
  • Retrieving Events From the Queue
  • Handling SRL Events

4.6. Demo Details

This chapter provides a detailed description of the demo.

4.6.1. Files Used by the Demo

This section presents a closer examination of the IPTMail_R4 demo, by looking into its structure and source code. The IPTMail_R4 demo source code is located in the Dialogic\Samples\gc_demos\IPDemos\iptmail_R4\ directory and is included in the following files:

Table 2. IPTMail Source Files

Samples\gc_demos\IPDemos\IPTMail_R4\	APPDEFS.H	Application definitions
Samples\gc_demos\IPDemos\IPTMail_R4\	APPINIT.C	Application initialization
Samples\gc_demos\IPDemos\IPTMail_R4\	APPINIT.H	Header file for application initialization
Samples\gc_demos\IPDemos\IPTMail_R4\	APPMAIN.C	The main application file: contains the thread initialization, route ports, etc.
Samples\gc_demos\IPDemos\IPTMail_R4\	APPMAIN.H	Header file for main application
Samples\gc_demos\IPDemos\IPTMail_R4\	APPPARS.C	Read configuration file functions
Samples\gc_demos\IPDemos\IPTMail_R4\	APPPARS.H	Header file for reading configuration file functions
Samples\gc_demos\IPDemos\IPTMail_R4\	APPSTAT.C	Application state machine functions
Samples\gc_demos\IPDemos\IPTMail_R4\	APPSTAT.H	Header file for the application state machine functions
Samples\gc_demos\IPDemos\IPTMail_R4\	APPSTRC.H	Definitions of application structures
Samples\gc_demos\IPDemos\IPTMail_R4\	APPVARS.H	Definition of application variables
Samples\gc_demos\IPDemos\IPTMail_R4\	GATEIP.C	Initialize IP, Get IP available channels, handle IP events
Samples\gc_demos\IPDemos\IPTMail_R4\	GATEIP.H	Header file for the IP functions
Samples\gc_demos\IPDemos\IPTMail_R4\	MAILDEFS.H	Mailbox definitions
Samples\gc_demos\IPDemos\IPTMail_R4\	MAILUTIL.C	Mailbox utility functions
Samples\gc_demos\IPDemos\IPTMail_R4\	MAILUTIL.H	Header file for Mailbox utility functions
Samples\gc_demos\IPDemos\IPTMail_R4\	VOICE.C	Initialize voice resources, get voice resources available channels, handle voice resources events
Samples\gc_demos\IPDemos\IPTMail_R4\	VOICE.H	Header file for voice resources functions.
Samples\gc_demos\IPDemos\IPTMail_R4\	Iptmail_r4.cfg	IPTMail demo configuration file
Samples\gc_demos\IPDemos\IPTMail_R4\	Iptmail_r4.exe	IPTMail demo executable file
Samples\gc_demos\IPDemos\IPTMail_R4\	Stoplisten.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	ErrorInput.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	ListenMenu.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	MainMenu.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	SaveConfirm.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	SendMsg.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	StartRec.vox	Voice file
Samples\gc_demos\IPDemos\IPTMail_R4\	StopRec.vox	Voice File
Samples\gc_demos\IPDemos\IPTMail_R4\	ThankYou.vox	Voice File
Samples\gc_demos\IPDemos\IPTMail_R4\	UnavMenu.vox	Voice File
Samples\gc_demos\UTIL\	Libdbg.c, Libdbg.h, Libdefs.h	Project files that include all debug definitions and functions (static debug library)

NOTE:

If you move the files for the IPTMail demo, be sure to move the .vox files as well, otherwise the IPTMail demo will not work.

4.6.2. Programming Model

The IPTMail_R4 demo is designed to operate in a single thread mode. (There is a secondary thread operating alongside the main thread. This secondary thread consists of keyboard events, and does not change the overall structure of the demo.). Because of the nature of a single threaded application, the state machines do not, and should not, block any other operation, but wait for the SRL. Figure 2. Thread Diagram illustrates the demo's thread structure.

NOTE:

The application programming framework also allows multi-thread operation. It is not demonstrated in the IPTMail_R4 demo.

Figure 2. Thread Diagram

4.6.3. Demo-Related Initialization (Appinit.c)

1. Get any arguments from the command-line.
2. Reset the demo data structures. Initialize all channels' states to INIT.
3. Call gc_Start( ): starts all configured , call control libraries.
4. Set SRL modeltype to SR_STASYNC.
5. Set-up the call-back handler, callback_hdlr.
6. Call getVoiceChannels( ) which checks the number of available voice devices :
   • Get number of voice boards, by calling sr_getboardcnt( )
   • For each board that was found:

· Open the board, by calling dx_open( )

· Find number of channels per board, by calling ATDV_SUBDEVS( )

· Calculate the logical board and channel and save them into Session.VoiceParams

· Close the board, by calling dx_close( )

7. Call getIPChannels( ) which checks the number of available IP channels:
   • Get number of voice boards, by calling sr_getboardcnt( )
   • For each board that was found:

· Open the board, by calling gc_open( )

· Find number of IP channels per board, by calling TDV_SUBDEVS( )

· Calculate the logical board and channel and save them into Session.IPParams

· Close the board, by calling gc_close( )

8. Call getmailChannels( ) to find the demo MAX available channels (the smaller of available IP or Voice Devices and the number of channels specified with the --n command line option, if used ).

   NOTE:

   The printf( ) function must be used when printing an error/ trace/warning during the above initialization operations one through six, because some actions are not related to a specific channel and log files are not yet opened.

9. Open the channels' log files if --l command-line option was used.
10. Read information from the configuration file (IPTMail_R4.cfg or other CFG file determined by the user) and update the ConfigFileParm in the Session data structure.
11. Print information from the configuration file.
12. Call the IPInit( ) function. See Section 4.6.4. IPLink-Related Initialization for a description of the IPInit( ) function.
13. Call the VoiceInit( ) function. See Section 4.6.5. Voice-Related Initialization for a description of the VoiceInit( ) function..
14. Call the InitMailBoxs( ) function, which initializes the MailBox structure.
15. Create waitForKey thread to receive keyboard input.

4.6.4. IPLink-Related Initialization

The IPLink initialization procedure described in this section is defined in the IPInit( ) function in the GATEIP.C file, which performs the following:

For all channels:

• Call gc_OpenEx( )

Open all IP devices, and returns LineDevH.

• Save the channel number in the global array (HandleToChannel[ ]) according to the LineDevH handle.
• Call gc_GetXmitSlot(VoiceH)

Gets the transmit timeslot(Xmitslot) for the IP devices and saves it in the session.IPParams structure.




4.6.5. Voice-Related Initialization

Call VoiceInit( ), located in the VOICE.C file, which does the following:

For all channels:

• Call dx_open( ) to get the VoiceH (voice device handle ).
• Save the channel number in the global array (HandleToChannel[ ]) according to the VoiceH handle.
• Call dx_getxmitslot(VoiceH). Returns the Xmitslot (the SCbus time slot connected to transmit of voice channel) and saves it in the session.VoiceParams structure.

4.6.6. Data Structures

This section describes the main data structures:

• Session
• IPParams
• VoiceParams
• MailBox

Session:

The Session data structure (defined in Appstrc.h) contains the following fields:

• SessionState
  • The state machine current state
• State machine function
  • The current state machine function according to SessionState
• Session Number
  • The channel number
• ConfigFileParm
  • Information from the CFG file
• LogFile
  • A pointer to a session log file
• lpMailBox
  • Pointer to the MailBox that is used
• IPparams
  • IPPARAMS structure
• VoiceParams
  • VOICEPARAMS structure
• enteredExtNum
  • the extension number entered by the user

There is a session structure for every channel. Each channel session contains pointer to a MailBox structure.

typedef struct {  
   USHORT         sessionState;     /* Session state */  
   appStateFxn      stateFxn;         /* Next state machine function to be called */  
   UINT            sessionNumber;    /* Index session number */  
CallParameters      ConfigFileParm;   /* Information from cfg file */  
FILE            *LogFile;  
   LPMAILBOX         lpMailBox;        /* Pointer to the MailBox that is used */  
   VOICEPARAMS      VoiceParams;      /* The voice device parameters */  
   IPPARAMS          ipParams;        /* The IP device parameters */  
   char            enteredExtNum[10]; /* the Ext. number entered by the user*/  
BOOL            IsRouted; /* If Route done then set flag to TRUE else FALSE */  
   } AppSession;




IPPARAMS

The IPParams data structure (defined in Appstrc.h) contains the following fields:

• LineDevH
  • The Line Device Handle, to identify the physical device(s) that carries the call
• VoiceDevH
  • The voice device handle
• Xmitslot
  • The timeslot number for the IP
• logBoard
  • The logical board number
• logChan
  • The logical channel number
• crn
  • The Call Reference Number, generated after getting IP Offered

typedef struct {  
LINEDEV   linedev;   /* line device handle to identify the IP physical */  
                     /* device that carries the call */  
   int       VoiceDevH; /* the voice device handle */  
   long      XmitSlot;  /* the transmit timeslot number assigned for the Voice */  
                          /* Resourses */  
   int       logBoard;  /* The logical board number for the session */  
   int       logChan;   /* The logical channel number for the session */  
   CRN       crn;       /* The current call's CRN */  
} IPPARAMS;




VOICEPARAMS

The VoiceParams data structure (defined in Appstrc.h) contains the following fields:

• VoiceDevH
  • The voice device handle
• Xmitslot
  • The timeslot number for the voice resources
• logBoard
  • The logical board number
• logChan
  • The logical channel number
• digp -
  • A structure(DV_DIGIT) for the digits when getting TDX_GETDIG event
• iott
  • A structure (DX_IOTT) for the file handle, played or recorded file
• fPlayerStopped
  • A flag which indicates the Player status
• fRecorderStopped
  • A flag which indicates the Recorder status

typedef struct {  
int   VoiceDevH;     /* the voice device handle */  
long  XmitSlot; /*the  transmit timeslot number assigned for the Voice Resourses */  
int   logBoard;      /* The logical board number for the session */  
int   logChan;       /* The logical channel number for the session */  
DV_DIGIT digp[256];  /* A structure for the digits when getting TDX_GETDIG event */  
DX_IOTT  iott;       /* data structure contains parameters for the Input/Output */  
                     /* Transfer Table. */  
BOOL  fPlayerStopped; /* A flag which indicates the Player status */  
BOOL  fRecorderStopped;  /* A flag which indicates the Recorder status */  
} VOICEPARAMS;




MailBox

The MailBox data structure (defined in Maildefs.h) contains the following fields

• ExtNum
  • an array that contains the digits of the mailbox number
• msgFileStatus
  • 0 = no message
  • 1 = one saved message
• isBusy
  • 1 = mailbox is currently answering a call
  • 0 = mailbox is ready to answer an incoming call

typedef struct _MAILBOX {  
   // mail-box number  
   char ExtNum[MAX_EXTNUM_LENGTH+1];  
   // file status: 0 for no message,1 for saved message  
   MB_STATUS  msgFileStatus;  
   // Mailbox busy: 0 for ready to answer an incoming call, 1 for currently answering a call  
   BOOL          isBusy;  
} MAILBOX, *LPMAILBOX;




4.6.7. Event Mechanism

The IPTMail_R4 demo uses the SRL mechanism to retrieve the IP/R4/Keyboard events. The application waits for events using the sr_waitevt(-1) function. When an event occurs, SRL calls event handlers automatically.

In the initialization phase of the demo the mailInitialization( ) function will perform the following:

1. Set SRL modeltype to SR_STASYNC, by calling sr_setparm( ).
2. Set-up the call-back handler, by calling sr_enbhdlr( ).

The SRL will be notified of application exit events using a special key CTRL_CLOSE_EVENT, when calling sr_putevt( ).

Retrieving Events From the Queue

There is an endless loop {while(1) } in the main( ) function in the APPMAIN.C file. In that loop, the application waits forever for an event by calling the sr_waitevt( ) function. The event must be handled immediately and event-specific information should be retrieved before the next call to sr_waitevt( ).

When the next event occurs or when a timeout is reached, the sr_waitevt( ) returns and the call-back handler function is called automatically.

Handling SRL Events

When the R4/GC/Keyboard event is received, the application performs the following:

1. Get the event device handle, by calling sr_getevtdev( ).
2. Get the channel number related to the event, from the global array (HandleToChannel[ ]).
3. Update the METAEVENT structure by calling gc_GetMetaEvent( ).
4. Get the event type, by calling sr_getevttype( ).

If type==CTRL_CLOSE_EVENT,
then end application,
else run the state machine function.

Click here to contact Dialogic Customer Engineering