Providing simple solutions to todays tough T1 and E1 problems

GL Communications Inc.

GL T1/E1 Application Development Toolkit For Windows Programmers Guide and Reference Manual
Version 10.10

GL Communications Inc.
818 West Diamond Avenue - Third Floor Gaithersburg, MD 20878 USA

Voice 301-670-4784 Web http://www.gl.com E-mail [email protected]

Contents
1. INTRODUCTION............................................................................................................................... 2 1.1 OBSOLETE AND INTERNAL (LOW LEVEL) FUNCTIONS .................................................................. 2 1.1.1 Obsolete Functions ................................................................................................................. 2 1.1.2 Internal (low level) Functions ................................................................................................ 2 1.2 SYMBOL CONVENTIONS ............................................................................................................... 4 2 PROGRAMMERS GUIDE............................................................................................................... 6 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 2.11 2.12 2.13 2.14 2.15 2.16 2.17 2.18 2.19 2.20 2.21 2.22 2.23 2.24 2.25 2.26 3 3.1 3.2 3.3 4 CREATING AND INITIALIZING INTERFACE OBJECT ........................................................................ 6 USING BUILT-IN DEBUGGING FEATURES ...................................................................................... 7 FUNCTION PARAMETERS .............................................................................................................. 8 FUNCTION GROUPS ...................................................................................................................... 8 INITIALIZATION AND TERMINATION FUNCTIONS .......................................................................... 8 CONFIGURATION FUNCTIONS ....................................................................................................... 9 MODE FUNCTIONS ...................................................................................................................... 10 CODEC FUNCTIONS ..................................................................................................................... 11 PORT INPUT/OUTPUT FUNCTIONS............................................................................................... 12 REGISTER FUNCTIONS ................................................................................................................ 12 BUFFER FUNCTIONS ................................................................................................................... 13 CROSS PORT FUNCTIONS ............................................................................................................ 14 DRIVER FUNCTIONS ................................................................................................................... 14 FRAMER FUNCTIONS .................................................................................................................. 16 BIT ERROR RATE FUNCTIONS..................................................................................................... 19 TIMESLOT FUNCTIONS................................................................................................................ 20 PATTERN FILE FUNCTIONS ......................................................................................................... 20 STREAM I/O FUNCTIONS ............................................................................................................ 21 MISCELLANEOUS FUNCTIONS ..................................................................................................... 22 SUBCHANNEL INPUT/OUTPUT .................................................................................................... 23 HDLC ENCODING/DECODING .................................................................................................... 24 FACILITY DATA LINK ................................................................................................................. 25 MEMORY MAPPED FILES AND VARRECBUF CLASS ................................................................... 26 DYNAMIC LIST BUFFER .............................................................................................................. 27 C INTERFACE.............................................................................................................................. 28 PERIODIC FILE SAVING............................................................................................................... 29 LINKER ....................................................................................................................................... 31 CONFIGURATION FILES .............................................................................................................. 32 BUILDING EXAMPLES................................................................................................................. 32

BUILDING APPLICATIONS USING THE API LIBRARY ....................................................... 31

DRIVER API LIBRARY REFERENCE ........................................................................................ 33 4.1 EXCEPTIONS ............................................................................................................................... 33 4.2 ENABLING BUILT-IN DIAGNOSTIC MESSAGES IN DEBUG BUILDS ............................................ 35 4.3 CHECK WHETHER THE BUILT-IN DIAGNOSTIC MESSAGES ARE ENABLED .................................. 35 4.4 DISPLAY MESSAGE BOX USING PRINTF FORMATTING................................................................ 36 4.5 DISPLAY MESSAGE BOX USING PRINTF FORMATTING IN DEBUG BUILDS ONLY. ..................... 36 4.6 FORMAT AND DISPLAY CRITICAL ERROR MESSAGE BOX AND THROW AN EXCEPTION.............. 37 4.7 FORMAT ERROR MESSAGE BOX IN DEBUG BUILDS ONLY. APPEND GLCOMEXCEPTIONS TEXTUAL DESCRIPTION AND THROW A GLCOMEXCEPTIONS EXCEPTION. ............................................... 38 4.8 GET GLCOMEXCEPTIONS TEXTUAL DESCRIPTION ..................................................................... 38 4.9 GET TEXTUAL DESCRIPTION OF AN INTERNAL ERROR ............................................................... 39 4.10 CREATING A C INTERFACE OBJECT ............................................................................................ 40 4.11 DESTROYING A C INTERFACE OBJECT ........................................................................................ 41 4.12 CHECKING IF C INTERFACE OBJECT EXISTS .............................................................................. 41

II

4.13 4.14 4.15 4.16 4.17 4.18 4.19 4.20 4.21 4.22 4.23 4.24 4.25 4.26 4.27 4.28 4.29 4.30 4.31 4.32 4.33 4.34 4.35 4.36 4.37 4.38 4.39 4.40 4.41 4.42 4.43 4.44 4.45 4.46 4.47 4.48 4.49 4.50 4.51 4.52 4.53 4.54 4.55 4.56 4.57 4.58 4.59 4.60 4.61 4.62 4.63 4.64 4.65 4.66 4.67 4.68

GET POINTER TO DEVICE DRIVER INFORMATION FOR A DEVICE ................................................ 42 GET DEFAULT FILE PATTERN NAME .......................................................................................... 43 SET DEFAULT FILE PATTERN NAME ........................................................................................... 43 GET CURRENT PATTERN FILE NAME .......................................................................................... 43 SET CURRENT PATTERN FILE NAME .......................................................................................... 44 GET ACTIVE RECEIVE BUFFER POINTER .................................................................................... 44 GET ACTIVE TRANSMIT BUFFER POINTER.................................................................................. 45 GET ACTIVE RECEIVE BUFFER OFFSET ...................................................................................... 45 GET ACTIVE TRANSMIT BUFFER OFFSET ................................................................................... 46 GET INACTIVE RECEIVE BUFFER POINTER ................................................................................. 46 GET INACTIVE TRANSMIT BUFFER POINTER............................................................................... 47 GET ACTIVE RECEIVE BUFFER SEQUENTIAL NUMBER ............................................................... 48 GET ACTIVE TRANSMIT BUFFER SEQUENTIAL NUMBER ............................................................ 48 GET DATA TRANSMISSION RATE ............................................................................................... 49 FILL BOTH GLOBAL TRANSMIT BUFFERS WITH IDLE CODE ....................................................... 49 FILL BOTH GLOBAL TRANSMIT BUFFERS WITH A BYTE STRING................................................ 50 GET DRIVERS CURRENTLY SELECTED DEVICE NUMBER (OBSOLETE) ...................................... 50 GET NUMBER OF PHYSICAL DEVICES INSTALLED AND CONFIGURED ......................................... 51 GET NUMBER OF DEVICES FOUND DURING DRIVER INITIALIZATION ........................................ 52 GET RECEIVE/TRANSMIT GLOBAL BUFFER POINTERS ............................................................... 52 SELECT CURRENT DRIVER DEVICE NUMBER (OBSOLETE) ......................................................... 54 SYNCHRONIZE DEVICES ............................................................................................................. 54 GET IDLE CODE .......................................................................................................................... 54 GET NUMBER OF FRAMES PER MULTIFRAME ............................................................................. 55 GET MULTIFRAME SIZE.............................................................................................................. 56 GET MULTIFRAME DURATION.................................................................................................... 56 GET USABLE SOFTWARE BUFFER SIZE ....................................................................................... 57 GET NUMBER OF MULTIFRAMES PER SOFTWARE BUFFER ......................................................... 57 GET NUMBER OF FRAMES PER SOFTWARE BUFFER.................................................................... 58 GET ACTIVE GLOBAL TRANSMIT SOFTWARE BUFFER INDEX ..................................................... 58 GET ACTIVE GLOBAL RECEIVE SOFTWARE BUFFER INDEX ....................................................... 59 INITIALIZE INTERFACE ............................................................................................................... 60 CHECK CARD I/O AND MEMORY ................................................................................................ 61 CHECK CARD INPUT/OUTPUT ..................................................................................................... 61 CHECK CARD MEMORY.............................................................................................................. 62 LOAD DEFAULT CONFIGURATION (INTERNAL FUNCTION) ......................................................... 63 INITIALIZE IRQ, MEMORY OFFSET AND BASE ADDRESS (INTERNAL FUNCTION)....................... 63 CODEC INITIALIZATION (INTERNAL FUNCTION) ......................................................................... 64 READ FROM A PORT (INTERNAL FUNCTION)............................................................................... 64 WRITE TO A PORT (INTERNAL FUNCTION).................................................................................. 65 LOADING INTERNAL FPGA ........................................................................................................ 66 LOADING STATIC BER INTERNAL FPGA ................................................................................... 67 WAITING (INTERNAL FUNCTION) ............................................................................................... 68 FILL TRANSMIT BUFFERS WITH A FILLER BYTE (INTERNAL FUNCTION) .................................... 68 CHECKING MODE ....................................................................................................................... 69 SETTING MODE (INTERNAL FUNCTION) ..................................................................................... 70 WRITE TO TIMESLOT ASSIGNER (INTERNAL FUNCTION) ............................................................ 70 SPECIFYING THE TIMESLOT ASSIGNER RANGE ........................................................................... 71 WRITING TO DRIVER, FRAMER OR AUDIO REGISTERS (INTERNAL FUNCTION)........................... 72 SET CODEC GAIN OR TIME SLOT ................................................................................................ 73 SET CODEC CLOCK OR CASF..................................................................................................... 74 RESET CODEC FROM CASF TO BER .......................................................................................... 74 GET CODEC GAIN OR TIME SLOT ............................................................................................... 75 TURN ON CODEC SPEAKER OR VF TRANSMIT, OR ENABLE DROP INSERT .................................. 76 TURN OFF CODEC SPEAKER OR VF TRANSMIT, OR DISABLE DROP INSERT ............................... 77 CHECK CODEC SETTINGS ........................................................................................................... 78

III

4.69 ENABLE/DISABLE TIME SLOT FOR MULTIFRAME TRANSMISSION .............................................. 79 4.70 CHECK WHETHER A TIME SLOT IS AVAILABLE .......................................................................... 79 4.71 CHECK WHETHER ALL THE TIME SLOTS ARE AVAILABLE .......................................................... 80 4.72 MAKE ALL TIME SLOTS AVAILABLE/UNAVAILABLE ................................................................. 80 4.73 RESTORE TIME SLOT STATUS ..................................................................................................... 81 4.74 SAVE TIME SLOT STATUS........................................................................................................... 81 4.75 READ BER ERROR COUNTER AND CLEAR IT ............................................................................. 82 4.76 INSERT A LOGICAL OR BPV ERROR............................................................................................ 82 4.77 SELECT RECEIVE OR TRANSMIT BER......................................................................................... 83 4.78 DESELECT RECEIVE/TRANSMIT BER ......................................................................................... 84 4.79 LOAD BER STATIC PATTERN ..................................................................................................... 84 4.80 SETTING CROSS PORT MODE...................................................................................................... 84 4.81 GETTING CROSS PORT MODE ..................................................................................................... 85 4.82 DISABLING DRIVER INTERRUPT EVENTS .................................................................................... 85 4.83 ENABLING DRIVER INTERRUPT EVENTS ..................................................................................... 86 4.84 GET DRIVER CHIP ATTRIBUTES.................................................................................................. 86 4.85 CHECK WHETHER A DRIVER ATTRIBUTE IS SET/SELECTED ....................................................... 87 4.86 SET DRIVER EQUALIZER CONTROL OR LINE LENGTH ................................................................ 88 4.87 SET DRIVER EQUALIZER GAIN ................................................................................................... 89 4.88 ENABLING DRIVER LOOPBACK, TRANSMISSION ALL ONES, NETWORK LOOP UP/DOWN, OR RX MONITOR MODE ....................................................................................................................................... 90 4.89 DISABLING DRIVER LOOPBACK, TRANSMISSION ALL ONES, NETWORK LOOP UP/DOWN, OR RX MONITOR MODE ....................................................................................................................................... 91 4.90 RESETTING DRIVER REGISTERS ................................................................................................. 92 4.91 CHECK DRIVER JITTER SETTINGS ............................................................................................... 92 4.92 SET DRIVER JITTER .................................................................................................................... 93 4.93 CHECKING T1 FRAMER .............................................................................................................. 94 4.94 CHECKING E1 FRAMER .............................................................................................................. 96 4.95 CHECKING IF A FRAMER TIME SLOT IS ENABLED ....................................................................... 97 4.96 DISABLING FRAMER INTERRUPTS............................................................................................... 98 4.97 DISABLING FRAME INTERRUPTS SELECTIVELY .......................................................................... 99 4.98 ENABLING ALL FRAME INTERRUPTS ........................................................................................ 100 4.99 ENABLING FRAME INTERRUPTS SELECTIVELY ......................................................................... 101 4.100 GET FRAMER RECEIVE STATUS REGISTER (RSR) OR RECEIVE INTERRUPT MASK REGISTER (RIMR) 102 4.101 GETTING NUMBER OF FRAME ERRORS ..................................................................................... 103 4.102 SET FRAMER ERROR COUNTERS TO A START VALUE ............................................................... 104 4.103 ENABLING FRAMER FEATURES ................................................................................................ 105 4.104 DISABLING FRAMER FEATURES ............................................................................................... 106 4.105 SETTING FRAMER FEATURES ON.............................................................................................. 108 4.106 SELECTING FRAMER FEATURES ............................................................................................... 109 4.107 DESELECTECTING FRAMER CHANNELS .................................................................................... 110 4.108 SELECTING FRAMER TIME SLOTS ............................................................................................. 112 4.109 DESELECTECTING FRAMER TIME SLOTS .................................................................................. 113 4.110 DETECTING RX B8ZS OR COFA ( T1 ONLY ) .......................................................................... 114 4.111 RESYNC FRAMER ..................................................................................................................... 115 4.112 SET FRAMER TX EXTRA, NATIONAL OR INTERNATIONAL BITS (E1 ONLY)............................... 116 4.113 GET FRAMER TX EXTRA, NATIONAL OR INTERNATIONAL BITS (E1 ONLY) .............................. 117 4.114 RETRIEVING TIMESLOT DATA .................................................................................................. 118 4.115 RETRIEVING LATEST TIMESLOT DATA ..................................................................................... 119 4.116 GET DRIVER VERSION .............................................................................................................. 120 4.117 GET API LIBRARY VERSION .................................................................................................... 120 4.118 GET MAXIMUM TIME SLOT NUMBER ....................................................................................... 121 4.119 GET MAXIMUM NUMBER OF DEVICES SUPPORTED BY DEVICE DRIVER ................................... 121 4.120 SETTING ON-HOOK/OFF-HOOK IN A GLOBAL TRANSMIT BUFFER ............................................ 122 4.121 GET RECEIVE LINE FREQUENCY .............................................................................................. 123

IV

4.122 ENABLING RECEIVE AND TRANSMIT BUFFERS ......................................................................... 123 4.123 DISABLING RECEIVE AND TRANSMIT BUFFERS ........................................................................ 124 4.124 TRANSMITTING IDLE CODES .................................................................................................... 125 4.125 FILLING TRANSMIT BUFFER WITH A MULTIFRAME .................................................................. 125 4.126 DISABLING UNFRAMED INPUT ................................................................................................. 126 4.127 ENABLING UNFRAMED INPUT .................................................................................................. 127 4.128 SETTING TX INVERSION MASK ................................................................................................. 127 4.129 SETTING RX INVERSION MASK................................................................................................. 128 4.130 GETTING RX INVERSION MASK ................................................................................................ 128 4.131 GETTING TX INVERSION MASK ................................................................................................ 129 4.132 BIOSTREAM CLASS. STREAM INPUT/OUTPUT........................................................................... 130 4.132.1 Creating and Initializing the Basic Input Output Stream Object (BioStream constructor). 130 4.132.2 Creating and Initializing the Basic Input Output Stream Object (BioStream constructor). 131 4.132.3 Destroying the Basic Input Output Stream Object (BioStream destructor). .................. 131 4.132.4 Set Read Channel Mask. ................................................................................................ 132 4.132.5 Set Write Channel Mask................................................................................................. 132 4.132.6 Set Read Margins in Multiframes. ................................................................................. 133 4.132.7 Set Write Margins in Multiframes.................................................................................. 133 4.132.8 Set Read Margins in Bytes. ............................................................................................ 134 4.132.9 Set Write Margins in Bytes. ........................................................................................... 135 4.132.10 Get Missed Receive Bytes Count.................................................................................... 135 4.132.11 Get Missed Transmit Bytes Count.................................................................................. 136 4.132.12 Read Stream (Receive). .................................................................................................. 136 4.132.13 Write Stream (Transmit). ............................................................................................... 137 4.132.14 Reopen Stream for Receiving......................................................................................... 138 4.132.15 Reopen Stream for Transmitting. ................................................................................... 138 4.132.16 Reopen Stream for Receiving, Transmitting, or both..................................................... 139 4.132.17 Fill Global Transmit Buffers with Idle Code ................................................................. 139 4.132.18 Fill Global Transmit Buffers with Byte String ............................................................... 140 4.132.19 Calculate Channel Mask................................................................................................ 141 4.133 BIOSTREAMEX CLASS. SIGNALING BITS PROCESSING. ............................................................ 142 4.133.1 BioStreamEx Constructor .............................................................................................. 142 4.133.2 Reading Signalling Bits and Data.................................................................................. 143
4.133.2.1 4.133.2.2 4.133.2.3 Signaling Bits Transition Item Structure.................................................................................. 143 Reading Data and Signalling Bits ............................................................................................ 144 Reading Signaling Transitions Only ........................................................................................ 145

Setting Signalling Bits for the Subsequent Signalling or Data+Signalling Transmission 146 4.133.4 Transmit Signalling Bits ................................................................................................ 147 4.133.5 Transmitting Data and Signalling Bits .......................................................................... 147 4.134 SIGBITSASYNCIO CLASS. RECEIVING AND TRANSMITTING SIGNALING BITS ONLY ON MULTIPLE CHANNELS.............................................................................................................................................. 149 4.134.1 SigBitsAsyncIo Constructor ........................................................................................... 149 4.134.2 Opening SigBitsAsyncIo for Singnaling Bits Reading or Writing.................................. 149 4.134.3 Stopping Receiving or Transmitting Signaling Bits ....................................................... 150 4.134.4 Reading Signaling Transitions....................................................................................... 150 4.134.5 Transmitting Signals on All Selected Timeslots ............................................................. 151 4.134.6 Access to BioStreamEx for Accesing Individual Timeslots ............................................ 151 4.134.7 Retrieving Receive Event Handle for Signaling Transitions.......................................... 152 4.134.8 Getting Number of Queued Signaling Transitions......................................................... 152 4.134.9 Getting Number of Skipped Signals ............................................................................... 152 4.134.10 Getting Number of Underruns ....................................................................................... 152 4.135 DETERMINING IF THE RECEIVE THREAD IS ALIVE .................................................................... 153 4.136 BITSTREAM CLASS. SUBCHANNEL INPUT ................................................................................. 154

4.133.3

4.136.1 BitStream Constructors.................................................................................................. 154 4.136.2 Setting Bit Mask ............................................................................................................. 155 4.136.3 Getting Bit Mask ............................................................................................................ 155 4.136.4 Set or Unset Bit Inversion .............................................................................................. 155 4.136.5 Get Inversion Setting...................................................................................................... 156 4.136.6 Resetting Stream ............................................................................................................ 157 4.136.7 Reading Stream.............................................................................................................. 157 4.136.8 Get Payload Bit Count ................................................................................................... 157 4.137 OUTBITSTREAM CLASS. SUBCHANNEL OUTPUT ...................................................................... 158 4.137.1 Constructor .................................................................................................................... 158 4.137.2 Reinitialization of the OutBitStream Instance................................................................ 158 4.137.3 Getting Bit Mask ............................................................................................................ 159 4.137.4 Get Inversion.................................................................................................................. 159 4.137.5 Get Filler for Zero Mask Bits......................................................................................... 159 4.137.6 Write Subchannel Stream............................................................................................... 160 4.138 MSBSTUFFBITS. HDLC BIT STUFFING..................................................................................... 161 4.139 BITREMOVE CLASS. HDLC ZERO BIT REMOVAL .................................................................... 162 4.139.1 BitRemove Constructor.................................................................................................. 162 4.139.2 Remove Stuffed Zero Bits ............................................................................................... 162 4.139.3 Reset Input ..................................................................................................................... 163 4.139.4 Get Statistics .................................................................................................................. 164 4.139.5 Set Counters................................................................................................................... 164 4.139.6 Get Statistics and Reset Counters .................................................................................. 165 4.140 FDLSTREAM CLASS. FACILITY DATA LINK (FDL) INPUT/OUTPUT........................................... 166 4.140.1 Constructor .................................................................................................................... 166 4.141 REINITIALIZE FDLSTREAM ....................................................................................................... 168 4.141.1 Set New Read Subchannel Mask .................................................................................... 169 4.141.2 Set New Write Subchannel Mask ................................................................................... 169 4.141.3 Set Safe Margins for Reading in Multiframes................................................................ 170 4.141.4 Set Safe Margins for Writing in Multiframes................................................................. 170 4.141.5 Set Safe Margins for Reading in Bytes........................................................................... 170 4.141.6 Set Safe Margins for Writing in Bytes............................................................................ 171 4.141.7 Get Used Read Bits per each Four Frames ................................................................... 171 4.141.8 Get Used Write Bits per each Four Frames................................................................... 171 4.141.9 Get Missed Bytes when Reading Underrun Occurrs ..................................................... 172 4.141.10 Get Missed Bytes when Writing Overrun Occurrs......................................................... 172 4.141.11 Reset Stream .................................................................................................................. 172 4.141.12 Read Stream................................................................................................................... 172 4.141.13 Write Stream .................................................................................................................. 173 4.141.14 Reset Input Stream ......................................................................................................... 173 4.141.15 Reset Output Stream ...................................................................................................... 173 4.141.16 Reset Both Input and/or Output Streams ....................................................................... 174 4.141.17 Open for Synchronous Reading ..................................................................................... 174 4.142 MEMFILE CLASS. MEMORY MAPPED INPUT/OUTPUT .............................................................. 175 4.142.1 Constructors................................................................................................................... 175 4.142.2 Reinitialize ( ReOpen) the Object .................................................................................. 176 4.142.3 Close File....................................................................................................................... 176 4.142.4 Return Unused Bytes...................................................................................................... 177 4.142.5 Return Unused Bytes...................................................................................................... 177 4.142.6 Check if File is Open ..................................................................................................... 177 4.143 VARRECBUF CLASS. VARIABLE RECORD BUFFER ................................................................... 177 4.143.1 Constructors................................................................................................................... 178 4.143.2 Initialization................................................................................................................... 178 4.143.3 Close .............................................................................................................................. 178 4.143.4 Append a Record............................................................................................................ 179 4.143.5 Append a Record Consisting of two Parts: Header and Data ....................................... 179

VI

4.143.6 Direct Record Access by Record Number...................................................................... 180 4.143.7 Sequential Access. Get Next Record .............................................................................. 180 4.143.8 Sequential Access. Get Previous Record ....................................................................... 181 4.143.9 Get Number of Records in the Buffer ( List ) ................................................................. 181 4.143.10 Get Memory Size used by Data in the List ..................................................................... 181 4.143.11 Flush MemFile Object Associated with VarRecBuf to Disk........................................... 182 4.143.12 Delete All Records ......................................................................................................... 182 4.144 CLASS DYNAMICLISTBUF. DYNAMIC LIST BUFFER IN CALLER SUPPLIED BUFFER. ................. 182 4.144.1 Constructors................................................................................................................... 182 4.144.2 Assignment Operator ..................................................................................................... 183 4.144.3 Appending a Record....................................................................................................... 183 4.144.4 Getting the First Record ................................................................................................ 183 4.144.5 Getting the Next Record................................................................................................. 184 4.144.6 Erase the List ................................................................................................................. 184 4.144.7 Get Total Size of All Records in the List ........................................................................ 184 4.144.8 Check if the List is Empty............................................................................................... 184 4.144.9 Get Number of Records in the List................................................................................. 185 4.145 CALCULATE CRC FOR HDLC .................................................................................................. 185 4.146 INVERT BYTE(S)....................................................................................................................... 185 4.146.1 Invert Bits In-place ........................................................................................................ 185 4.146.2 Invert a Byte................................................................................................................... 186 4.146.3 Copy Byte String with Inversion .................................................................................... 186 4.147 ASYNCHRONOUS HDLC FRAME PROCESSING .......................................................................... 187 4.147.1 Constructor .................................................................................................................... 187 4.147.2 Starting Transmission or Reception............................................................................... 188 4.147.3 Transmitting Frames...................................................................................................... 189 4.147.4 Receiving Frames .......................................................................................................... 190 4.147.5 Receiving Frames with Extended Frame Information ................................................... 191
4.147.5.1 HdlcFrameInfo......................................................................................................................... 191

4.147.6 Example of Loop Back ................................................................................................... 192 4.147.7 Stopping Receiving or Transmitting .............................................................................. 193 4.147.8 Getting the Rx or Tx Queue Size .................................................................................... 193 4.147.9 Getting Total Number of CRC Errors in Received Frames ........................................... 194 4.147.10 Getting Total Number of Malformed Received Frames ................................................. 194 4.147.11 Get Total Number of UnderRuns or OverRuns.............................................................. 194 4.147.12 Get Number of Discarded Frame Octets ....................................................................... 194 4.147.13 Get Number of Discarded Frames ................................................................................. 195 4.147.14 Setting Minimum Number of Flags Between Frames..................................................... 195 4.147.15 Getting the Minimum Number of Flags Between Frames.............................................. 195 4.148 ENABLING THE SOUND DRIVER ................................................................................................ 196 4.149 DISABLING THE SOUND DRIVER ............................................................................................... 196 4.150 QUERYING IF THE SOUND DRIVER IS ENABLED ........................................................................ 196 4.151 GET APPLICATION INSTANCE COUNT TRANSMITTING ON THE CARD ....................................... 197 4.152 GET APPLICATION INSTANCE COUNT RECEIVING ON THE CARD .............................................. 197 4.153 GET LINE LEVEL VOLTAGE ...................................................................................................... 197 4.154 GET HD CARD FPGA PARAMETERS ........................................................................................ 198 4.155 SET HD CARD FPGA PARAMETERS ......................................................................................... 199 4.156 CHECK IF SEPARATE FDL BUFFERS ARE USED ......................................................................... 200 4.157 GET SEPARATE FDL BUFFERS ADDRESSES .............................................................................. 200 4.158 GET SIGNALING INFORMATION FOR HD CARDS ....................................................................... 201 4.159 GET FIRMWARE VERSION......................................................................................................... 201 4.160 SET TX SIGNALING BITS FOR A TIMESLOT FOR HD CARDS ...................................................... 202 4.161 GET TX SIGNALING BITS FOR A TIMESLOT FOR HD CARDS ..................................................... 202 4.162 GET RX SIGNALING BITS FOR A TIMESLOT FOR HD CARDS ..................................................... 203 4.163 CHECK IF TX SIGNALING BITS FOR A TIMESLOT ARE ENABLED FOR HD CARDS ...................... 203 4.164 CFILECAPTURINGOPERATIONS, PERIODIC FILE SAVING CLASS ............................................... 204

VII

4.164.1 Creating the Periodic File Saving Class........................................................................ 204 4.164.2 Initializing the Periodic File Saving Class Data Members............................................ 204 4.164.3 Initializing the CFileCapturingOperations Data Members ........................................... 206 4.164.4 Opening Files for Capture ............................................................................................. 206 4.164.5 Allocating Memory for Device Information................................................................... 207 4.164.6 Deallocating Device Information................................................................................... 207 4.164.7 Closing the Periodic File Saving Class ......................................................................... 208 4.164.8 Close all Files ................................................................................................................ 208 4.164.9 Periodic File Saving Control Loop................................................................................ 209 4.164.10 Periodic File Saving Control Loop................................................................................ 209 4.164.11 Periodic File Saving Control Loop................................................................................ 210 4.164.12 Clear Messages.............................................................................................................. 210 4.164.13 Initialization of File Saving Object................................................................................ 210 4.164.14 Synchronize Captures .................................................................................................... 211 4.164.15 PeriodicFileSaving I/O Errors....................................................................................... 211 4.165.16 PeriodicFileSaving Disk Usage Limitations ..................................................................... 212 5 INDEX ............................................................................................................................................. 213

VIII

Figures
FIGURE 1. SYSTEM HIERARCHY ...................................................................................................................... 3

Tables
TABLE 1. DEVICE DRIVER FEATURES .......................................................ERROR! BOOKMARK NOT DEFINED. TABLE 2. INITIALIZATION FUNCTIONS ............................................................................................................. 8 TABLE 3. CONFIGURATION FUNCTIONS ......................................................................................................... 10 TABLE 4. MODE FUNCTIONS ......................................................................................................................... 10 TABLE 5. CODEC FUNCTIONS ........................................................................................................................ 11 TABLE 6. PORT I/O FUNCTIONS ..................................................................................................................... 12 TABLE 7. REGISTER FUNCTIONS .................................................................................................................... 12 TABLE 8. BUFFER FUNCTIONS ....................................................................................................................... 13 TABLE 9. DRIVER FUNCTIONS ....................................................................................................................... 15 TABLE 10. FRAMER FUNCTIONS .................................................................................................................... 18 TABLE 11. BER FUNCTIONS .......................................................................................................................... 19 TABLE 12. TIMESLOT FUNCTIONS ................................................................................................................. 20 TABLE 13. PATTERN FILE FUNCTIONS ........................................................................................................... 20 TABLE 14. STREAM INPUT/OUTPUT FUNCTIONS............................................................................................ 21 TABLE 15. MISCELLANEOUS FUNCTIONS ...................................................................................................... 23 TABLE 16. COMPILER DEFINES FOR DIFFERENT CARD TYPES ..................ERROR! BOOKMARK NOT DEFINED. TABLE 17. IMPORT LIBRARY AND DLL NAMES FOR DIFFERENT DEVICES .................................................... 31 TABLE 18. LIBRARY NAMING CONVENTION.................................................................................................. 31 TABLE 19. CONFIGURATION FILES ................................................................................................................ 32 TABLE 20. API LIBRARY EXCEPTIONS .......................................................................................................... 34 TABLE 21. GETFPGA CODES AND PARAMETERS........................................................................................... 198 TABLE 22. SETFPGA CODES AND PARAMETERS ........................................................................................... 199 TABLE 23. GETSIGNALINGINFO CODES AND PARAMETERS .......................................................................... 201

IX

1. Introduction
The GL T1/E1 Application Development Toolkit is an application programming interface (API) library that provides functions to access a wealth of GL Communications T1/E1 features. The toolkit consists of: Device Driver Analyzer Application API library implemented as a DLL Header and import library files This guide and reference manuals Sample code The Application Development Toolkit can be used to develop new applications that use GL Communications T1/E1 cards. The toolkit supports Windows XP and later operating systems and provides C++ class library to access hardware features. Only one application can access cards of the same type. If there are several different types installed, several applications (one per type) can be running simultaneously.
Note: Before one starts developing: 1. Install the devices into the PC as described in GLs users manual 2. Install the corresponding device driver(s) and the basic software provided by the GL Communications Inc. as described in GLs users manual. 3. User provided applications to verify whether hardware and software installation is correct.

1.1 Obsolete and Internal (Low Level) Functions

Most of the functions comprising the API library are intended to be used by all applications. However, there are two small groups of functions (see reference): obsolete and internal that should be treated differently.

1.1.1 Obsolete Functions

These functions are saved for the backward compatibility with the existing applications and should not be used in new software development. They will be removed in future API library versions.

1.1.2 Internal (low level) Functions

These functions should be used only if there is no general (high level) function available to achieve the same goal. The following picture demonstrates the system hierarchy:

T 1 Application

E1 Application

T 1 API Library

E1 API Library

T 1 Device Driver

E1 Device Driver

T 1 Cards

E1 Cards

Figure 1. System Hierarchy

1.2 Symbol Conventions

This document uses the following symbols: - warnings - notes
followed by the warning text
followed by the text of note

- see also followed by the function names - sample code

followed by the example source code

Function Naming Conventions The toolkit API library functions use the following conventions: function name starts with a verb followed by a function group name and optional descriptive name, for example, CheckDr or ResetDrRegisters the first parameter of member functions is usually a device number starting with one and not exceeding number of installed devices the second parameter is usually a descriptive function name in the function group sharing the same function name time slots specified as a parameter have type BYTE and start from zero function names returning bool start with Check verbs used as the function prefix: Set, Reset, Read, Write, Enable, Disable, Check, Insert, Get, Resync, Select, Deselect, Load function groups: Mode, Codec, Port, Dr, Fr, Ber, Ts, Multi to specify mode, codec, port, driver, framer, bit error rate, timeslots and status function groups accordingly Function Calling Conventions The API library uses standard C++ exception mechanism to handle error conditions. This handling is chosen in favor of error codes because: it produces more robust code makes client code cleaner and easier to understands guaranties that most of the errors are caught at an early development phase provides consistent error recovery mechanisms The following two exception groups are used internally by the API library: enum GlComExceptions interface errors DWORD DriverAndSystemErrors driver and system errors To handle errors properly the client application code using the API library should incorporate code into try {} catch {} blocks.

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Must be first member function called!!! ... } catch (GlComExceptions except) { GlcMsg( "Driver Interface Error", "Exception description: %s", GetExceptionDescription( except ) ); return 11; } catch ( DWORD lastError ) { GlcMsg( "Driver Error", "GetLastError() = %ul", lastError ); return 12; } catch (...) { printf("Unexpected internal error\n"); return 13; }

2 Programmers Guide
This section explains how to use the API library in applications. It does not cover all the details for each function. The functions reference section covers all the details for each particular function. Read Redme.txt file supplied with examples before building the toolkit examples.

2.1 Creating and Initializing Interface Object

To use API library the GlComInterface object must be created and initialized. Only one GlComInterface object can be used in an application. This object controls all the cards of the corresponding type installed on the machine. Multiple applications cannot control the same type of cards, the application that starts first seizes controls over the cards and the next applications will not. Furthermore, if another application is already using the cards, the exception ExceptCardsInUse will be thrown and it should be handled by the application. If multiple types of cards are installed on the system, several applications can run concurrently, each handling different type(s) of cards. To control several different types of cards, the application should be linked with multiple libraries, each one controlling single device type.
Always destroy GlComInterface object while exiting application. Failing to do so will make devices inaccessible for future use till the system is rebooted. Do not stop debugger using GlComInterface, the debugger will terminate the process leaving the object GlComInterface running.
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( true, GL_CARD_TYPE_DPCI_DMA ); // Must be 1st function called!!! ... } // Local variable Ifc is destroyed automatically when leaving the scope try // Variable created on the heap with new operator must be destroyed explicitly { GlComInterface* pIfc = new GlComInterface(); pIfc->Initialize(true, GL_CARD_TYPE_DPCI_DMA); ... delete pIfc; // !!! Always delete GlComInterface created by new operator }

int main(int argc, char** argv) { try { GlComInterface Ifc; // Create a device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be first member // function called!!! // false specifies that hardware settings // will not be initialized BYTE devCount = (BYTE)Ifc.GetNoOfDevicesInstalled(); // devices installed #ifdef _DEBUG GlcEnableDbgMsg( false ); #endif this // By default in DEBUG build all the exceptions // thrown by the API library will be preceeded by // a message box unless explicitly disabled by // function. For console application the message // box is usually inconvenient and can be // suppressed by specifying false as a parameter } catch (GlComExceptions except) // Catch interface exceptions first { printf( "Driver interface error. Exception description: %s\n", GetExceptionDescription( except ) );//Textual description of the exception return 11; } catch ( DWORD lastError ) // Catch device driver error, see WinError.H { printf( "Driver error. GetLastError() = %ul\n", lastError ); return 12; } catch (...) // Other exceptions { printf("Unexpected internal error\n"); return 13; } return 14; }

2.2 Using Built-in Debugging Features

The API library has a built in debugging facility. For performance reasons this facility is enabled only in the DEBUG builds of the applications when _DEBUG is defined: #define _DEBUG However, even in the debug builds the facility can be disabled by calling the function GlcEnableDbgMsg( false ). By default the debugging is enabled in DEBUG builds. We recommend having the debugging enabled for GUI applications.

There is another API library debugging feature that is always enabled. Use functions GlcGetLastErrorMsg() to get internal errors descriptions.

2.3 Function Parameters

Most functions validate parameters. If a parameter is invalid the appropriate GlComExceptions exception is thrown: ExceptInvParm1 the first parameter is invalid ExceptInvParm2 the second parameter is invalid, etc.
bRet = Ifc.CheckFr( 0, _EfrIsReceiveLossOfSync); // Causes ExceptInvParm1 // because Device number should be 1..NumberOfInstalledDevices and cannot be 0

2.4 Function Groups

The API library consists of the following function groups: Initialization and Termination functions Configuration functions Mode Codec functions Port functions Buffer functions Register functions Driver functions Framer functions Bit Error Rate functions Timeslot functions Pattern file functions Stream I/O functions Miscellaneous functions

2.5 Initialization and Termination functions

Function Name Initialize CheckCard CheckCardIo CheckCardMemory LoadDefaultConfig ReadHardwareConfig InitializeCodec ImplementTxIsr ImplementRxIsr Description Initializes cards Checks card I/O and memory Check card I/O Checks card memory Loads framer and driver chip registers, Reads I/O address, base memory address and IRQ Initializes codec Starts/stops interrupt service for Tx Starts/stops interrupt service for Rx

Table 1. Initialization Functions 8

Applications usually do not have to call all the functions directly to initialize the cards. When Initialize(true) or Initialize() (true is the default) is invoked the following functions are called: ReadHardwareConfig LoadDefaultConfig InitializeCodec CheckCard ImplementTxIsr Additionally the true parameter: initializes framer and driver according to the default.cfg file, loads Xilinx file, sets Codec default parameters, initializes time slot assignor and setting mode, checks input/output, memory and interrupts. If Initialize(false) is specified most of the hardware settings remains unchanged: Hardware and default configuration is not loaded Codec and Framer settings remain unchanged Xilinx file is not loaded Mode and timeslot assignment remain unchanged Memory and I/O are not checked
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... } catch (GlComExceptions except)

2.6 Configuration Functions

These functions are used to query device configuration parameters. Function Name GetMaxTimeslot GetMaxDeviceCount GetNoOfDevicesInstalled GetIoBaseAddr GetMemOffset GetInterrupt1 Description Returns maximum time slot number for the devices Returns maximum number of devices supported by device driver Returns number of devices installed and configured Returns base I/O address Returns memory offset Returns interrupt number

GetMultiFrameSize GetMultiFrameDuration GetIdleCode GetNoOfFramesPerMF GetMultiFrameSize GetMultiFrameDuration GetUsableSoftBufferSize GetNoOfMultiFramesPerSoft Buffer GetProtocolBytesPerMs GetNoOfFramesPerSoftBuffer

Returns multiframe size Returns multiframe duration Returns idle code used for transmission Returns number of frames per multiframe Returns multiframe size Returns duration of multiframe Returns usable software buffer size Returns number of multiframes fit in software buffer Number of bytes transferred per mSec full frame Returns number of frames fit in software buffer

Table 2. Configuration Functions

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... printf("Frames in Multiframe = %d", Ifc.GetNoOfFramesPerMF(SelectedDeviceNo)); #ifdef T1 BitsInMltFrm = 193 * Ifc.GetNoOfFramesPerMF(); #else // E1 BitsInMltFrm = 256 * Ifc.GetNoOfFramesPerMF(); #endif } catch (GlComExceptions except) { ... }

2.7 Mode Functions

Function Name CheckMode SetMode Description Checks whether a particular mode is set Sets a mode

Table 3. Mode Functions One of the following three modes is used: Monitor Terminate Bridge
bool b1; GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!!

10

Ifc.SetMode( SelectedDeviceNo, _SetBridgeMode ); b1 = Ifc.CheckMode ( SelectedDeviceNo, _IsBridgeModeSelected); Ifc.SetMode( SelectedDeviceNo, _SetMonitorMode ); b1 = Ifc.CheckMode ( SelectedDeviceNo, _IsMonitorModeSelected); Ifc.SetMode( SelectedDeviceNo, _SetTerminateMode ); b1 = Ifc.CheckMode ( SelectedDeviceNo, _IsTerminateModeSelected);

2.8 Codec functions

This group of functions controls Codec features. Function Name InitializeCodec SetCodec ResetCodec GetCodec EnableCodec DisableCodec SetCodecInterfaceLatch ResetCodecInterfaceLatch CheckCodecTxRxLatch Table 4. Codec Functions Description Initializes codec Sets gain, Rx/Tx timeslots, sets clock to recovered, internal or external, sets CASF Resets to BER Queries gain, timeslot and BER settings Enables speaker, VF transmit, and drop insert Disables speaker, VF transmit, and drop insert Sets Codec interface latch Resets Codec interface latch Checks interface latch status for Tx or Rx

GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! /********************************************************************/ /* Get current settings for the current device */ /********************************************************************/ TxTs = Ifc.GetCodec(DevNo, _GetTxTimeslot); // Read this setting from driver RxTs = Ifc.GetCodec(DevNo, _GetRxTimeslot); // Read this setting from driver RxGain = Ifc.GetCodec(DevNo, _GetGainForVfRx ); // Read VF gain for Rx TxGain = Ifc.GetCodec(DevNo, _GetGainForVfTx ); // and TX bSpeaker = Ifc.CheckCodec(DevNo, _IsSpeakerOn ); bInsert = Ifc.CheckCodec(DevNo, _IsVfTxOn ); Ifc.DisableCodec(DevNo, _TurnOffSpeaker ); // If was On set Off Ifc.EnableCodec(DevNo, _TurnOnSpeaker); // If was Off set On Ifc.DisableCodec(DevNo, _TurnOffVfTx ); // If was On set Off Ifc.EnableCodec(DevNo, _TurnOnVfTx); // If was Off set On Ifc.SetCodec( DevNo, _SetRxTimeslot, (BYTE)timeslot ); Ifc.SetCodec( DevNo, _SetTxTimeslot, (BYTE)timeslot ); Ifc.SetCodec( DevNo, _SetGainForVfRx, (BYTE)gain ); Ifc.SetCodec( DevNo, _SetGainForVfTx, (BYTE)gain );

11

2.9 Port Input/Output Functions

This group of functions controls reading and writing to 82c55s A, B and C hardware ports. Function Name ReadPort WritePort Table 5. Port I/O Functions
GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! BYTE SelectedDeviceNo = 1; . . . for (cPort='A'; cPort <='C'; cPort++) printf("Port%c= %02X ", cPort, Ifc.ReadPort( SelectedDeviceNo, cPort ) );

Description Reads from a port Writes to a port

2.10 Register Functions

This group of functions controls reading and writing to hardware registers for driver, framer and codec chips. Function Name ReadRegister WriteRegister Table 6. Register Functions
try { GlComInterface Ifc; Ifc.Initialize(false); ... for (;;) { for (i=0; i < 8; i++) printf("Frm%X=%02X i, Ifc.ReadRegister( i, Ifc.ReadRegister( i, Ifc.ReadRegister( i, Ifc.ReadRegister( ); for (i=8; i < 11; i++) printf("Frm%X=%02X RxC%X=%02X TxC%X=%02X\n", i, Ifc.ReadRegister( SelectedDeviceNo, IoCtlCode, (BYTE)i ), i, Ifc.ReadRegister( SelectedDeviceNo, _ReadRxAudioRegister, (BYTE)i ), i, Ifc.ReadRegister( SelectedDeviceNo, _ReadTxAudioRegister, (BYTE)i ) ); for (i=11; i < 16; i++) printf("Frm%X=%02X\n", i, Ifc.ReadRegister( SelectedDeviceNo, IoCtlCode, (BYTE)i ) ); } } // Device driver interface object // Must be first member function called!!!

Description Reads from a register Writes to a register

Drv%X=%02X RxC%X=%02X TxC%X=%02X\n", SelectedDeviceNo, IoCtlCode, (BYTE)i ), SelectedDeviceNo, _DrReadRegister, (BYTE)i ), SelectedDeviceNo, _ReadRxAudioRegister, (BYTE)i ), SelectedDeviceNo, _ReadTxAudioRegister, (BYTE)i )

12

2.11 Buffer Functions

This group of functions controls software buffers. The device driver uses some of these buffers and therefore these functions should be used carefully. Function Name GetRxGlobalBuffer0 GetRxGlobalBuffer1 GetTxGlobalBuffer0 GetTxGlobalBuffer1 GetGlobalBufferSize GetActiveTxSoftBuffer GetActiveRxSoftBuffer GetMultiRxGlobalBuffer0 GetMultiRxGlobalBuffer1 GetMultiTxGlobalBuffer0 GetMultiTxGlobalBuffer1 GetActiveRxBufPtr GetActiveTxBufPtr GetPrevRxBufPtr GetPrevTxBufPtr GetRxActiveBufferNumber GetTxActiveBufferNumber GetRxActiveBufferOffs GetTxActiveBufferOffs FillTxGlobalBuffers Table 7. Buffer functions
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... if ( bSendIdle ) for( i = 0 ; i < NoOfSamplesPerTs; i++ ) { pTempBuf = Ifc.GetMultiTxGlobalBuffer0(SelectedDeviceNo-1) + i*NoOfChannels + StartTs; memset( pTempBuf , Ifc.GetIdleCode(), TsCount ); pTempBuf = Ifc.GetMultiTxGlobalBuffer1(SelectedDeviceNo-1) + i*NoOfChannels + StartTs; memset( pTempBuf , Ifc.GetIdleCode(), TsCount ); } }

Description Get driver global receive buffer0 pointer (obsolete) Get driver global receive buffer1 pointer (obsolete) Get driver global transmit buffer0 pointer (obsolete) Get driver global transmit buffer1 pointer (obsolete) Returns receive/transmit global buffers size. Returns running count of transmit software buffers Returns running count of receive software buffers Get driver global receive buffer0 pointer for a device Get driver global receive buffer1 pointer for a device Get driver global transmit buffer0 pointer for a device Get driver global transmit buffer1 pointer for a device Get active global receive buffer pointer Get active global transmit buffer pointer Get inactive global receive buffer pointer Get inactive global transmit buffer pointer Get sequence number of the active receive global buffer Get sequence number of the active transmit global buffer Current driver position in the active global receive buffer Current driver position in the active global xmit buffer Fills transmit buffers with idle code or idle byte strings

13

2.12 Cross Port Functions

Cross Port functions are used to set card in one of three crossport modes: Normal (no Cross Port ) Cross Port Through Cross Port Transmit Cross Port functions always affect both ports on the board regardless through which port on the same board the functions were invoked. In the normal mode ports are not interconnected internally. In the cross port through mode that is maintained when device is powered off, the relays cross connect ports on the board and sets ports in bridge mode. In the cross port transmit mode the data programmatically transmitted on port 1 goes out on port 2 and data transmitted on port 2 goes out on port 1. In other words, when application transmits data on port 1 in normal and cross port through mode it goes out on port 1, while in cross port transmit it goes out on port 2. Function Name SetCrossPort GetCrossPort Description Set cross port mode to one of the EnT1E1CrossPortMode modes Returns EnT1E1CrossPortMode, the current cross port setting

2.13 Driver Functions

This group controls device driver service functions for the GL Communications cards. Function Name EnableDrInterruptEvents DisableDrInterruptEvents GetDr CheckDr Description Enables device driver event notification Disables device driver event notification Queries driver information, equalizer control, line length, inband network loop setup, Rx line attenuation, and jitter attenuation Checks if one of the following is set: LOS , network loop, AIS, DFMO, ES overrun, ES underrun, driver open, BIST, 12dB, 26dB or 36dB equalizer gain, analog, remote, local or network loopback is set, Transmit all ones is set, Rx monitor mode is selected or whether built-in self test is active Controls equalizer, sets 12dB, 26dB or 36dB equalizer gain Enables analog, remote, local or network loopback, 14

SetDr EnableDr

Function Name

DisableDr

ResetDrRegisters CheckDrJitter SetDrJitter DrvGetNoOfDevicesInstalled Table 8. Driver Functions

Description enables network loopback detect, sets transmission all ones, enables inbound network loopback up/down, and enables Rx monitor mode Disables jitter attenuation, disables analog, remote, local or network loopback, disables network loopback detect, resets transmission all ones, and disables inbound network loopback up/down Resets driver registers Checks if the driver jitter is set to 3Hz or 6Hz, whether jitter attenuation is enabled, whether jitter attenuation is set on Rx or Tx Sets jitter to 3Hz or 6Hz, sets jitter attenuation on Rx or Tx Returns number of cards installed and configured

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! bRet = Ifc.CheckDr(SelectedDeviceNo, _DrIsNLoopPerStatusSet); bRet = Ifc.CheckDr( SelectedDeviceNo, _DrIsEsOvrTransitionSet ); bRet = Ifc.CheckDr( SelectedDeviceNo, _DrIsEsUnTransitionSet ); bRet = Ifc.CheckDr( SelectedDeviceNo, _DrIsLosPerStatusSet ); bRet = Ifc.CheckDr( SelectedDeviceNo, _DrIsLosPerStatusSet ); bRet = Ifc.CheckDr( SelectedDeviceNo, _DrIsAisPerStatusSet); Ifc.EnableDr( SelectedDeviceNo, _DrEnableLocalLoopback); Ifc.DisableDr( SelectedDeviceNo, _DrDisableLocalLoopback); Ifc.EnableDr( SelectedDeviceNo, _DrEnableRemoteLoopback); Ifc.DisableDr( SelectedDeviceNo, _DrDisableRemoteLoopback); }

15

2.14 Framer Functions

This group of functions controls framing attributes. Some of the functions are available only for T1 or only for E1 cards. Please refer to the reference section to determine whether a particular function is applicable. CheckFr Description T1 and E1 Checks whether: error counter is saturated, autoresync is enabled, local framer loopback is active, T1 only. Checks whether: resync is in progress, blue and/or yellow alarm is detected, B8ZS or COFA is on, frame error is detected, carrier loss is detected, bipolar violation counter is saturated, zero suppression B7 is set, TxB8ZS is active, D4 yellow allarm S bit is set, ESF yellow alarm FDL is set, Rx COFA detect is selected, D4 or ESF is selected, SLC96, T1DM are selected, resync algo10Bits set, resync uses FT bits, OOF criteria is 2of4, resync OOF is on, TX yellow and/or blue alarms are enabled, external S bit is enabled, FF or 7F is Tx idle code, robbed bit signal is enabled, external CRC is enabled, external FT FPS is enabled, outdata NRZ is selected, a channel is selected for Tx idle code, channel is selected for transparent, Rx channel is selected for code insert. E1 only. Checks whether: receive loss of sync, CAS multiframe resync, frame resync, receive unframed all ones, receive signaling all ones, Tx/Rx DMA is set, receive remote alarm, Rx/Tx CCS or CAS mode selected, resync criteria is fixed, CAS MF resync criteria is fixed, CAS multiframe sync criteria is fixed, Rx/TX CRC4 and HDB3 are enabled, Tx multiframe starts with FAS, Tx 100 or 50 duty cycle, Tx signaling all ones, Tx extra, national or international bits are set, external signaling bits are set, unframed all ones, Tx remote alarm is set. Checks if timeslot is selected for Tx idle code Masks all interrupts, interrupts only or interrupts specified by a mask Unmasks all interrupts, interrupts only or interrupts specified by a mask

CheckFrTimeslotSelectedForTxIdleCo de

DisableFrInterrupts EnableFrInterrupts

16

GetFr GetFrErrorCounter

EnableFr

DisableFr

SetFr

SelectFr

DeselectFr

Description Reads receive status register (RSR) or interrupt mask register (IMR) T1 and E1 Retrieves bipolar error counter T1 only Retrieves out of frame and errorred superframe counters E1 only Retrieves CRC4 and frame error counters T1 and E1 Enables autoresync and local loopback T1 only Enables TxB8ZS, yellow and blue alarms, external S bit, robbed bit signal, external CRC, external FT FPS. E1 only Enables Tx/Rx CRC4 and HDB3, Tx signaling all ones, Tx extra, national and international bits, external signaling bits, unframed all ones, Tx remote alarm, Tx DMA and multiframe start with FAS T1 and E1 Disables autoresync and local loopback T1 only Disables TxB8ZS, yellow and blue alarms, external S bit, robbed bit signal, external CRC, external FT FPS. E1 only Disables Tx/Rx CRC4 and HDB3, Tx signaling all ones, Tx extra, national and international bits, external signaling bits, unframed all ones, Tx remote alarm, Tx DMA and multiframe start with FAS T1 Only Sets zero suppression B7, zero suppression transparent, OOF criteria 2of4 or 2of5 E1 Only Rx/Tx CCS or CAS mode, CAS multiframe sync criteria fixed or not fixed T1 Only Selects yellow alarm D4 B2 or S bit, or yellow alarm ESF FDL or S bit, D4/ESF, SLC96, T1DM, Tx idle code 7F or FF, out data unipolar, outdata NRZ E1 Only Tx 100 or 50 duty cycle T1 Only Deselects all channel for Tx idle code, all channels for transparent and all Rx channels for code insert E1 Only

17

SelectFrTimeslot

DeselectFrTimeslot

DetectFrRx ResyncFr

EnableUnframedInput DisableUnframedInput SetFrBits GetFrBits Table 9. Framer Functions

Description Deselects all timeslots for Tx idle codes T1 and E1 Selects channel for Tx idle code T1 Only Selects channel for transparent or code insert. T1 and E1 Deselects channel for Tx idle code T1 Only Deselects channel for transparent or code insert. T1 Only Detects Rx B8ZS or COFA T1 and E1 Causes forced resync T1 Only Resyncs: Algo10 or Algo24 bits, using FT bits, using FT FA bits, on OOF or OOF RCL E1 Only Resyncs with criteria fixed or not fixed, or CAS multiframe criteria fixed or not fixed Enables unframed input Disables unframed input E1 Only Sets Tx national, international or extra bits Retrieves Tx national, international or extra bits

GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! BYTE DevNo = 1; . . . #if defined (T1) FrameErrors = _Ifc.GetFrErrorCounter( DevNo, TfrGetErroredSuperFrameCounter ); #else //if defined (E1) FrameErrors = Ifc.GetFrErrorCounter( DevNo, _EfrGetFrameErrorCounter ); #endif

18

2.15 Bit Error Rate Functions

Function Name LoadStaticBerIntFpga ReadBerErrXlinx InsertBerError SetBerTxRx ResetBerTxRx LoadBerStaticPattern Description Loads static BER pattern Gets number of logic errors Inserts single or bipolar violation error Selects Tx or Rx to read number of errors Resets Tx or Rx BER Loads static BER pattern

Table 10. BER Functions

GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! BYTE _DevNo = 1; . . . #ifdef T1 DWORD IoCtlCode = _TfrIsResyncInProgress; #else DWORD IoCtlCode = _EfrIsReceiveLossOfSync; #endif if (Ifc.CheckFr( _DevNo, IoCtlCode )) { if (Ifc.CheckDr( _DevNo, _DrIsLosTransitionSet ) ) _bT1Carrier = false; else _bT1Carrier = true; if (_bUnframed == true) { #if defined(T1) Ifc.SetBerTxRx( _DevNo, _SelectRxBer ); Ifc.ReadBerErrXlinx( _DevNo ); // Clear Error Counter after Resync #endif } else if ( !_bT1Carrier ) { _bPattern = false; Ifc.SetBerTxRx( _DevNo, _SelectRxBer ); Ifc.ReadBerErrXlinx( _DevNo ); // Clear Error Counter after Resync bT1Sync = false; _bPatternLossInThisSec = true; } }

19

2.16 Timeslot Functions

This group of functions sets timeslot relevant attributes. The timeslot parameters are usually 0-23 for T1 and 0-31 for E1. Function Name WriteTsAssigner WriteTsAssignerRange EnableMultiTs EnableMultiTsAll CheckMultiTsAvailable CheckMultiTsAllAvailable SaveMultiTsStatus RestoreMultiTsStatus Description Specifies start or end timeslot1 Specifies start and end timeslots, i.e. range of timeslots 2 Enables or disables a timeslot for a device 3 Enables or disables all timeslots for a device Checks whether a timeslot is enabled for a device Checks whether all timeslots are enabled for a device Saves timeslot status for a device Restores timeslot status for a device

Table 11. Timeslot Functions

GlComInterface Ifc; // Device driver interface object Ifc.Initialize(false, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! BYTE DevNo = 1; . . . for (int i = 0; i <= (NoOfChannels-1); i++) { if ( Ifc.CheckMultiTsAvailable( DevNo, i) ) SetCheckButtonChecked(i); }

2.17 Pattern File Functions

These functions are used to control Xlinx pattern files. Function Name Description GetDefaultPatternFileName Retrieves default pattern file name SetDefaultPatternFileName Sets default pattern file name GetCurrentPatternFileName Retrieves current pattern file name SetCurrentPatternFileName Sets current pattern file name GetDefaultPpPatternFileName Retrieves default PP pattern file name SetDefaultPpPatternFileName Sets default parallel port pattern file name (EPP.BIN) Table 12. Pattern File Functions

1 2

Used with BER example or drop insert Used with BER example or drop insert 3 Higher level functions maintain time slot usage for transmit direction

20

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... #ifdef CARD_V3 Ifc.SetDefaultPatternFileName("T1PASS.BIN"); #else Ifc.SetDefaultPatternFileName("LTPASS.BIN"); #endif } catch (GlComExceptions except) { ... }

2.18 Stream I/O Functions

Use these functions to read/write data to/from one or more channels
These functions are members of BioStream class NOT GlComInterface class!!!

Function Name BioStream SetReadChannelMask SetWriteChannelMask SetReadSafeMarginMultiFrames SetWriteSafeMarginMultiFrames SetReadSafeMarginBytes SetWriteSafeMarginBytes GetReadMissedBytesCount GetWriteMissedBytesCount Reset Read Write ReopenRead ReopenWrite Reopen FillTxChannels

Description Initializes and sets read/write channel masks Sets channel mask to read Sets channel mask to write Sets safe margins for reading Sets safe margins for writing Sets safe margins for reading Sets safe margins for writing Bytes missed when client application is too slow (Non-blocking only) when client application is too fast Resets current position and counters Reads T1/E1 channel(s) data Writes T1/E1 channel(s) data Reopens receive stream Reopens transmit stream Reopens both receive and transmit streams Fills channels with idle code or idle byte string

Table 13. Stream Input/Output Functions

21

// Receive and retransmit received data GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! . BioStream Bs(&Ifc, SelectedDeviceNo, 0xC0000000 ); // Use channels 1 and 2 DWORD WriteSize = 12*24; BYTE Buf[65536]; DWORD XmitLen; Bs.SetWriteSafeMarginBytes( 16*WriteSize ); Bs.SetReadSafeMarginBytes( 0 ); for(;;) { try { XmitLen = Bs.Read( Buf, WriteSize, true ); Bs.Write( Buf, XmitLen, true, true ); } catch (GlComExceptions exception) { printf( "%s missed %d ", GetExceptionDescription( exception ), Bs.GetWriteMissedBytesCount() ); Bs.Reopen(); } }

2.19 Miscellaneous functions

Function Name GlcEnableDbgMsg CheckGlcEnableDbgMsg GlcMsg GlcDebugMsg GlcCriticalMsg Description Enables/Disables built-in error diagnostic in DEBUG builds Checks if built-in error diagnostic in DEBUG builds is enabled Displays error message box with parameter list similar to printf Same as GlcMsg but works only for the DEBUG builds DEBUG: displays error message box and throws an exception with the last system error throw (DWORD)GetLastError() RELEASE: throws the exception only Gets textual description of the API internal errors In DEBUG builds displays the error message box and optionally throws an exception (controlled by parameter) Returns textual description of internal API library exceptions Gets the API library version Gets the device driver version Sets on-hook or off-hook

GlcGetLastErrorMsg DisplayError GetExceptionDescription GetApiVersion GetVersion SetOnHook

22

Table 14. Miscellaneous Functions

if ((ConfigFile = fopen("HARDWARE.CFG", "rt")) == NULL) { char szFullFilename[MAX_PATH]=""; GetCurrentDirectory(MAX_PATH, (LPTSTR)szFullFilename); strcat(szFullFilename,"\\HARDWARE.CFG"); GlcDebugMsg( pszFuncName, "Cannot open %s file", (LPCTSTR)szFullFilename ); bIsValid = false; }

2.20 Subchannel Input/Output

Each T1/E1 timeslot provides 64 kbps throughput. However some industry implementations are using 56 kbps per timeslot and even multiples of 8 kbps subchannels on each timeslot. The BitStream class allows splitting one or more timeslots into 8 kbps subchannels and reading them separately. This class can be used in conjunction with BioStream class that reads, for example, the first bit from several timeslots and then BitStream class assembles these bits into continuous stream of bytes.
BitStream BitStr; BitStr.SetBitMask(0xFE); // 56 kbps BitStr.SetInvert(true); // MSB->LSB (reverse bits in each byte) BioStream Bs; // ByteBufLen = Bs.Read( pInpBuf, LenToRead, false ); // read multiple timeslots BitBufLen = BitStr.Extract( pInpBuf, ByteBufLen, pBitBuf, BitBufLen );

This example reads a continuous stream from several timeslots into an intermediate buffer using the BioStream class and then it uses BitStream class to Extract 56 kbps payload Invert bits MSB to LSB It produces byte output that has integral number of bytes. Consecutive calls to BitStream::Extract assemble leftover bits from the previous call into continuous stream. The OutBitStream class is opposite to BitStream and is used to write to 8 kbps subchannels. This class uses bits from the input buffer to fill in the output buffer according to the subchannel mask. The unused bits are filled with zeroes or ones. To merge subchannels use two OutBitStream objects with non-interleaving subchannel masks and XOR the resulting streams (buffers) byte by byte.
OutBitStream Obs( 0xFE, true ); // 56 kbps, invert OutLen = Obs.Put( pBuf, BufLen, pOutBuf, OutLen ); // Get bits from pBuf and // put into pOutBuf stream

23

2.21 HDLC Encoding/Decoding

HDLC encodes frames using zero bit insertion after each consecutive five ones. Decoding removes these inserted bits. One or more 0x7E flags separate frames. More than six consecutive ones are not allowed. The data link specification is published in the ITU-T Q.921 standard. Frames consist of address, control and frame check sequence (FCS). HDLC is widely used in ISDN and other higher level protocols. MsbStuffBits function is used to insert zero bits after five consecutive ones and also inserts flags between frames. CalculateCrc function is used to create FCS field.
// Putting out just flags MsbStuffBits( pInRecord, // not used in this particular case, 0, // putting just flags pOutBuf, // pointer to output buffer OutLen, // (IN/OUT) - output buffer length RemBits // (In/Out) Number of flag bits, if more than 8 ); // multiple flags will be put a flag per each 8 bits // Put two flags first and then encode a HDLC frame DWORD FlagBits = 16; // two flags MsbStuffBits( pInFrameBytes, // not used in this particular case, FrameLength, // frame length pOutBuf, // pointer to output buffer OutLen, // (IN/OUT) - output buffer length FlagBits // (In/Out) Number of flag bits, if more than 8 ); // multiple flags will be put a flag per each 8 bits

HDLC Decoding uses BitRemove class. This class not only decodes HDLC frames but also gathers statistics and timing information.
// BitRemove Br; Br.parse( pInpBuf, InputBufLen, pOutBuf, OutBufLen ); BrOutputList* pList = (BrOutputList*)( pOutBuf ); BrOutputFrame* pFr = &pList->OutputFrames; TotalFrCount += pList->pFrameCount + pList->pErrFrameCount; DWORD Time = pFr->TotalInputBytesBeforeFrame * 125 / Channels; // Time in mkS while ( bNotEndOf Frames ) { BrOutputFrame* pFrame = pFr; size_t len = pFrame->Length; if ( pFrame->bOkFrame) { BYTE Crc[2]; CalculateCrc( pFrame->Data, len, Crc ); if ( Crc[0] == 0xE2 && Crc[1] == 0xF0 ) Trec.ErrorFlag = 0; else Trec.ErrorFlag = ErrorFlagCrc; } pFr = (BrOutputFrame*)&(pFr)->Data[pFr->Length]; // Next frame }

24

The BitRemove::parse produces a list of output frames in the buffer supplied by the client application. Each frame has an error flag indicating that frame has a correct or erroneous encoding. Client must call CalculateCrc function to verify FCS field. The best way to iterate through frames is:
pFr = (BrOutputFrame*)&(pFr)->Data[pFr->Length]; // Next frame

2.22 Facility Data Link

FDL is 4Hz dedicated channel for system messages in 193E (ESF) T1 framing format. The FDL feature implemented by the FdlStream class can be used only for T1 devices. For ESF framing format this class allows to read and write FDL channel, framing pattern sequence (FPS) and CRC (cyclic redundancy check) bits.
In normal circumstances FPS and CRC bits can be filled in by the on-board hardware. For specialized applications, however, these bits can be filled in using FdlStream interface, for example, to insert different kind of errors.

For D4 format ( 193s) the FdlStream class allows to read and write Ft and Fs (terminal and system framing ) bits.
// Reading GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! Ifc.SelectFr( DevNo, _TfrSelectEsf); Ifc.LoadIntFpga( DevNo, "LTFDLX.BIN" ); // Necessary to enable FDL feature !!! FdlStream Fdl( &Ifc, DevNo, FdlEsfMaskData, 0 ); // FDL channel, read only DWORD SafeReadMargins = 3 * 32; Fdl.SetReadSafeMarginBytes( SafeReadMargins ); // Optional // To sync multiple cards for(all cards) { Fdl.SyncOpenRead(); } Fdl.Read( pBuf, BufLen ); // Ifc.LoadIntFpga(DevNo, "LTPASS.BIN"); // Restore Xilinx when done with FDL !!!

// Writing GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! Ifc.SelectFr( DevNo, _TfrSelectEsf); Ifc.LoadIntFpga( DevNo, "LTFDLX.BIN" ); // Necessary to enable FDL feature !!! FdlStream Fdl( &Ifc, DevNo, 0, FdlEsfMaskData ); // FDL channel, write only Fdl.Write(pBuf, BufLen ); Ifc.LoadIntFpga(DevNo, "LTPASS.BIN"); // Restore Xilinx when done with FDL !!!

25

When writing FPS or CRC bits some extra setup is required to enable these operations normally done by hardware.
// Writing GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! Ifc.SelectFr( DevNo, _TfrSelectEsf); Ifc.LoadIntFpga( DevNo, "LTFDLX.BIN" ); // Necessary to enable FDL feature !!! FdlStream Fdl( &Ifc, DevNo, 0, FdlEsfMaskFps ); // write frame pattern sequence Ifc.EnableFr( DevNo, _TfrEnableExternalFtFps ); // Required to write FPS !!! Fdl.Write(pBuf, BufLen ); // When done DisableFr(DevNo, _TfrDisableExternalFtFPS); // Enable hardware FPS writing Ifc.LoadIntFpga(DevNo, "LTPASS.BIN"); // Restore Xilinx when done with FDL !!!

2.23 Memory Mapped Files and VarRecBuf Class

MemFile class uses Win32 memory mapped input/output features. This feature allows mapping file to memory and to read or modify it using memory pointer instead of file I/O access functions. This feature is usually much faster and much more efficient than traditional file I/O. The VarRecBuf is designed to use in conjunction with MemFile to handle list of variable length records in memory. It allows very fast direct access to records minimizing disk I/O for huge files.
// Reading MemFile m_MemFile; VarRecBuf m_VrBuf; m_MemFile.Init( (LPCTSTR)m_szFileName, m_BufSize, m_pBuffer, false ) ); // R/O open will open file and return mapped memory in m_pBuffer DWORD Offs = offsetof(FileHeader,VarRecords); m_Comment = (LPCTSTR)((FileHeader*)m_pBuffer)->szComment; // Map VarRecBuf to this file mapped buffer m_VrBuf.Init( m_pBuffer+Offs, m_BufSize-Offs, *((PDWORD)m_pBuffer) ); // printf("%lu Frames\n", m_VrBuf.GetRecordCount()); m_VrBuf.GetRecord( RecNo, (PBYTE&)pFrame, Len ); m_MemFile.Close(); m_VrBuf.Close();

26

// Writing MemFile m_MemFile; VarRecBuf m_VrBuf; m_MemFile.Init( (LPCTSTR)m_szFileName, m_BufSize, m_pBuffer, true ) // R/W open will open file and return mapped memory in m_pBuffer DWORD Offs = offsetof(FileHeader,VarRecords); m_VrBuf.Init( m_pBuffer+Offs, m_BufSize-Offs); RecCnt = m_VrBuf.AddTwoPartRecord( (PBYTE)&Header, sizeof(Header), pFrameData, FrameLen ); // Assemble record from two parts // m_MemFile.Flush(); // Call this function when you want to take over control // when updated data is flushed to disk, normally Windows do it automatically m_MemFile.SetEndOfFile( offsetof(FileHeader,VarRecords) + m_VrBuf.GetUsableSize() ); // Truncate file to get rid of unused // bytes before closing file m_MemFile.Close(); m_VrBuf.Close();

2.24 Dynamic List Buffer

The DynamicListBuf is a very specialized implementation of the linked list usually used as a parameter for functions. This list has extremely fast allocation but only append and clear functions to modify the list. It also has only one way to iterate using first/next methods. The list is allocated in supplied memory buffer.
// Iteration DynamicListBuf HdlcList; //. bNotListEnd = HdlcList.first( pFrame, FrameLen, offs ); while ( bNotListEnd ) { OutLen = RemLen; m_RemBits += ExtraFlags * 8; MsbStuffBits( pFrame, // pointer to input buffer to stuff FrameLen,// input buffer length pOut, // pointer to output buffer OutLen, // (OUT) - output buffer length m_RemBits // (In/Out) Number of flag bits ); pOut += OutLen; // To continue appending encoded frames OutLen = ( RemLen -= OutLen ); bNotListEnd = HdlcList.next( pFrame, FrameLen, offs ); } // Filling In DynamicListBuf Hl(4096); // Initial buffer size, buffer will expand // automatically when needed //. Hl.erase(); // Clear while ( bContinue ) { // Fill it in Hl.push( pNextItem, ItemLength ); } if ( !Hl.isEmpty() ) printf("List has %lu items\n), Hl.count(); DynamicListBuf Hl2(Hl); // Create copy DynamicListBuf Hl3; Hl3 = Hl; // Assignment is OK also Hl.erase(); // Hl becomes empty, but Hl2 and Hl3 contain original data

27

2.25 C Interface
In addition to the GlComInterface, a C version of GlComInterface is available. This interface is called CGlComInterface, and it behaves no differently than the normal GlComInterface with the exception of a few changes. Rather than creating a CGlComInterface object and calling member functions from it (a feature not available in C), once the CGlComInterface object is created, functions are called without a host object prefix. Only one CGlComInterface object can be used in an application. Since there can only be one CGlComInterface object, the functions are performed on the created object. As with GlComInterface, to use API library the CGlComInterface object must be created and initialized. Only one CGlComInterface object can be used in an application. This object controls all the cards of the corresponding type installed on the machine. Multiple applications cannot control the same type of cards, the application that starts first seizes controls over the cards and the next applications will not. Furthermore, if another application is already using the cards, the exception ExceptCardsInUse will be thrown and it should be handled by the application. If multiple types of cards are installed on the system, several applications can run concurrently, each handling different type(s) of cards.
Always destroy CGlComInterface object while exiting application. Failing to do so will make devices inaccessible for future use till the system is rebooted. Do not stop debugger while using CGlComInterface, the debugger will terminate the process leaving the object CGlComInterface running.
try { CreateCGlComInterface(); // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... DestroyCGlComInterface() } // Object NOT destroyed automatically when // leaving the scope. Must do explicitly.

28

int main(int argc, char** argv) { try { CreateCGlComInterface(); GlInitialize(false, 0);

// Device driver interface object // Must be first function called after // object creation!!! // false specifies that hardware settings // will not be initialized BYTE devCount = GlGetNoOfDevicesInstalled(); // devices installed #ifdef _DEBUG // By default in DEBUG build all the exceptions CGlcEnableDbgMsg( false ); // thrown by the API library will be preceeded by #endif // a message box unless explicitly disabled by //this function. For console application the // messagea box is usually inconvenient and can be // suppressed by specifying false as a parameter } catch (GlComExceptions except) // Catch interface exceptions first { printf( "Driver interface error. Exception description: %s\n", GetCExceptionDescription( except ) );//Textual description of the exception return 11; } catch ( DWORD lastError ) // Catch device driver error, see WinError.H { printf( "Driver error. GetLastError() = %ul\n", lastError ); return 12; } catch (...) // Other exceptions { printf("Unexpected internal error\n"); return 13; } return 14; }

2.26 Periodic File Saving

CFileCapturingOperations is an object designed to facilitate the capture of data into sequential files. Instead of capturing data into one large single file, captured data can be seamlessly written to files based upon size or time criteria. An API has been developed for the software developer who has the desire to to take advantage of CFileCapturingOperations sequential capture capabilities. Automated Continuous Capture (ACC) takes advantage of this object. A console application utilizing the features of CFileCapturingOperations will be supplied with the toolkit. It basically consists of the following major steps and will provide insight and a good grasp of its methodology: 1. Setting the card type, GL_CARD_TYPE_DPCI_DMA for HD boards, or GL_CARD_TYPE_DPCI_USB for USB boards, or GL_CARD_TYPE_DPCI_UNIV for Universal boards or GL_CARD_TYPE_USB_NG for tProbe boards

29

DWORD CardType = GL_CARD_TYPE_DPCI_DMA; // can be only used with HD boards, or else an exception

2.

Loading initialization data, and initializing the board

PeriodicLoadData perhd; // initialization data CFileCapturingOperations filecap; // periodic filesaving object GlComInterface Ifc; if (inifile.ReadIniFile(argv[1], perhd) == true)// read settings from ini file which is supplied as // commandline argument { Ifc.Initialize(!perhd.initialization, CardType); // initialize card }

3.

Setting up control loop, with the following important setting

CAPMESSAGES *CapMsgs; // contains messages for the user filecap.ProcessFileSavingFlags(&CapMsgs); // runs capture utility

CapMsgs notifies the user of capture status ProcessFileSavingFlags performs the actual process of capturing data and writing to file 4. Closing the object and the sequential files
filecap.CloseAllPeriodicFiles(); // close periodic files

The initialization file, which is invoked as an argument on the commandline, consists of the following settings:
// framingformat options - D4, ESF (T1), CAS, CCS, CASCRC, CCSCRC (E1) FRAMINGFORMAT=CasCRC // cards #1, #2, and #3 DEVICEMASK = 1-3 // 0 - if sequential, 1 - if date/time FILENAMETYPE = 0 SEQFILENAMEPREFIX = temp // tsmask - timeslots selected, for example, valid input for timeslots can be something // like "1-5,11,13-14,19" TSMASK=5-31 // filenames will have the sequence temp000, temp001, , temp999 SEQFILENAMEDIGITS=3 SEQFILENAMESUFFIX=.PCM DATETIMEFILENAMESUFFIX = .PCM // %Y year, %M month, %D day, %H hour of day, %I - minute DATETIMEFILENAMEMASK = %Y%M%D_%H%I // 0 - bytes, 2 time SAVELIMITTYPE = 0 // if based on time, use 05:25 for 5 hours, 25 minutes SIZECOUNTLIMIT = 234333 // time limit in nanoseconds, 360,000,000,000 ns is 360 seconds TIMELIMIT = 360000000000 // RecycleType, 0 - Keep n latest files, 1 - stop after n files, 2 - unrestricted RECYCLETYPE = 2 RECYCLEFILECOUNT = 7FFFFFFF // where captured files are stored FILEDIRECTORY = g:\sequentialfiles // ignore ENABLEFILTER = off

30

3 Building Applications Using the API Library

This section describes compilation and linker parameters that are required to build applications that use device driver interface library. The API libraries are provided for Microsoft Visual C++ v5.0 and Borland C++ Builder v3.0 The API Library requires multithreading option of the compiler. Otherwise there are no restrictions on the type of applications built with the library. MFC and non-MFC applications or components are supported. #include <glcomifc.h> should be used in application and the glcomifc.h must be on the include path. The compiler alignment on 8 bytes boundary or #pragma pack(8) must be used. The following #define symbols should be specified for all the card types: WIN32,_WINDOWS,_MBCS The following #define symbols should be specified for HD, USB, Universal and tProbe cards: T1_TYPE,LICENSE_SERIAL or E1_TYPE,LICENSE_SERIAL

3.1 Linker
The API library import library for the API DLL must be linked with the application. The import library names end with D for debug and have no D at the end for release versions. HD, USB, Universal, tProbe T1 HD, USB, Universal, tProbe E1
GlcIfcT1.lib and GlcIfcT1.dll - release, GlcIfcTd.lib and GlcIfcTd.dll - debug GlcIfcE1.lib and GlcIfcE1.dll - release, GlcIfcEd.lib and GlcIfcEd.dll - debug

Table 15. Import Library and DLL Names for Different Devices The naming convention is described in the following table. Compiler Prefix Debug/Release GlcIfc for HD, USB, D debug Universal and tProbe Table 16. Library Naming Convention

31

3.2 Configuration Files

Applications using the API library must have the following configuration files installed in the directory where the application resides, otherwise the device driver will not be able to initialize. Configuration File Name Usage T1Default.CFG T1 configuration parameters E1Default.CFG E1 configuration parameters T1PASS.BIT, E1PASS.BIT Pattern for HD PCI *.BIT and *.CFG files USB and tProbe BitFiles with binary files, *.CFG Universal Table 17. Configuration Files

3.3 Building Examples.

The CardType.txt file is used to specify card type. Please refer to Readme.txt file supplied with examples for details. Copy driver interface DLL and configuration files into the exe directory before running the examples. Read Readme.txt file for more details.

32

4 Driver API Library Reference

4.1 Exceptions
enum GlComExceptions { ExceptAssert, ExceptDriverNotOpen, ExceptNotInitialized, ExceptInvParm1, ExceptInvParm2, ExceptInvParm3, ExceptInvParm4, ExceptInvParm5, ExceptInvParm6, ExceptInvParm7, ExceptInvParm8, ExceptInvParm9, ExceptInvDeviceIndex, ExceptCardsInUse, ExceptCheckCardIo, ExceptCheckCardMemory, ExceptLoadDefaultConfig, ExceptAltBufferNotAvailable, ExceptOpenFile, ExceptCreateObj, ExceptDeadlockTimeout, ExceptInvalidFunctionCall, ExceptUnderRun, ExceptOverRun, ExceptAlgorithm, ExceptNotImplemented, ExceptInterruptNotRunning }; The API Library takes full advantage of the C++ exceptions. If parameters passed to a function are incorrect or an unexpected error occurred in the library a GlComExceptions exception will be thrown and should be caught by the application. To make development easier, instead of just reporting an invalid parameter the library throws ExceptInvParm1 if the first parameter is incorrect, ExceptInvParm2 if the second parameter is incorrect etc.

33

Exception ExceptAssert ExceptDriverNotOpen ExceptNotInitialized ExceptInvParm1 ExceptInvParm2 ExceptInvParm3 ExceptInvParm4 ExceptInvParm5 ExceptInvParm6 ExceptInvDeviceIndex ExceptCardsInUse ExceptCheckCardIo ExceptCheckCardMemory ExceptLoadDefaultConfig ExceptAltBufferNotAvailable ExceptOpenFile ExceptCreateObj ExceptDeadlockTimeout

Reason Assertion failed Driver is not open Driver is not initialized Invalid parameter 1 Invalid parameter 2 Invalid parameter 3 Invalid parameter 4 Invalid parameter 5 Invalid parameter 6 Device number exceeds number of installed devices Another application uses the driver Card I/O is not operating properly Card memory read/write does not return correct data Loading default configuration failed Alternative buffer is not available Error opening a file Error creating an object API library deadlock timed out

Table 18. API Library Exceptions Additionally to these exceptions the API library throws exception of type DWORD when the system call to the device driver returned an error. The value of this exception is the returned value of GetLastError(). Application should use the try {} catch {} blocks to handle the possible hardware and configuration errors properly.
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(true, GL_CARD_TYPE_DPCI_DMA); // Must be 1st function called!!! ... } catch (GlComExceptions except) { GlcMsg( "Driver Interface Error", "Exception description: %s", GetExceptionDescription( except ) ); return 11; } catch ( DWORD lastError ) { GlcMsg( "Driver Error", "GetLastError() = %ul", lastError ); return 12; } catch (...) { printf("Unexpected internal error\n"); return 13; }

34

4.2 Enabling Built-in Diagnostic Messages in DEBUG Builds

This function has an effect in the DEBUG builds only. It enables or disables error message boxes display. By default in the DEBUG builds the built-in diagnostic is enabled.

C++ C

void GlcEnableDbgMsg( bool bEnable ); void CGlcEnableDbgMsg( bool bEnable );

Parameters: bool bEnable if true enables, otherwise disables diagnostic error message boxes Returns: Nothing
Its recommended not to disable the diagnostic messages for the GUI applications. For console applications the diagnostic messages may be placed by system on the task bar and some users may prefer to disable them while debugging applications. The diagnostic messages are not displayed in the RELEASE builds.
#ifdef _DEBUG GlcEnableDbgMsg( false ); #endif // Disable MsgBoxes in debugging mode

4.3 Check Whether the Built-in Diagnostic Messages are Enabled

This function is a companion to GlcEnableDbgMsg and should be used only in the DEBUG builds.

C++ C

bool CheckGlcEnableDbgMsg(); bool CheckCGlcEnableDbgMsg();

Parameters: None Returns: Bool true if the diagnostic messages are enabled (default), false otherwise
#ifdef _DEBUG GlcEnableDbgMsg( false ); // Disable MsgBoxes in debugging mode bool bDiagnostic = CheckGlcEnableDbgMsg(); // is set to false GlcEnableDbgMsg( true ); bDiagnostic = CheckGlcEnableDbgMsg(); // is set to true #endif

35

4.4 Display Message Box Using printf Formatting

This function simplifies displaying message boxes using formatting strings identical to printf formatting strings.

C++ C

void GlcMsg(LPCTSTR pszTitle, LPCTSTR pszFormat, ... ); void CGlcMsg(LPCTSTR pszTitle, LPCTSTR pszFormat, ... );

Parameters: LPCTSTR pszTitle message box caption (title) LPCTSTR pszFormat formatting string for the message box text identical to the printf formatting string. ... arguments for the formatting string Returns: Nothing
DWORD dw = GetLastError(); GlcMsg("System Error","%s failed. GetLastError returned %u\n",lpszFunction,dw );

GlcDebugMsg, throwDebug, GlcCriticalMsg

4.5 Display Message Box Using printf Formatting in DEBUG Builds Only.
This function simplifies displaying message boxes using formatting strings identical to printf formatting strings in DEBUG builds and does nothing in RELEASE builds.

C++ C

void GlcDebugMsg(LPCTSTR pszTitle, LPCTSTR pszFormat, ... ); N/A

Parameters: LPCTSTR pszTitle message box caption (title) LPCTSTR pszFormat formatting string for the message box text identical to the printf formatting string. ... arguments for the formatting string Returns: Nothing 36

DWORD dw = GetLastError(); GlcDebugMsg("Error","%s failed. GetLastError returned %u\n",lpszFunction,dw );

GlcMsg, throwDebug, GlcCriticalMsg

4.6 Format and Display Critical Error Message Box and Throw an Exception.
This function formats error message and appends GetLastError() information in DEBUG builds only. Then it throws a DWORD exception using throw (DWORD)GetLastError();

C++ C

void GlcCriticalMsg(LPCTSTR pszTitle, LPCTSTR pszFormat, ... ); N/A

Parameters: LPCTSTR pszTitle dialog box caption, if pszTitle == NULL the default Critical Error is used. LPCTSTR pszFormat formatting string identical to printf formatting string ... parameters for printf formatting string Returns: Nothing
GlcCriticalMsg( "GlComInterface::OpenVxD", "%s Device Driver not found/loaded.", DeviceDriverName );

GlcCriticalMsg is equivalent to GlcDebugMsg + throw (DWORD)GetLastError().

GlcMsg, GlcDebugMsg, throwDebug

37

4.7 Format Error Message Box in DEBUG Builds only. Append GlComExceptions Textual Description and Throw a GlComExceptions Exception.
This function formats and display message in DEBUG builds only and throws GlComExceptions exception in DEBUG and Release builds. It appends the textual description of the exception to the formatting string passed in the parameters. C++ void throwDebug(GlComExceptions Exception, LPCTSTR pszTitle, LPCTSTR pszFormat, ... ) N/A C Parameters: GlComExceptions Exception exception to throw (both DEBUG and RELEASE) LPCTSTR pszTitle message box capture (title), ignored in RELEASE builds LPCTSTR pszFormat - printf formatting string, ignored in RELEASE builds ... printf formatting string Returns: Nothing
throwDebug( exception, "Error", "GlComInterface::LoadDefaultConfig Cannot process configuration file \"%s\"", pszDefFileName );

GlcMsg, GlcDebugMsg, GlcCriticalMsg

4.8 Get GlComExceptions Textual Description

C++ C
LPCTSTR GetExceptionDescription ( GlComExceptions exception ); LPCTSTR GetCExceptionDescription ( GlComExceptions exception );

Parameters: GlComExceptions exception exception number to get description for Returns: LPCTSTR textual description 38

try { GlComInterface Ifc; Ifc.Initialize( false ); . . . // Device driver interface object // Do not set default hardware settings

} catch (GlComExceptions exception) { printf( "Driver interface error. Exception description: %s\n", GetExceptionDescription( exception ) ); return 11; } catch ( DWORD lastError ) { printf( "Driver error. GetLastError() = %lu\n", lastError ); return 12; } catch (...) { printf("Unexpected internal error\n"); return 13; } return 14; }

Use this function to include useful information into error messages for API Library errors.

4.9 Get Textual Description of an Internal Error

C++ C
LPCTSTR GlcGetLastErrorMsg() N/A

Parameters: None Returns: LPCTSTR textual description

This function should be used when the GlComInterface::Initialize() fails and in some other cases to find out the reason for an internal error. Usually the reason is in the incorrect hardware or device driver configuration and missing configuration files.

39

try { GlComInterface Ifc; // Device driver interface object // Do not set default hardware settings Ifc.Initialize( false, GL_CARD_TYPE_DPCI_DMA ); . . .

} catch (GlComExceptions exception) { printf( "Driver interface error. Exception description: %s\n", GetExceptionDescription( exception ) ); return 11; } catch ( DWORD lastError ) { printf( "Driver error. GetLastError() = %lu\n", lastError ); return 12; } catch (...) { printf( "Last error: %s\n", GlcGetLastErrorMsg() ); printf("Unexpected internal error\n"); return 13; } return 14; }

4.10 Creating a C Interface Object

This function creates a CGlComInterface object.

C++ C

N/A bool CreateCGlComInterface();

Parameters: None Returns: bool true if object was created, otherwise false

try { CreateCGlComInterface(); GlInitialize(true, 0); ... DestroyCGlComInterface() }

// Device driver interface object // Must be first function called after object // creation! // Object NOT destroyed automatically when // leaving the scope. Must do explicitly.

DestroyCGlComInterface

40

4.11 Destroying a C Interface Object

This function destroys the existing CGlComInterface object.

C++ C

N/A void DestroyCGlComInterface();

Parameters: None Returns: Nothing

try { CreateCGlComInterface(); GlInitialize(true, 0); ... DestroyCGlComInterface() }

// Device driver interface object // Must be first function called after object // creation! // Object NOT destroyed automatically when // leaving the scope. Must do explicitly.

CreateCGlComInterface

4.12 Checking if C Interface Object Exists

This function checks if a CGlComInterface object has been created and is currently in existance.

C++ C

N/A bool IsObjectCreated();

Parameters: None Returns: bool true if CGlComInterface object exists, otherwise false

try { CreateCGlComInterface(); GlInitialize(true, 0); ... DestroyCGlComInterface() }

// Device driver interface object // Must be first function called after object // creation! // Object NOT destroyed automatically when // leaving the scope. Must do explicitly.

DestroyCGlComInterface

41

4.13 Get Pointer to Device Driver Information for a Device

Obtains miscellaneous device driver information.

C++ C

DevicePtr GetMultiSharedDevicePtr(int Index ); DevicePtr GlGetMultiSharedDevicePtr(int Index );

Parameters: int Index 0 relative device index. Returns: DevicePtr pointer to the device driver information structure defined in w32if.h
typedef struct DeviceShare { DWORD PPBaseAddr; DWORD PPIrq; DWORD MemoryAddr; DWORD NoOfFramesPerMF; DWORD BufferSize; Application DWORD buffer DWORD DWORD DWORD DWORD DWORD DWORD //DWORD DWORD DWORD DWORD DWORD DWORD DWORD DWORD } // parallel port base address // parallel port IRQ // memory address // Software buffer shared by VxD and // Max multiframe index in global // // // // // // // // // // // // // // Total no transmitted multiframes Byte offset into current buffer Current active global buffer Total global buffers received Start Channel End Channel Points to Software Rx Buffers Max multiframe index in glb buffer Total no received multiframes Byte offset into current buffer Current active global buffer Total global buffers received Start Channel End Channel

MaxNoOfTxMultiframes; NoOfTxMultiframesCount; TxCurrentPosition; TxActiveBuffer; NoOfTxBuffersFilledCount; TxStartChannel; TxEndChannel; ptrGlobalRxBuffer[2]; MaxNoOfRxMultiframes; NoOfRxMultiframesCount; RxCurrentPosition; RxActiveBuffer; NoOfRxBuffersFilledCount; RxStartChannel; RxEndChannel;

DWORD Flags; //Status Flags, etc Device, *DevicePtr;

DWORD RxActiveBuf = Ifc.GetMultiSharedDevicePtr( SelectedDeviceNo-1)->RxActiveBuffer; if ( m_TrackSoftBuffer < RxActiveBuf ) { if ( m_TrackSoftBuffer != RxActiveBuf - 1 ) { MissingBytes += NoOfSamplesPerTs * TsCount * ( RxActiveBuf - 1 - m_TrackSoftBuffer ); printf("Missing Bytes: %d Bytes\n", MissingBytes); } }

42

4.14 Get Default File Pattern Name

C++ C
LPCTSTR GetDefaultPatternFileName(); LPCTSTR GlGetDefaultPatternFileName();

Parameters: None Returns: LPCTSTR file pattern name

4.15 Set Default File Pattern Name

C++ C
bool SetDefaultPatternFileName(LPCTSTR pszFileName); bool GlSetDefaultPatternFileName(LPCTSTR pszFileName);

Parameters: LPCTSTR pszFileName default file pattern name to set Returns: bool true if set OK, false if fails
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . Ifc.SetDefaultPatternFileName("T1PASS.BIN"); }

4.16 Get Current Pattern File Name

C++ C
LPCTSTR GetCurrentPatternFileName(int Index); LPCTSTR GlGetCurrentPatternFileName(int Index);

Parameters: int Index 0 relative device index Returns: LPCTSTR current pattern file name 43

4.17 Set Current Pattern File Name

C++ C
bool SetCurrentPatternFileName(int Index, LPCTSTR pszFileName); bool GlSetCurrentPatternFileName(int Index, LPCTSTR pszFileName);

Parameters: int Index zero relative device index LPCTSTR pszFileName pattern file name Returns: bool true OK, false failure
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . Ifc.SetCurrentPatternFileName(DeviceNo-1, pszFilename); }

4.18 Get Active Receive Buffer Pointer

Obtains the pointer to the active receive global buffer C++ BYTE* GetActiveRxBufPtr( BYTE DeviceNo )

BYTE* GlGetActiveRxBufPtr( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: BYTE* pointer to the active receive buffer GetActiveTxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferNumber GetTxActiveBufferOffs - one relative device number

44

The device driver uses pairs of receive and transmit buffers to optimize the application interface performance. When the device driver is processing an active buffer the application can safely access the alternative buffer. When the device driver is finished with a buffer it switches to the alternative buffer. It takes approximately one second for device driver to process a global buffer.

4.19 Get Active Transmit Buffer Pointer

Obtains the pointer to the active transmit global buffer C++ BYTE* GetActiveTxBufPtr( BYTE DeviceNo )

BYTE* GlGetActiveTxBufPtr( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: BYTE* pointer to the active transmit buffer GetActiveRxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferNumber GetTxActiveBufferOffs
The device driver uses pairs of receive and transmit buffers to optimize the application interface performance. When the device driver is processing an active buffer the application can safely access the alternative buffer. When the device driver is finished with a buffer it switches to the alternative buffer. It takes approximately one second for device driver to process a global buffer.

- one relative device number

4.20 Get Active Receive Buffer Offset

Obtains the offset of the current driver position in the active receive global buffer C++ DWORD GetRxActiveBufferOffs( BYTE DeviceNo )

DWORD GlGetRxActiveBufferOffs( BYTE DeviceNo )

Parameters: BYTE DeviceNo

- one relative device number

Returns: DWORD offset in the active receive buffer

45

GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetTxActiveBufferNumber GetTxActiveBufferOffs

4.21 Get Active Transmit Buffer Offset

Obtains the offset (current driver position) in the active transmit global buffer C++ DWORD GetTxActiveBufferOffs( BYTE DeviceNo )

DWORD GlGetTxActiveBufferOffs( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: DWORD offset in the active transmit buffer GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferNumber - one relative device number

4.22 Get Inactive Receive Buffer Pointer

Obtains the pointer to the inactive receive global buffer C++ BYTE* GetPrevRxBufPtr( BYTE DeviceNo )

BYTE* GlGetPrevRxBufPtr( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: BYTE* pointer to the inactive receive buffer - one relative device number

46

The device driver uses pairs of receive and transmit buffers to optimize the application interface performance. When the device driver is processing an active buffer the application can safely access the alternative buffer. When the device driver is finished with a buffer it switches to the alternative buffer. It takes approximately one second for device driver to process a global buffer.

GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferNumber GetTxActiveBufferOffs

4.23 Get Inactive Transmit Buffer Pointer

Obtains the pointer to the inactive transmit global buffer C++ BYTE* GetPrevTxBufPtr( BYTE DeviceNo )

BYTE* GetPrevTxBufPtr( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: BYTE* pointer to the inactive transmit buffer GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevRxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferNumber GetTxActiveBufferOffs
The device driver uses pairs of receive and transmit buffers to optimize the application interface performance. When the device driver is processing an active buffer the application can safely access the alternative buffer. When the device driver is finished with a buffer it switches to the alternative buffer. It takes approximately one second for device driver to process a global buffer.

- one relative device number

47

4.24 Get Active Receive Buffer Sequential Number

Obtains sequence number of the current receive global buffer

C++ C

DWORD GetRxActiveBufferNumber( BYTE DeviceNo ) DWORD GlGetRxActiveBufferNumber( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: DWORD sequence number of the current receive global buffer GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferOffs, GetTxActiveBufferNumber GetTxActiveBufferOffs
This function returns the number of global buffers received and this number should change in normal receive conditions each second

- one relative device number

4.25 Get Active Transmit Buffer Sequential Number

Obtains the sequence number of the current transmit global buffer

C++ C

DWORD GetTxActiveBufferNumber( BYTE DeviceNo ) DWORD GlGetTxActiveBufferNumber( BYTE DeviceNo )

Parameters: BYTE DeviceNo Returns: DWORD sequence number of the current transmit global buffer GetActiveRxBufPtr, GetActiveTxBufPtr, GetPrevRxBufPtr, GetPrevTxBufPtr, GetRxActiveBufferNumber, GetRxActiveBufferOffs, GetTxActiveBufferOffs - one relative device number

48

This functions returns number of global buffers transmitted and this number should change in normal receive conditions each second

4.26 Get Data Transmission Rate

Obtains data transmission rate for full frame T1 or E1 independent of framing format

C++ C

DWORD GetProtocolBytesPerMs() DWORD GlGetProtocolBytesPerMs()

Parameters: None Returns: DWORD bytes per mSec (1/1000 Sec)

This function returns the number of bytes transferred per millisecond not depending on protocol (T1/E1) and framing for full frame (all channels used).

4.27 Fill Both Global Transmit Buffers With Idle Code

Fills all global buffers with the idle code specified as a parameter

C++ C

void FillTxGlobalBuffers( BYTE DeviceNo, BYTE FillerByte ); void GlFillTxGlobalBuffers( BYTE DeviceNo, BYTE FillerByte );

Parameters: BYTE DeviceNo BYTE FillerByte Returns: Nothing

Use overloaded FillTxGlobalBuffers to fill with byte strings

- one relative device number - idle code value to use for filling in both global transmit buffers

49

4.28 Fill Both Global Transmit Buffers With a Byte String

Fills entire global buffers with the idle code specified as a parameter C++ void FillTxGlobalBuffers( BYTE DeviceNo, BYTE* pFillerBytes, DWORD Length ); void GlFillTxGlobalBuffers( BYTE DeviceNo, BYTE* pFillerBytes, C DWORD Length ); Parameters: BYTE DeviceNo - one relative device number BYTE* pFillerBytes - byte string pointer to use as a filler DWORD Length - byte string length Returns: Nothing
Use overloaded FillTxGlobalBuffers to fill with a byte

4.29 Get Drivers Currently Selected Device Number (Obsolete)

C++ C
int GetCurrentlySelectedDeviceNo(); int GlGetCurrentlySelectedDeviceNo();

Parameters: None Returns: int currently selected device number

50

4.30 Get Number of Physical Devices Installed and Configured

C++ C
int GetNoOfDevicesInstalled() int GlGetNoOfDevicesInstalled()

Parameters: None Returns: int number of devices installed and configured

Use this function to execute operations on all the installed devices

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . BYTE devCount = Ifc.GetNoOfDevicesInstalled(); for (BYTE DevNo=1; DevNo <= devCount; DevNo++) Ifc.EnableDr( DevNo, _DrEnableNetworkLoopbackDetect ); }

51

4.31 Get Number Of Devices Found During Driver Initialization

C++ C
int GetNoOfDevicesFound() int GlGetNoOfDevicesFound()

Parameters: None Returns: int number of devices found during driver initialization
This is a backward compatibility function. Use GetNoOfDevicesInstalled() to obtain the number of installed and configured devices on the system.

GetNoOfDevicesInstalled

4.32 Get Receive/Transmit Global Buffer Pointers

These four functions return the address of a global receive or transmit software buffer used as device driver data interface. C++ BYTE* GetMultiRxGlobalBuffer0(int Index ); BYTE* GetMultiRxGlobalBuffer1(int Index ); BYTE* GetMultiTxGlobalBuffer0(int Index ); BYTE* GetMultiTxGlobalBuffer1(int Index ); BYTE* GlGetMultiRxGlobalBuffer0(int Index ); C BYTE* GlGetMultiRxGlobalBuffer1(int Index ); BYTE* GlGetMultiTxGlobalBuffer0(int Index ); BYTE* GlGetMultiTxGlobalBuffer1(int Index ); Parameters: int Index zero based device index, should be less then GetNoOfDevicesInstalled(). Returns: BYTE* - global buffer pointer requested

52

The device driver uses pairs of receive and transmit buffers to optimize the application interface performance. When the device driver is processing an active buffer the application can safely access the alternative buffer. When the device driver is finished with a buffer it switches to the alternative buffer. It takes approximately one second for device driver to process a buffer.

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . int TsCount = EndTs - StartTs +1; int NoOfSamplesPerTs = BufferSize / NoOfChannels; DWORD RxActiveBuf = Ifc.GetMultiSharedDevicePtr(SelectedDeviceNo-1)>RxActiveBuffer; PBYTE pGlobalBuffer; DWORD BytesToWrite; if ( m_TrackSoftBuffer < RxActiveBuf ) { //m_ProgressBar.StepIt( ); if ( m_TrackSoftBuffer != RxActiveBuf - 1 ) { MissingBytes += NoOfSamplesPerTs * TsCount * ( RxActiveBuf - 1 - m_TrackSoftBuffer ); printf("Missing Bytes: %d Bytes\n", MissingBytes); } m_TrackSoftBuffer = RxActiveBuf; BYTE *pTempBuf; if( m_TrackSoftBuffer & 0x00000001 ) pGlobalBuffer = Ifc.GetMultiRxGlobalBuffer0(SelectedDeviceNo-1); else pGlobalBuffer = Ifc.GetMultiRxGlobalBuffer1(SelectedDeviceNo-1); for (int i = 0; i < NoOfSamplesPerTs; i++ ) { pTempBuf = pGlobalBuffer + i*NoOfChannels + StartTs; memcpy( &pData[i * TsCount], pTempBuf, TsCount ); // Copy next ts range } // Check if we are over the limit BytesToWrite = NoOfSamplesPerTs * TsCount; if (bLimited && TotalWritten + BytesToWrite > BytesCnt) BytesToWrite = BytesCnt - TotalWritten; TotalWritten += fwrite( pData, 1, BytesToWrite, fh ); } } // end try

53

4.33 Select Current Driver Device Number (Obsolete)

C++ C
int SelectCurrentDeviceNo(int DeviceNumberToBeSelected); int GlSelectCurrentDeviceNo(int DeviceNumberToBeSelected);

Parameters: int DeviceNumberToBeSelected one relative device number to be selected Returns: int device number selected

4.34 Synchronize Devices

Resets all dynamically updated parameters in the device share structure (DevicePtr) for all the devices.

C++ C

bool SyncDevices(); bool GlSyncDevices();

Parameters: None Returns: bool true success, false failure

Resets counters for the global buffers

4.35 Get Idle Code

Obtains the idle code used for transmission. C++ BYTE GetIdleCode();

BYTE GlGetIdleCode();

Parameters: None Returns: BYTE idle code (filler byte)

54

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . PBYTE pTempBuf; if ( bSendIdle ) for( i = 0 ; i < NoOfSamplesPerTs; i++ ) { pTempBuf = Ifc.GetMultiTxGlobalBuffer0(SelectedDeviceNo-1) + i*NoOfChannels + StartTs; memset( pTempBuf , Ifc.GetIdleCode(), TsCount ); pTempBuf = Ifc.GetMultiTxGlobalBuffer1(SelectedDeviceNo-1) + i*NoOfChannels + StartTs; memset( pTempBuf , Ifc.GetIdleCode(), TsCount ); } }

4.36 Get Number of Frames per Multiframe

C++ C
int GetNoOfFramesPerMF(BYTE DeviceNo ); int GlGetNoOfFramesPerMF(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int number of frames per multiframe
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . #ifdef T1 if (Ifc.GetNoOfFramesPerMF(1) == 12) // check for framing format num_sigbits = 2; else num_sigbits = 4; #endif }

55

4.37 Get Multiframe Size

C++ C
int GetMultiFrameSize(BYTE DeviceNo ); int GlGetMultiFrameSize(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int multiframe size in bytes

4.38 Get Multiframe Duration

C++ C
float GetMultiFrameDuration(BYTE DeviceNo ); float GlGetMultiFrameDuration(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: float multiframe duration in ms (1/1000 sec)
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . MultiFrameTime = Ifc.GetMultiSharedDevicePtr(DeviceIndex)->NoOfRxMultiframesCount * Ifc.GetMultiFrameDuration(DeviceIndex + 1); }

56

4.39 Get Usable Software Buffer Size

C++ C
int GetUsableSoftBufferSize(BYTE DeviceNo ); int GlGetUsableSoftBufferSize(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int buffer size in bytes
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . BufferSize = Ifc.GetUsableSoftBufferSize(SelectedDeviceNo); assert ( pData = new BYTE[(BufferSize / NoOfChannels)*(EndTs - StartTs +1)] ); if ( fh = fopen(szFileName, "w" ) ) bCapturing = true; ... // start capturing to the file }

4.40 Get Number of Multiframes Per Software Buffer

C++ C
int GetNoOfMultiFramesPerSoftBuffer(BYTE DeviceNo ); int GlGetNoOfMultiFramesPerSoftBuffer(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int number of multiframes fit in software buffer
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . SignalingBufferSize = Ifc.GetNoOfMultiFramesPerSoftBuffer(1) * NoOfChannels * DeviceCount; // size of signaling storage }

57

GetNoOfFramesPerSoftBuffer

4.41 Get Number of Frames Per Software Buffer

C++ C
int GetNoOfFramesPerSoftBuffer(BYTE DeviceNo ); int GlGetNoOfFramesPerSoftBuffer(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int number of frames fit in software buffer
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize( false ); // Do not set default hardware settings . . . FramesCnt = Ifc.GetNoOfFramesPerSoftBuffer(CurrentSelDev); }

GetNoOfMultiFramesPerSoftBuffer

4.42 Get Active Global Transmit Software Buffer Index

Checks which global transmit buffer, 0 or 1, is active

C++ C

int GetActiveTxSoftBuffer(BYTE DeviceNo ); int GlGetActiveTxSoftBuffer(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int 0 if global transmit buffer 0 is active, 1 if global transmit buffer 1 is active

58

GetActiveRxSoftBuffer

4.43 Get Active Global Receive Software Buffer Index

Checks which global receive buffer 0 or 1 is active

C++ C

int GetActiveRxSoftBuffer(BYTE DeviceNo ); int GlGetActiveRxSoftBuffer(BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: int 0 if global receive buffer 0 is active, 1 if global receive buffer 1 is active GetActiveTxSoftBuffer

59

4.44 Initialize Interface

These functions MUST be called after GlComInterface constructor and before any other functions. This function initializes driver and optionally initializes hardware.

C++ C

void Initialize(bool bInitializeHardware = true, DWORD CardType=0 ); void Initialize(bool bInitializeHardware, DWORD CardType);

Parameters: bool bInitializeHardware (default true for C++) initializes hardware (see notes) DWORD CardType Numerical value of GL Communications card type The CardType parameter must be set to: GL_CARD_TYPE_DPCI_DMA for HD PCI cards GL_CARD_TYPE_USB for USB cards GL_CARD_TYPE_UNIV for Universal cards GL_CARD_TYPE_USB_NG for tProbe cards Returns: Nothing.
If driver or hardware are not setup correctly or configuration files (*.bin and *.cfg) are missing in the application directory, an exception will be thrown.
The driver interface initialization: opens the device driver selects device creates global transmit and receive memory buffers initializes the device driver reads hardware configuration file

If parameter bInitializeHardware == true the function also initializes onboard 8255 chip loads FPGA initializes codec turns off VF output and speaker sets default codec transmit and receive gain checks card memory and input/output writes timeslot assigner and sets terminate mode refreshes framer information

60

try { GlComInterface Ifc; Ifc.Initialize(); . . . }

// Device driver interface object // Set default hardware settings

4.45 Check Card I/O and Memory

C++ C
void CheckCard( BYTE DeviceNo ); void GlCheckCard( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing. Throws an exception if checking fails.
Calls CheckCardIo(DeviceNo) and CheckCardMemory(DeviceNo) to check I/O and card memory.

CheckCardIo, CheckCardMemory

4.46 Check Card Input/Output

C++ C
void CheckCardIo( BYTE DeviceNo ); void GlCheckCardIo( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing. Throws an exception if checking fails.
Writes framer register, reads it back and then compares data

61

CheckCardMemory, CheckCard

4.47 Check Card Memory

C++ C
void CheckCardMemory( BYTE DeviceNo ); void GlCheckCardMemory( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing. Throws an exception if checking fails.
sets inward loopback of the framer chip, then writes one multiframe, reads it back and then compares data

CheckCardIo, CheckCard

62

4.48 Load Default Configuration (Internal Function)

Reads the default configuration file and initializes framer chip registers and driver chip registers. C++ void LoadDefaultConfig( BYTE DeviceNo );

void GlLoadDefaultConfig( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing. Throws an exception if fails.

4.49 Initialize IRQ, Memory Offset and Base Address (Internal Function)
Initializes IRQ, memory offset and base address using data from the HARDWARE.CFG file. C++ bool ReadHardwareConfig();

bool GlReadHardwareConfig();

Parameters: None Returns: bool true if succeed, false if fails

63

4.50 Codec Initialization (Internal Function)

C++ C
void InitializeCodec ( BYTE DeviceNo ); void GlInitializeCodec ( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing.
This function is invoked in GlComInterface::Initialize when the initialize hardware parameter is set to true.

4.51 Read from a Port (Internal Function)

This function reads one byte from A, B or C on-board port. C++ BYTE ReadPort ( BYTE DeviceNo, char Port );

BYTE GlReadPort ( BYTE DeviceNo, char Port );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) char Port port to read from. Valid values are A, B, C. This parameter is not case sensitive, therefore a, b and c can also be specified. Returns: BYTE data byte read from the port specified by the Port parameter.
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . for (cPort='A'; cPort <='C'; cPort++) printf("Port%c= %02X ", cPort, Ifc.ReadPort( SelectedDeviceNo, cPort ) ); }

WritePort

64

4.52 Write to a Port (Internal Function)

This function writes a byte to the specified on-board port. C++ void WritePort ( BYTE DeviceNo, char Port, BYTE Data );

void GlWritePort ( BYTE DeviceNo, char Port, BYTE Data );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) char Port port to write to. Valid values are A, B, C. This parameter is not case sensitive, therefore a, b and c can also be specified. BYTE data byte to write to the port specified by the Port parameter. Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #ifdef T1 if ( strNewPattern == "LTSTAT.BIN" || _bUnframed ) _bDs0SelectionEnabled = false; // Disable selection 56k/64k else _bDs0SelectionEnabled = true; // Enable selection 56k/64k if (_bDs0_56) { _pIfc->WritePort(_DevNo, 'B', _pIfc->ReadPort(_DevNo, 'B') | 0xC0 ); // Make TLINKERRS and TABCDERR1 HIGH Sleep(10); _pIfc->WritePort(_DevNo, 'B', _pIfc->ReadPort(_DevNo, 'B') & 0x3F ); //Make TLINKERRS and TABCDERR1 low } #endif }

ReadPort

65

4.53 Loading Internal FPGA

C++ C
bool LoadIntFpga(BYTE DeviceNo, LPCTSTR pszFilename ); bool GlLoadIntFpga(BYTE DeviceNo, LPCTSTR pszFilename );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) LPCTSTR pszFilename file name to load data from Returns: bool - true success, false failure
This function is invoked in GlComInterface::Initialize when the initialize hardware parameter is set to true to load default patterns. Xilinx file name specified in the parameter pszFilename is saved as the current pattern file name.

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . // changing patterns if( (strNewPattern == "T1STAT.BIN") || (strNewPattern == "E1STAT.BIN") || (strNewPattern == "LTSTAT.BIN") || (strNewPattern == "LESTAT.BIN") || (strNewPattern == "LTCSU.BIN") || (strNewPattern == "LECSU.BIN") || (strNewPattern == "LEUCSU.BIN") || (strNewPattern == "LEUSTAT.BIN") ) { #ifdef E1 _pIfc->ResetCodec( _DevNo, _ResetCasf ); #endif _pIfc->LoadStaticBerIntFpga(_DevNo, strNewPattern.c_str(),_StaticPatBits ); } else _pIfc->LoadIntFpga( _DevNo, strNewPattern.c_str() ); }

LoadStaticBerIntFpga, LoadPpXilinxFile, LoadBerStaticPattern, LoadPpXilinxFile

66

4.54 Loading Static BER Internal FPGA

C++ C
bool LoadStaticBerIntFpga(BYTE DeviceNo, LPCTSTR pszFilename, unsigned long StaticBits ); bool GlLoadStaticBerIntFpga(BYTE DeviceNo, LPCTSTR pszFilename, unsigned long StaticBits );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) LPCTSTR pszFilename file name to load data from unsigned long StaticBits static bits Returns: bool - true success, false failure
Xilinx file name specified in the parameter pszFilename is saved as the current pattern file name.

LoadIntFpga, LoadPpXilinxFile, LoadBerStaticPattern, LoadPpXilinxFile

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . // changing patterns if( (strNewPattern == "T1STAT.BIN") || (strNewPattern == "E1STAT.BIN") || (strNewPattern == "LTSTAT.BIN") || (strNewPattern == "LESTAT.BIN") || (strNewPattern == "LTCSU.BIN") || (strNewPattern == "LECSU.BIN") || (strNewPattern == "LEUCSU.BIN") || (strNewPattern == "LEUSTAT.BIN") ) { #ifdef E1 _pIfc->ResetCodec( _DevNo, _ResetCasf ); #endif _pIfc->LoadStaticBerIntFpga(_DevNo, strNewPattern.c_str(), _StaticPatBits ); } else _pIfc->LoadIntFpga( _DevNo, strNewPattern.c_str() ); }

67

4.55 Waiting (Internal Function)

This function waits for start of RMSYNC or TMO. C++ void Wait( BYTE DeviceNo, DWORD IoCtlCode );

void GlWait( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies an event to wait for: _WaitForStartOfRmSync to wait for RMSYNC _WaitForStartOfTmo - to wait for TMO Returns: Nothing

4.56 Fill Transmit Buffers with a Filler Byte (Internal Function)

C++ C
void SetTxBuffers( BYTE DeviceNo, BYTE DataByte, WORD MultiframeSize ); void GlSetTxBuffers( BYTE DeviceNo, BYTE DataByte, WORD MultiframeSize );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE DataByte filler byte WORD MultiframeSize multiframe size Returns: Nothing

68

4.57 Checking Mode

This function checks whether the card is in Terminate, Monitor or Bridge mode.

C++ C

bool CheckMode(BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckMode(BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies a mode to check _IsTerminateModeSelected _IsBridgeModeSelected _IsMonitorModeSelected Returns: bool - true the mode specified by IoCtlCode parameter is set, otherwise it returns false
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . if (Ifc.CheckMode ( SelectedDeviceNo, _IsTerminateModeSelected) ) { mode = ModeTerminate; pszMode = "Terminate"; } else if (Ifc.CheckMode ( SelectedDeviceNo, _IsBridgeModeSelected) ) { mode = ModeBridge; pszMode = "Bridge"; } else //(Ifc.CheckMode ( SelectedDeviceNo, _IsMonitorModeSelected) ) { mode = ModeMonitor; pszMode = "Monitor"; }

SetMode

69

4.58 Setting Mode (Internal Function)

Sets Terminate, Bridge or Monitor Mode

C++ C

void SetMode(BYTE DeviceNo, DWORD IoCtlCode ); void GlSetMode(BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies a mode to set _SetTerminateMode _SetBridgeMode _SetMonitorMode Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetMode( SelectedDeviceNo, _SetMonitorMode ); }

CheckMode
This function is invoked in GlComInterface::Initialize when the initialize hardware parameter is set to true to set the default mode Terminate.

4.59 Write to Timeslot Assigner (Internal Function)

Writes to start or stop timeslot assigner. C++ void WriteTsAssigner ( BYTE DeviceNo, BYTE Timeslot, bool bStart );

void GlWriteTsAssigner ( BYTE DeviceNo, BYTE Timeslot, bool bStart );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() )

70

BYTE Timeslot zero relative timeslot number. When START (bStart == true) is specified this parameter specifies the first timeslot in the timeslot range. When STOP (bStart == false) is specified this parameter should be LastTimeSlot + 1. bool bStart true to start, false to stop Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . WriteTsAssigner( DeviceNo, 0, true ); // start WriteTsAssigner( DeviceNo, NoOfChannels, false ); // stop (last+1) }

Always use pairs of functions, one with bStart = true and another with bStart = false to specify the timeslot range for the timeslot assigner. Use WriteTsAssignerRange ( BYTE DeviceNo, BYTE StartTimeslot, BYTE StopTimeslot ) to specify the range in one call instead of two calls to WriteTsAssigner.

WriteTsAssignerRange

4.60 Specifying the Timeslot Assigner Range

C++ C
void WriteTsAssignerRange ( BYTE DeviceNo, BYTE StartTimeslot, BYTE StopTimeslot ); void GlWriteTsAssignerRange ( BYTE DeviceNo, BYTE StartTimeslot, BYTE StopTimeslot );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE StartTimeslot zero relative start timeslot number. BYTE StopTimeslot zero relative stop timeslot number. This parameter should be LastTimeSlot + 1.

71

Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings // Assign all timeslots WriteTsAssignerRange( DeviceNo, 0, NoOfChannels ); // 0..(NoOfChannels-1) }

If you need to specify the range 0..5 call WriteTsAssignerRange( DeviceNo, 0, 6);

4.61 Writing to Driver, Framer or Audio Registers (Internal Function)

C++ C
void WriteRegister(BYTE DeviceNo, DWORD IoCtlCode, BYTE RegiNo, BYTE Data ); void GlWriteRegister(BYTE DeviceNo, DWORD IoCtlCode, BYTE RegiNo, BYTE Data );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _WriteRxAudRegi writes to a receive audio register _WriteTxAudRegi writes to a transmit audio register _drWriteRegister writes to a driver register _frWriteRegister writes to a framer register (T1 only) _E1frWriteRegister writes to a framer register (E1 only) BYTE RegiNo specifies the register number BYTE Data data to write to the register Returns: Nothing

72

ReadRegister

4.62 Set Codec Gain or Time Slot

C++ C
void SetCodec(BYTE DeviceNo, DWORD IoCtlCode, BYTE Data); void GlSetCodec(BYTE DeviceNo, DWORD IoCtlCode, BYTE Data);

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _SetRxTimeslot set receive time slot _SetTxTimeslot set transmit time slot _SetGainForVfRx set gain for receive in dB _SetGainForVfTx set gain for transmit in dB BYTE Data gain or time slot number depending on the IoCtlCode Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetCodec( SelectedDeviceNo, _SetRxTimeslot, (BYTE)timeslot ); Ifc.SetCodec( SelectedDeviceNo, _SetGainForVfRx, (BYTE)gain ); }

ResetCodec, SetCodec, GetCodec, EnableCodec, DisableCodec, CheckCodec

73

4.63 Set Codec Clock or CASF

Set codec clock to internal, external or recovered or CASF. C++ void SetCodec ( BYTE DeviceNo, DWORD IoCtlCode );

void GlSetCodec ( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _SetTxSetToRecovered sets clock to recoverd _SetTxSetToInternal - sets clock to internal _SetTxSetToExternal set sclock to external _SetCasf sets CASF Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetCodec( SelectedDeviceNo, _SetTxToInternal ); }

ResetCodec, SetCodec, GetCodec, EnableCodec, DisableCodec, CheckCodec

4.64 Reset Codec from CASF to BER

C++ C
void ResetCodec ( BYTE DeviceNo, DWORD IoCtlCode ); void GlResetCodec ( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _ResetCasf set to BER Returns: Nothing

74

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.ResetCodec( SelectedDeviceNo, _ResetCasf ); }

SetCodec, GetCodec, EnableCodec, DisableCodec, CheckCodec

4.65 Get Codec Gain or Time Slot

C++ C
BYTE GetCodec (BYTE DeviceNo, DWORD IoCtlCode ); BYTE GlGetCodec (BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _GetTxTimeslot gets transmit time slot _GetRxTimeslot gets receive time slot _GetGainForVfTx gets gain for transmit _GetGainForVfRx gets gain for receive Returns: BYTE Gain or timeslot number depending on the IoCtlCode parameter
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . TxTs = Ifc.GetCodec(DevNo, _GetTxTimeslot); // Read this setting from driver RxTs = Ifc.GetCodec(DevNo, _GetRxTimeslot); // Read this setting from driver RxGain = Ifc.GetCodec(DevNo, _GetGainForVfRx ); // Read VF gain for Rx TxGain = Ifc.GetCodec(DevNo, _GetGainForVfTx ); // and TX }

ResetCodec, SetCodec, EnableCodec, DisableCodec, CheckCodec

75

4.66 Turn On Codec Speaker or VF Transmit, or Enable Drop Insert

C++ C
void EnableCodec( BYTE DeviceNo, DWORD IoCtlCode ); void GlEnableCodec( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _TurnOnSpeaker turns speaker on _TurnOnVfTx turns VF transmit on _EnableDropInsert enables drop insert Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.EnableCodec(SelectedDeviceNo, _TurnOnSpeaker); // If was Off set On Ifc.EnableCodec(SelectedDeviceNo, _TurnOnVfTx); // }

ResetCodec, SetCodec, GetCodec, CheckCodec, DisableCodec

76

4.67 Turn Off Codec Speaker or VF Transmit, or Disable Drop Insert

C++ C
void DisableCodec( BYTE DeviceNo, DWORD IoCtlCode ); void GlDisableCodec( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _TurnOffSpeaker turns speaker off _TurnOffVfTx turns VF transmit off _DisableDropInsert disables drop insert Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.DisableCodec(SelectedDeviceNo, _TurnOffSpeaker); Ifc.DisableCodec(SelectedDeviceNo, _TurnOffVfTx); }

ResetCodec, SetCodec, GetCodec, CheckCodec, EnableCodec

77

4.68 Check Codec Settings

Checks whether speaker or VF transmit is on, clock setting or CASF/BER setting.

C++ C

bool CheckCodec( BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckCodec( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode specifies type of register to write to _IsSpeakerOn is speaker on? _IsVfTxOn is VF transmit on? _IsCasfNotBer is CASF set? _IsTxSetToRecovered is clock set to recovered? _IsTxSetToInternal - is clock set to internal? _IsTxSetToExternal is clock set to external?

Returns: Bool true if the option in question is enabled/on, false if the option is disabled/off
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . bool bSpeaker = Ifc.CheckCodec(SelectedDeviceNo, _IsSpeakerOn ); bool bInsert = Ifc.CheckCodec(SelectedDeviceNo, _IsVfTxOn ); }

ResetCodec, SetCodec, GetCodec, EnableCodec, DisableCodec

78

4.69 Enable/Disable Time Slot For Multiframe Transmission

C++ C
void EnableMultiTs(int DevIndex, int tsnum, bool bAvail); void GlEnableMultiTs(int DevIndex, int tsnum, bool bAvail);

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) int tsnum timeslot number bool bAvail true to enable, false to disable Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . for (int i = 0; i <= NoOfChannels-1; i++) { if ( bEnableTs[I] ) Ifc.EnableMultiTs( DevNo 1, 0, true ); else Ifc.EnableMultiTs( DevNo 1, 0, false ); } }

CheckMultiTsAvailable, CheckMultiTsAllAvailable, EnableMultiTsAll

4.70 Check Whether a Time Slot is Available

C++ C
bool CheckMultiTsAvailable(int DevIndex, int tsnum); bool GlCheckMultiTsAvailable(int DevIndex, int tsnum);

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) int tsnum timeslot number Returns: bool true if available, otherwise false

EnableMultiTs, CheckMultiTsAllAvailable, EnableMultiTsAll 79

4.71 Check Whether all the Time Slots are Available

C++ C
bool bool CheckMultiTsAllAvailable(int DevIndex); CheckMultiTsAllAvailable(int DevIndex);

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) Returns: bool true if available, otherwise false

EnableMultiTs, CheckMultiTsAvailable, EnableMultiTsAll

4.72 Make All Time Slots Available/Unavailable

C++ C
void void EnableMultiTsAll(int DevIndex, bool bAvail); EnableMultiTsAll(int DevIndex, bool bAvail);

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) bool bAvail true make available, false make unavailable Returns: Nothing EnableMultiTs, CheckMultiTsAvailable, CheckMultiTsAllAvailable

80

4.73 Restore Time Slot Status

Restores the saved time slot status. C++ void RestoreMultiTsStatus( int DevIndex );

void

GlRestoreMultiTsStatus( int DevIndex );

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) Returns: Nothing SaveMultiTsStatus

4.74 Save Time Slot Status

C++ C
void void SaveMultiTsStatus( int DevIndex ); GlSaveMultiTsStatus( int DevIndex );

Parameters: int DevIndex zero relative device index ( < GetNoOfDevicesInstalled() ) Returns: Nothing RestoreMultiTsStatus

81

4.75 Read BER Error Counter and Clear It

C++ C
long ReadBerErrXlinx( BYTE DeviceNo ); long GlReadBerErrXlinx( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: long BER error counter
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . if ( _bDropInsert ) Ifc.EnableCodec( _DevNo, _EnableDropInsert ); Ifc.ReadBerErrXlinx( _DevNo ); // Read First counter and discard it }

InsertBerError

4.76 Insert a Logical or BPV Error

C++ C
void InsertBerError( BYTE DeviceNo, DWORD IoCtlCode ); void GlInsertBerError( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _InsertSingleError - inserts a logical error _InsertSingleBpvError inserts a BPV error Returns: Nothing

82

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.InsertBerError( SelectedDeviceNo, _InsertSingleError ); Ifc.InsertBerError( SelectedDeviceNo, _InsertSingleBpvError); }

ReadBerErrXilinx

4.77 Select Receive or Transmit BER

C++ C
void SetBerTxRx( BYTE DeviceNo, DWORD IoCtlCode ); void GlSetBerTxRx( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _SelectRxBer selects receive BER _SelectTxBer selects transmit BER Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . /************ Resync Card ************/ Ifc.SetBerTxRx( _DevNo, _SelectRxBer ); // Enable Rx Ifc.SetBerTxRx( _DevNo, _SelectTxBer ); // Enable Tx }

ResetBerTxRx

83

4.78 Deselect Receive/Transmit BER

C++ C
void ResetBerTxRx( BYTE DeviceNo ); void GlResetBerTxRx( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing SetBerTxRx

4.79 Load BER Static Pattern

C++ C
void LoadBerStaticPattern( BYTE DeviceNo ); void LoadBerStaticPattern( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing

4.80 Setting Cross Port Mode

C++ C
bool SetCrossPort( BYTE devNo, EnT1E1CrossPortMode crossPortMode ); bool GlSetCrossPort( BYTE devNo, EnT1E1CrossPortMode crossPortMode);

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) EnT1E1CrossPortMode crossPortMode the desired cross port mode Returns: true if set ok, false if errors

84

The cross port values are defined as

enum EnT1E1CrossPortMode { EN_T1E1_CROSS_PORT_MODE_NO_CROSS_PORT = 0, EN_T1E1_CROSS_PORT_MODE_THROUGH = 1, EN_T1E1_CROSS_PORT_MODE_TRANSMIT = 2 };

See cross port functions in the users guide section for the definition of the cross port modes.

4.81 Getting Cross Port Mode

C++ C
EnT1E1CrossPortMode GetCrossPort( BYTE devNo ) const; EnT1E1CrossPortMode GlGetCrossPort( BYTE devNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: EnT1E1CrossPortMode crossPortMode the cross port mode setting The cross port values are defined as
enum EnT1E1CrossPortMode { EN_T1E1_CROSS_PORT_MODE_NO_CROSS_PORT = 0, EN_T1E1_CROSS_PORT_MODE_THROUGH = 1, EN_T1E1_CROSS_PORT_MODE_TRANSMIT = 2 };

See cross port functions in the users guide section for the definition of the cross port modes.

4.82 Disabling Driver Interrupt Events

C++ C
void DisableDrInterruptEvents( BYTE DeviceNo, BYTE Events ); void DisableDrInterruptEvents( BYTE DeviceNo, BYTE Events );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() )

85

BYTE Events - events to disable Returns: Nothing

EnableDrInterruptEvents

4.83 Enabling Driver Interrupt Events

C++ C
void EnableDrInterruptEvents( BYTE DeviceNo, BYTE Events ); void EnableDrInterruptEvents( BYTE DeviceNo, BYTE Events );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE Events - events to disable Returns: Nothing DisableDrInterruptEvents

4.84 Get Driver Chip Attributes

Obtains such driver attributes as: all transitions all per status, equalizer control value, line length, line and jitter attenuation.

C++ C

BYTE GetDr( BYTE DeviceNo, DWORD IoCtlCode ); BYTE GlGetDr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrGetAllTransitions _DrGetAllPerStatus _DrGetEqualizerControl _DrGetJitterAttenuation _DrGetRxLineAttenuation _DrGetLineLength - all transitions - all per status - equalizer control setting - jitter attenuation - receive line attenuation - line length

86

Returns:

BYTE attribute value

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . printf(" Rx Line attenuation level = %5.1f\n", -2.9f * (float)Ifc.GetDr( SelectedDeviceNo, _DrGetRxLineAttenuation ) ); }

CheckDr, SetDr, EnableDr, DisableDr, ResetDrRegisters, SetDrJitter

4.85 Check Whether a Driver Attribute is Set/Selected

C++ C
bool CheckDr( BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckDr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrIsLosTransitionSet - checks if LOS transition is set _DrIsNLoopTransitionSet - checks if network loop transition is set _DrIsAisTransitionSet - checks if AIS transition is set _DrIsDfmoTransitionSet - checks if DFMO transition is set _DrIsEsOvrTransitionSet checks if over-run transition is set _DrIsEsUnTransitionSet - checks if ES under-run transition set _DrIsLosPerStatusSet checks if LOS per status is set _DrIsNLoopPerStatusSet checks if network loop per status is set _DrIsAisPerStatusSet - checks if AIS per status is set _DrIsDrivOpenStatusSet checks if driver open status is set _DrIsBistPerStatusSet checks if BIST per status is set _DrIsRxMonitorModeSelected checks if driver monitor mode is selected _DrIs12dBRxEqualizerGain checks if equalizer gain is set to 12 dB _DrIs26dBRxEqualizerGain - checks if equalizer gain is set to 26 dB _DrIs36dBRxEqualizerGain - checks if equalizer gain is set to 36 dB _DrCheckLocalLoopback checks if local loopback is set _DrCheckAnalogLoopback checks if analog loopback is set _DrCheckRemoteLoopback checks if remote loopback is set _DrCheckNetworkLoopbackDetect checks if network loopback is detected _DrCheckTransmitAllOnes checks if transmit all ones is set 87

_DrBuiltInSelfTest built in self test Returns: bool true attribute is set/selected, false otherwise

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . bRet = Ifc.CheckDr(SelectedDeviceNo, _DrIsNLoopPerStatusSet); printf( "%s Network Loopback Active\n", bRet ? "Y" : "n"); }

GetDr, SetDr, EnableDr, DisableDr, ResetDrRegisters, CheckDrJitter, SetDrJitter

4.86 Set Driver Equalizer Control or Line Length

C++ C
void SetDr( BYTE DeviceNo, DWORD IoCtlCode, BYTE Data ); void GlSetDr( BYTE DeviceNo, DWORD IoCtlCode, BYTE Data );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrSetEqualizerControl _DrSetLineLength - sets equalizer control - sets line length

BYTE Data equalizer control value or line length depending on the IoCtlCode. Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetDr( DevNo, _DrSetLineLength, (BYTE)length ); }

GetDr, CheckDr, SetDr 88

4.87 Set Driver Equalizer Gain

C++ C
void SetDr( BYTE DeviceNo, DWORD IoCtlCode ); void GlSetDr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrSet12dBRxEqualizerGain sets 12 dB equalizer gain _DrSet26dBRxEqualizerGain sets 26 dB equalizer gain _DrSet36dBRxEqualizerGain sets 36 dB equalizer gain Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetDr( DevNo, _DrSet12dBRxEqualizerGain ); }

GetDr, CheckDr, SetDrJitter

89

4.88 Enabling Driver Loopback, Transmission All Ones, Network Loop Up/Down, or Rx Monitor Mode
C++ C
void EnableDr( BYTE DeviceNo, DWORD IoCtlCode ); void GlEnableDr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrEnableLocalLoopback _DrEnableAnalogLoopback _DrEnableRemoteLoopback _DrEnableNetworkLoopbackDetect _DrEnableTransmitAllOnes _DrEnableInBandNetworkLoopUp _DrEnableInBandNetworkLoopDown _DrEnableRxMonitorMode Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #ifdef T1 Ifc.DisableFr( SelectedDeviceNo, _TfrDisableLocalLoopback); #else // E1 Ifc.DisableFr( SelectedDeviceNo, _EfrDisableLocalLoopback); #endif Ifc.EnableDr( SelectedDeviceNo, _DrEnableLocalLoopback); }

- enables local loopback - enables analog loopback - enables remote loopback - enables network loopback detect - enables all ones transmission - enables in-band network loop up - enables in-band network loop down - enables driver Rx monitor mode

DisableDr

90

4.89 Disabling Driver Loopback, Transmission All Ones, Network Loop Up/Down, or Rx Monitor Mode
C++ C
void DisableDr( BYTE DeviceNo, DWORD IoCtlCode ); void GlDisableDr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrDisableLocalLoopback _DrDisableAnalogLoopback _DrDisableRemoteLoopback _DrDisableNetworkLoopbackDetect _DrDisableTransmitAllOnes _DrDisableInBandNetworkLoopUp _DrDisableInBandNetworkLoopDown _DrDisableRxMonitorMode _DrDisableJitterAttenuation Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.DisableDr( SelectedDeviceNo, _DrDisableLocalLoopback); Ifc.DisableDr( SelectedDeviceNo, _DrDisableRemoteLoopback); }

- disables local loopback - disables analog loopback - disables remote loopback - disables network loopback detect - disables all ones transmission - disables in-band network loop up - disables network loop down - disables driver Rx monitor mode - disables jitter attenuation

EnableDr, CheckDrJitter, SetDrJitter

91

4.90 Resetting Driver Registers

C++ C
void ResetDrRegisters( BYTE DeviceNo ); void GlResetDrRegisters( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.ResetDrRegisters( SelectedDeviceNo ); }

WriteRegister, ReadRegister

4.91 Check Driver Jitter Settings

C++ C
bool CheckDrJitter( BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckDrJitter( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrIsJitterAttenuationOnTx - checks whether jitter attenuation is set on Tx _DrIsJitterAttenuationOnRx - checks whether jitter attenuation is set on Rx _DrIsJitterAttenuationDisabled - checks whether jitter attenuation is disabled _DrIsJitterSet6Hz - checks whether jitter is set on 6Hz _DrIsJitterSet3Hz - checks whether jitter is set on 3Hz Returns: bool true if set, false otherwise 92

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . bool b6Hz = Ifc.CheckDrJitter( SelectedDeviceNo, _DrIsJitterSet6Hz ); }

DisableDr, SetDrJitter

4.92 Set Driver Jitter

C++ C
void SetDrJitter( BYTE DeviceNo, DWORD IoCtlCode ); void GlSetDrJitter( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DrSetJitterAttenuationOnRx sets driver jitter attenuation on Rx _DrSetJitterAttenuationOnTx sets driver jitter attenuation on Tx _DrSetJitter6Hz - sets jitter on 6Hz _DrSetJitter3Hz - sets jitter on 3Hz Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.SetDrJitter( SelectedDeviceNo, _DrSetJitter6Hz ); }

DisableDr, CheckDrJitter

93

4.93 Checking T1 Framer

C++ C
bool CheckFr( BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckFr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _TfrIsResyncInProgress - checks if resync is in progress _TfrIsBlueAlarmDetected - checks if blue alarm is detected _TfrIsB8ZSorCofaDetected - checks if B8ZS or COFA is detected _TfrIsFrameErrorDetected - checks if frame error is detected _TfrIsCarrierLossDetected - checks if carrier loss is detected _TfrIsYellowAlarmDetected - checks if yellow alarm is detected _TfrIsErrorCounterSaturated - checks if error counter is saturated _TfrIsBpvCounterSaturated - checks if BPV counter is saturated _TfrIsLocalLoopBackActive - checks if local loopback is active _TfrIsZeroSuppB7Set - checks if zero suppression B7 is set _TfrIsTxB8ZSActive - checks if Tx B8SZ is active _TfrIsD4YelAlarmSBit - checks if D4 yellow alarm SBit _TfrIsEsfYelAlarmFdl - checks if ESF yellow alarm FDL _TfrIsRxCofaDetectSelected - checks if Rx COFA detect is selected _TfrIsD4Selected - checks if D4 is selected _TfrIsEsfSelected - checks if ESF is selected _TfrIsSlc96Selected - checks if SLC96 is selected _TfrIsT1DMSelected - checks if T1DM is elected _TfrIsAutoResyncEnabled - checks if autoresync is enabled _TfrIsTxYellowAlarmEnabled - checks if Tx yellow alarm is enabled _TfrIsTxBlueAlarmEnabled - checks if Tx blue alarm is enabled _TfrIsExternalSBitEnabled - checks if external Sbit is enabled _TfrIsFFTxIdleCode - checks if the Tx idle code is 0xFF _TfrIs7FTxIdleCode - checks if Tx idle code is 0x7F _TfrIsRobbedBitSigEnabled - checks if robbed bit sig is enabled _TfrIsExternalCrcEnabled - checks if external CRC is enabled _TfrIsExternalFtFpsEnabled - checks if external FT FPS is enabled _TfrIsOutDataNrzSelected - checks if output data NRZ is selected _TfrIsResyncAlgo10Bits - checks if resync algorithm is 10 bits _TfrIsResyncUsingFtBits - checks if resync uses FT bits _TfrIsOofCriteria2of4 - checks if OFF criteria is 2 of 4 _TfrIsResyncOnOof - checks if resync is on OOF Returns:

94

bool true if set, false otherwise

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . /********************************************************************/ /* Resync status */ /********************************************************************/ #if defined(T1) bRet = Ifc.CheckFr( SelectedDeviceNo, _TfrIsResyncInProgress) ; #else // defined(E1) bRet = Ifc.CheckFr( SelectedDeviceNo, _EfrIsReceiveLossOfSync); #endif printf( "%s Sync Loss\n", bRet ? "Y" : "n"); }

This group of IoCtlCodes is defined only for T1 devices. They cannot be used for E1 cards !!!

SetFr,SelectFr,DeselectFr,GetFr,EnableFr,DisableFr

95

4.94 Checking E1 Framer

C++ C
bool CheckFr( BYTE DeviceNo, DWORD IoCtlCode ); bool GlCheckFr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _EfrIsErrorCounterSaturation - checks if error counter is saturated _EfrIsReceiveLossOfSync - checks if receive loss of sync _EfrIsCasMultiframeResync - checks if CAS multiframe resync _EfrIsFrameResync - checks if frame resync _EfrIsReceiveUnframedAllOnes - checks if receive unframed all ones is selected _EfrIsReceiveSignalingAllOnes - checks if receive signaling all ones is selected _EfrIsReceiveDma - checks if receive DMA is selected _EfrIsReceiveRemoteAlarm - checks if receive remote alarm _EfrIsAutoResyncEnabled - checks if autoresync is enabled _EfrIsRxCcsMode - checks if Rx is in CCS mode _EfrIsRxCasMode - checks if Rx is in CAS mode _EfrIsLocalLoopBackActive - checks if local loopback is active _EfrIsRxCrc4Enabled - checks if Rx CRC4 is enabled _EfrIsTxCrc4Enabled - checks if Tx CRC4 is enabled _EfrIsRxHdb3Enabled - checks if Rx HDB3 is enabled _EfrIsTxHdb3Enabled - checks if Tx HDB3 is enabled _EfrIsTx100DutyCycle - checks if Rx 100 duty cycle is selected _EfrIsTx50DutyCycle - checks if Tx 50 duty cycle is selected _EfrIsTxSignalingAllOnes - checks if Tx signaling all ones is selected _EfrIsTxExtraBits - checks if Tx extra bits are selected _EfrIsTxNationalBits - checks if Tx national bits are selected _EfrIsTxInternationalBits - checks if Tx international bits are selected _EfrIsTxCcsMode - checks if Tx CCS mode is selected _EfrIsTxCasMode - checks if Tx CAS mode is selected _EfrIsExtSignalingBits - checks if ext signaling bits are selected _EfrIsUnframeAllOnes - checks if unframed all ones is selected _EfrIsTxRemoteAlarm - checks if Tx remote alarm is selected _EfrIsTxDma - checks if Tx DMA is selected _EfrIsFrameResyncCriteriaFixed - checks if framere sync criteria is fixed _EfrIsCasMfResyncCriteriaFixed - checks if CAS MF resync criteria is fixed _EfrIsCasMultiframeSyncCriteriaFixed - checks if CAS multiframe sync criteria is fixed _EfrIsTxMfStartWithFas - checks if Tx multiframe starts with FAS Returns: bool true if set, false otherwise

96

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . /********************************************************************/ /* Resync status */ /********************************************************************/ #if defined(T1) bRet = Ifc.CheckFr( SelectedDeviceNo, _TfrIsResyncInProgress) ; #else // defined(E1) bRet = Ifc.CheckFr( SelectedDeviceNo, _EfrIsReceiveLossOfSync); #endif printf( "%s Sync Loss\n", bRet ? "Y" : "n"); }

This group of IoCtlCodes is defined only for E1 devices. They cannot be used for T1 cards !!!

SetFr,SelectFr,DeselectFr,GetFr,EnableFr,DisableFr

4.95 Checking if a Framer Time Slot is Enabled

C++ C
bool CheckFrTimeslot ( BYTE DeviceNo, BYTE TimeslotNo ); bool GlCheckFrTimeslot ( BYTE DeviceNo, BYTE TimeslotNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _TfrIsChannelSelectedForTxIdleCode - checks if timeslot is selected for Tx idle code _TfrIsChannelSelectedForTransparent - checks if timeslot is selected for transparent _TfrIsRxChannelSelectedForCodeInsert - checks if Rx timeslot is selected for code insert _EfrIsTimeslotSelectedForTxIdleCode - checks if timeslot is selected for Tx idle code

BYTE TimeslotNo zero relative timeslot number 0..31 (E1), 0-23(T1) Returns: bool true if set, false otherwise

97

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined(E1) bRet = Ifc.CheckFrTimeslotSelectedForTxIdleCode(DevNo, 0); #endif }

This function is defined only for E1 devices and cannot be used for T1 cards !!!

CheckFr, SetFr,SelectFr,DeselectFr,GetFr,EnableFr,DisableFr

4.96 Disabling Framer Interrupts

C++ C
void DisableFrInterrupts( BYTE DeviceNo, DWORD IoCtlCode ); void GlDisableFrInterrupts( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrDisableAllInterrupts disables all interrupts _TfrDisableAlarmsInterruptsOnly disables alarm interrupts only E1 only _EfrDisableAllInterrupts disables all interrupts _EfrDisableAlarmsInterruptsOnly disables alarm interrupts only Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined(T1) Ifc.DisableFrInterrupts ( SelectedDeviceNo, _TfrDisableAlarmsInterruptsOnly) ; #else // defined(E1) Ifc.DisableFrInterrupts ( SelectedDeviceNo, _EfrDisableAlarmsInterruptsOnly); #endif }

98


_TfrDisableXxx IoCtlCodes must be used only for T1 devices, and _EfrDisableXxx IoCtlCodes must be used only for E1 devices.

EnableFrInterrupts

4.97 Disabling Frame Interrupts Selectively

C++ C
void DisableFrInterrupts( BYTE DeviceNo, BYTE MaskBits ); void GlDisableFrInterrupts( BYTE DeviceNo, BYTE MaskBits );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE MaskBits bits in this parameter specify interrupts to be disabled Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.DisableFrInterrupts ( SelectedDeviceNo, BitMask ) ; }

EnableFrInterrupts

99

4.98 Enabling All Frame Interrupts

C++ C
void EnableFrInterrupts( BYTE DeviceNo, DWORD IoCtlCode ); void GlEnableFrInterrupts( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrEnableAllInterrupts enables all interrupts E1 only _EfrEnableAllInterrupts enables all interrupts Returns: Nothing

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined(T1) Ifc.EnableFrInterrupts ( SelectedDeviceNo, _TfrEnableAllInterrupts) ; #else // defined(E1) Ifc.DisableFrInterrupts ( SelectedDeviceNo, _EfrEnableAllInterrupts); #endif }

_TfrEnableAllInterrupts IoCtlCode must be used only for T1 devices, and _EfrEnableAllInterrupts IoCtlCode must be used only for E1 devices.

EnableFrInterrupts

100

4.99 Enabling Frame Interrupts Selectively

C++ C
void EnableFrInterrupts( BYTE DeviceNo, BYTE MaskBits ); void GlEnableFrInterrupts( BYTE DeviceNo, BYTE MaskBits );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE MaskBits bits in this parameter specify interrupts to be enabled Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.EnableFrInterrupts ( SelectedDeviceNo, BitMask ) ; }

DisableFrInterrupts

101

4.100 Get Framer Receive Status Register (RSR) or Receive Interrupt Mask Register (RIMR)
C++ C
BYTE GetFr ( BYTE DeviceNo, DWORD IoCtlCode ); BYTE GlGetFr ( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrReadRsr reads receive status register _TfrReadRimr reads receive interrupt mask register E1 only _EfrReadRsr reads receive status register _EfrReadRimr reads receive interrupt mask register Returns: BYTE register data

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . BYTE RsrData; #if defined(T1) RsrData = Ifc.GetFr ( SelectedDeviceNo, _TfrReadRsr ) ; #else // defined(E1) RsrData = Ifc.GetFr ( SelectedDeviceNo, _EfrReadRsr ); #endif }

_TfrReadXxx IoCtlCodes must be used only for T1 devices, and _EfrReadXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,DeselectFr,EnableFr,DisableFr

102

4.101 Getting Number of Frame Errors

C++ C
WORD GetFrErrorCounter ( BYTE DeviceNo, DWORD IoCtlCode ); WORD GlGetFrErrorCounter ( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrGetBipolarViolationCounter - gets number of bipolar violations _TfrGetOutOfFrameCounter gets out-of-frame counter _TfrGetErroredSuperFrameCounter gets number of superframe errors E1 only _EfrGetBipolarViolationCounter - gets number of bipolar violations _EfrGetCrc4ErrorCounter gets number of CRC4 errors _EfrGetFrameErrorCounter gets number of frame errors Returns: WORD number of errors
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) BpvErrors = Ifc.GetFrErrorCounter( _DevNo, _TfrGetBipolarViolationCounter ); #else // (E1) BpvErrors = Ifc.GetFrErrorCounter( _DevNo, _EfrGetBipolarViolationCounter ); #endif }

_TfrGetXxx IoCtlCodes must be used only for T1 devices, and _EfrGetXxx IoCtlCodes must be used only for E1 devices.

SetFrErrorCounter

103

4.102 Set Framer Error Counters to a Start Value

C++ C
void SetFrErrorCounter ( BYTE DeviceNo, DWORD IoCtlCode, WORD CounterValue); void GlSetFrErrorCounter ( BYTE DeviceNo, DWORD IoCtlCode, WORD CounterValue);

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrSetBipolarViolationCounter - sets start bipolar violations counter _TfrSetOutOfFrameCounter sets start out-of-frame counter _TfrSetErroredSuperFrameCounter sets start superframe error counter E1 only _EfrSetBipolarViolationCounter - sets start of bipolar violation counter _EfrSetCrc4ErrorCounter sets start of CRC4 error counter _EfrSetFrameErrorCounter sets start frame error counter Returns: Nothing

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.SetFrErrorCounter( _DevNo, _TfrSetBipolarViolationCounter, 0 ); #else // (E1) Ifc.SetFrErrorCounter( _DevNo, _EfrSetBipolarViolationCounter, 0 ); #endif }

_TfrSetXxx IoCtlCodes must be used only for T1 devices, and _EfrSetXxx IoCtlCodes must be used only for E1 devices.

GetFrErrorCounter

104

4.103 Enabling Framer Features

T1 only. This function enables local loopback, Tx B8ZS, autoresync, Tx yellow alarm, Tx blue alarm, external S bit, robbed bit signaling, external CRC, external FT FPS. E1 only. This function enables autoresync, local loopback, CRC4 for Tx/Rx, HDB3 for Tx/Rx, signaling all ones, extra, national and international bits, external signaling, unframed all ones, Tx remote alarm, Tx DMA and Tx multiframe start with FAS.

C++ C

void EnableFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlEnableFr( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrEnableLocalLoopback enables local loopback _TfrEnableTxB8ZS enables Tx B8SZ _TfrEnableAutoResync enables auto resync _TfrEnableTxYellowAlarm enables Tx yellow alarm _TfrEnableTxBlueAlarm enables Tx blue alarm _TfrEnableExternalSBit enables external S bit _TfrEnableRobbedBitSig enables robbed bit signaling _TfrEnableExternalCrc enables external CRC _TfrEnableExternalFtFps enables external FT FPS E1 only _EfrEnableAutoResync enables auto resync _EfrEnableLocalLoopback enables local loopback _EfrEnableRxCrc4 enables Rx CRC4 _EfrEnableTxCrc4 enables Tx CRC4 _EfrEnableRxHdb3 enables Rx HDB3 _EfrEnableTxHdb3 enables Tx HDB3 _EfrEnableTxSignalingAllOnes enables Tx signaling all ones _EfrEnableTxExtraBits enables Tx extra bits _EfrEnableTxNationalBits enables Tx national bits _EfrEnableTxInternationalBits enables Tx international bits _EfrEnableExtSignalingBits enables ext signaling bits _EfrEnableUnframeAllOnes enables unframed all ones _EfrEnableTxRemoteAlarm enables Tx remote alarm _EfrEnableTxDma enables Tx DMA _EfrTxMfStartWithFas enables starting multiframes with FAS Returns: Nothing

105

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.EnableFr( _DevNo, _TfrEnableAutoResync ); #else // (E1) Ifc.EnableFr( _DevNo, _TfrEnableAutoResync ); #endif }

_TfrEnableXxx IoCtlCodes must be used only for T1 devices, and _EfrEnableXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,DeselectFr,GetFr,DisableFr

4.104 Disabling Framer Features

T1 only. This function disables local loopback, Tx B8Sz, autoresync, Tx yellow alarm, Tx blue alarm, external S bit, robbed bit signaling, external CRC, external FT FPS. E1 only. This function disables autoresync, local loopback, CRC4 for Tx/Rx, HDB3 for Tx/Rx, signaling all ones, extra, national and international bits, external signaling, unframed all ones, Tx remote alarm, Tx DMA and Tx multiframe start with FAS.

C++ C

void DisableFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlDisableFr( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrDisableLocalLoopback disables local loopback _TfrDisableTxB8ZS disables Tx B8SZ _TfrDisableAutoResync disables auto resync _TfrDisableTxYellowAlarm disables Tx yellow alarm _TfrDisableTxBlueAlarm disables Tx blue alarm _TfrDisableExternalSBit disables external S bit _TfrDisableRobbedBitSig disables robbed bit signaling _TfrDisableExternalCrc disables external CRC _TfrDisableExternalFtFps disables external FT FPS

106

E1 only _EfrDisableAutoResync disables auto resync _EfrDisableLocalLoopback disables local loopback _EfrDisableRxCrc4 disables Rx CRC4 _EfrDisableTxCrc4 disables Tx CRC4 _EfrDisableRxHdb3 disables Rx HDB3 _EfrDisableTxHdb3 disables Tx HDB3 _EfrDisableTxSignalingAllOnes disables Tx signaling all ones _EfrDisableTxExtraBits disables Tx extra bits _EfrDisableTxNationalBits disables Tx national bits _EfrDisableTxInternationalBits disables Tx international bits _EfrDisableExtSignalingBits disables ext signaling bits _EfrDisableUnframeAllOnes disables unframed all ones _EfrDisableTxRemoteAlarm disables Tx remote alarm _EfrDisableTxDma disables Tx DMA _EfrTxMfStartWithoutFas disables starting multiframes with FAS Returns: Nothing

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.DisableFr( _DevNo, _TfrDisableAutoResync ); #else // (E1) Ifc.DisableFr( _DevNo, _TfrDisableAutoResync ); #endif }

_TfrDisableXxx IoCtlCodes must be used only for T1 devices, and _EfrDisableXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,DeselectFr,GetFr,EnableFr

107

4.105 Setting Framer Features On

T1 only. This function sets zero suppression B7 and transparent, and OOF criteria to 2 of 4 or 2 of 5. E1 only. Sets Rx/Tx CCS/CAS mode and CAS multiframe sync criteria to fixed or not fixed.

C++ C

void SetFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlSetFr( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrSetZeroSuppB7 sets zero bit suppression B7 _TfrSetZeroSuppTransparent sets zero bit suppression transparent _TfrOofCriteria2of4 sets OOF criteria to 2 of 4 _TfrOofCriteria2of5 sets OOF criteria to 2 of 5 E1 only _EfrSetRxCcsMode sets Rx CCS mode _EfrSetRxCasMode sets Rx CAS mode _EfrSetTxCcsMode sets Tx CCS mode _EfrSetTxCasMode sets Tx CAS mode _EfrCasMultiframeSyncCriteriaFixed sets CAS multiframe sync criteria fixed _EfrCasMultiframeSyncCriteriaNotFixed sets CAS multiframe sync criteria not fixed Returns: Nothing

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.SetFr( _DevNo, _TfrOofCriteria2of5 ); #endif }

108


_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,DeselectFr,EnableFr,DisableFr

4.106 Selecting Framer Features

T1 only. This function selects D4 yellow alarm B2 or S bit, ESF yellow alarm FDL or S bit, sets framing to D4 or ESF, selects SLC96 or T1DM, idle code 0xFF or 0x7F, data unipolar or NRZ. E1 only. Selects Tx 100 or 50 duty cycle.

C++ C

void SelectFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlSelectFr( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrSelectD4YelAlarmB2 selects yellow alarm B2 for D4 _TfrSelectD4YelAlarmSBit selects yellow alarm S bit for D4 _TfrSelectEsfYelAlarmFdl selects yellow alarm FDL for ESF _TfrSelectEsfYelAlarmSBit selects yellow alarm S bit for ESF _TfrSelectD4 selects D4 superframe _TfrSelectEsf selects extended superframe _TfrSelectSlc96 selects SLC96 _TfrSelectT1DM selects T1DM _TfrSelectTxIdleCode7F selects idle code 0x7F _TfrSelectTxIdleCodeFF selects idle code 0xFF _TfrSelectOutDataUnipolar selects output data unipolar _TfrSelectOutDataNrz selects output data NRZ E1 only _EfrSelectTx100DutyCycle selects Tx 100 duty cycle _EfrSelectTx50DutyCycle selects Tx 50 duty cycle Returns: Nothing

109

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.SelectFr( _DevNo, _TfrSelectT1DM ); #endif }

_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,DeselectFr,EnableFr,DisableFr, EnableFr

4.107 Deselectecting Framer Channels

T1 only. This function deselects all channels for Tx idle code or for transparent code, or deselects all Rx channels for code insert. E1 only. Deselects all channels (time slots) for Tx idle code.

C++ C

void DeselectFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlDeselectFr( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrDeselectAllChannelForTxIdleCode - deselects all channels for Tx idle code _TfrDeselectAllChannelForTransparent - deselects all channels for transparent _TfrDeselectAllRxChannelForCodeInsert deselects all Rx channels for code insert E1 only _EfrDeselectAllTimeslotForTxIdleCode - deselects all channels for Tx idle code Returns: Nothing 110

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.DeselectFr( _DevNo, _TfrDeselectAllChannelForTxIdleCode); #else // (E1) Ifc.DeselectFr( _DevNo, _EfrDeselectAllTimeslotForTxIdleCode); #endif }

_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,EnableFr,DisableFr, EnableFr

111

4.108 Selecting Framer Time Slots

T1 only. This function selects a time slot for Tx idle code or transparent, or selects a Rx channel for code insert. E1 only. Selects a time slot for Tx idle code

C++ C

void SelectFrTimeslot( BYTE DeviceNo, DWORD IoCtlCode, BYTE TimeslotNo ); void GlSelectFrTimeslot( BYTE DeviceNo, DWORD IoCtlCode, BYTE TimeslotNo );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrSelectChannelForTxIdleCode - selects a timeslot for Tx idle code _TfrSelectChannelForTransparent - selects a time slot for transparent _TfrSelectRxChannelForCodeInsert - selects a Rx time slot for code insert E1 only _EfrSelectTimeslotForTxIdleCode - selects a time slot for Tx idle code BYTE TimeslotNo zero relative time slot to select Returns: Nothing

try { GlComInterface Ifc; Ifc.Initialize(); . . . #if defined (T1) Ifc.SelectFrTimeslot( Ifc.SelectFrTimeslot( #else // (E1) Ifc.SelectFrTimeslot( Ifc.SelectFrTimeslot( #endif }

// Device driver interface object // Set default hardware settings _DevNo, _TfrSelectChannelForTxIdleCode, 0); _DevNo, _TfrSelectChannelForTxIdleCode, 23); _DevNo, _EfrSelectTimeslotForTxIdleCode, 0); _DevNo, _EfrSelectTimeslotForTxIdleCode, 31);

_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

DeselectFrTimeslot

112

4.109 Deselectecting Framer Time Slots

T1 only. This function deselects a time slot for Tx idle code or transparent, or selects a Rx channel for code insert. E1 only. Deselects a time slot for Tx idle code

C++ C

void DeselectFrTimeslot( BYTE DeviceNo, DWORD IoCtlCode, BYTE TimeslotNo ); void GlDeselectFrTimeslot( BYTE DeviceNo, DWORD IoCtlCode, BYTE TimeslotNo );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrDeselectChannelForTxIdleCode - deselects a timeslot for Tx idle code _TfrDeselectChannelForTransparent - deselects a time slot for transparent _TfrDeselectRxChannelForCodeInsert - deselects a Rx time slot for code insert E1 only _EfrDeselectTimeslotForTxIdleCode - deselects a time slot for Tx idle code BYTE TimeslotNo zero relative time slot to deselect Returns: Nothing
try { GlComInterface Ifc; Ifc.Initialize(); . . . #if defined (T1) Ifc.DeselectFrTimeslot( Ifc.DeselectFrTimeslot( #else // (E1) Ifc.DeselectFrTimeslot( Ifc.DeselectFrTimeslot( #endif }

// Device driver interface object // Set default hardware settings _DevNo, _TfrDeselectChannelForTxIdleCode, 0); _DevNo, _TfrDeselectChannelForTxIdleCode, 23); _DevNo, _EfrDeselectTimeslotForTxIdleCode, 0); _DevNo, _EfrDeselectTimeslotForTxIdleCode, 31);

113


_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

SelectFrTimeslot

4.110
C++ C

Detecting Rx B8ZS or COFA ( T1 Only )

void DetectFrRx( BYTE DeviceNo, DWORD IoCtlCode ); void DetectFrRx( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _TfrDetectRxB8ZS detects B8ZS _TfrDetectRxCofa detects COFA Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (T1) Ifc.DetectFrRx( _DevNo, _TfrDetectRxB8ZS ); #endif }

Use this member function only for T1 devices.

114

4.111

Resync Framer

T1 only. Call this function to force resync, or to resync using algo 10 or 24 bits, or to resync using FT or FT FS bits, or to resync on OOF or on OOF RCL E1 only. Call this function to force resync, or with frame or CAS multiframe criteria fixed or not fixed.

C++ C

void ResyncFr( BYTE DeviceNo, DWORD IoCtlCode ); void GlResyncFr( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode T1 only _TfrForcedResync forces resync _TfrResyncAlgo10Bits resyncs using algo 10 bits _TfrResyncAlgo24Bits resyncs using algo 24 bits _TfrResyncUsingFtBits resyncs using FT bits _TfrResyncUsingFtFsBits resyncs using FT FS bits _TfrResyncOnOof - resync on OOF _TfrResyncOnOofRcl resync on OOF RCL E1 only _EfrForcedResync - forces resync _EfrFrameResyncCriteriaFixed frame resync with criteria fixed _EfrFrameResyncCriteriaNotFixed frame resync with criteria not fixed _EfrCasMfResyncCriteriaFixed CAS multiframe resync with criteria fixed _EfrCasMfResyncCriteriaNotFixed CAS multiframe resync with criteria not fixed Returns: Nothing

115

try { GlComInterface Ifc; Ifc.Initialize(); . . . Ifc.ResyncFr( _DevNo, #if defined (T1) _TfrForcedResync ); #else // (E1) _EfrForcedResync ); #endif }

// Device driver interface object // Set default hardware settings

_TfrXxx IoCtlCodes must be used only for T1 devices, and _EfrXxx IoCtlCodes must be used only for E1 devices.

CheckFr,SetFr,SelectFr,DeselectFr,GetFr,EnableFr,DisableFr

4.112 Set Framer Tx Extra, National or International Bits (E1 only)

C++ C
void SetFrBits( BYTE DeviceNo, DWORD IoCtlCode, BYTE Bits ); void GlSetFrBits( BYTE DeviceNo, DWORD IoCtlCode, BYTE Bits );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _EfrSetTxExtraBits sets extra bits _EfrSetTxNationalBits sets national bits _EfrSetTxInternationalBits sets international bits BYTE Bits bits to set Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (E1) Ifc.SetFrBits( DevNo, _EfrSetTxExtraBits, Bits ); #endif }

116


This member function is defined for E1 devices only.

GetFrBits

4.113 Get Framer Tx Extra, National or International Bits (E1 only)

C++ C
BYTE GetFrBits( BYTE DeviceNo, DWORD IoCtlCode ); BYTE GlGetFrBits( BYTE DeviceNo, DWORD IoCtlCode );

BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _EfrGetTxExtraBits gets extra bits _EfrGetTxNationalBits gets national bits _EfrGetTxInternationalBits gets international bits Returns: BYTE Bits bits that are set
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . #if defined (E1) BYTE BitsSet = Ifc.GetFrBits( DevNo, _EfrGetTxNationalBits ); #endif }

This member function is defined for E1 devices only.

SetFrBits

117

4.114 Retrieving Timeslot Data

Copies data from the driver global receive buffer that has already been filled in. This global buffer is the alternative to the active global buffer that is being filled in when function is called. C++ void GetTimeslotData(BYTE DeviceNo, BYTE *BufferPtr, int BufferSize, int TimeslotNo); void G;GetTimeslotData(BYTE DeviceNo, C BYTE *BufferPtr, int BufferSize, int TimeslotNo); Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE *BufferPtr buffer to retrieve data into int BufferSize bytes to retrieve int TimeslotNo zero relative time slot to retrieve Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . for (i=0; i < NoOfChannels; i++) { Switches[i] = 0; Ifc.GetTimeslotData(DataBuffer, NoOfSamples, i, CurrentSelDev); PrevPolarity[i] = DataBuffer[i] & 0x80; for (j=0; j < NoOfSamples; j++) { int Polarity = DataBuffer[j] & 0x80; if ( Polarity == PrevPolarity[i]) ; else { Switches[i]++; PrevPolarity[i] = Polarity; } } } }

118


During execution of this function the global active receive buffer can switch to the alternative. Use GetLatestTimeslotData to avoid this possibility.

GetLatestTimeslotData

4.115 Retrieving Latest Timeslot Data

This function is similar to GetTimeslotData but it takes into account that active buffer can switch to the alternative buffer when this function is being executed

C++ C

int GetLatestTimeslotData(BYTE DeviceNo, BYTE *BufferPtr, int BufferSize, int TimeslotNo); int GlGetLatestTimeslotData(BYTE DeviceNo, BYTE *BufferPtr, int BufferSize, int TimeslotNo);

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE *BufferPtr buffer to retrieve data into int BufferSize bytes to retrieve int TimeslotNo zero relative time slot to retrieve Returns: int number of bytes copied into user buffer
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . int nbytes = Ifc.GetLatestTimeslotData(DevNo, pBuffer, BuffSize, nTimeSlot ); }

GetTimeslotData 119

4.116
C++ C

Get Driver Version

DWORD GetVersion(); DWORD GlGetVersion();

Parameters: None Returns: DWORD driver version (major in high byte and minor in low byte)
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . DWORD Version = Ifc.GetVersion(); printf("Driver Version %d.%02d\n", HIBYTE(Version), LOBYTE(Version)); }

4.117
C++ C

Get API Library Version

DWORD GetApiVersion(); DWORD GlGetApiVersion();

Parameters: None Returns:

DWORD driver version (0x00MjMiBd Major/Minor Version Numbers and build number). For example, version 1.3 build 18 is returned as 0x00010312. try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . DWORD ApiVersion = Ifc.GetApiVersion(); printf( " Api Version v%d.%d (build %d) \n", ( ApiVersion >> 16), (ApiVersion >> 8) & 0x000000FF, ApiVersion & 0x000000FF ); }

120

4.118 Get Maximum Time Slot Number

C++ C
BYTE GetMaxTimeslot(); BYTE GlGetMaxTimeslot();

Parameters: None Returns: BYTE maximum timeslot number (23 for T1 and 31 for E1)
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . for (int j = 0; j <= Ifc.GetMaxTimeslot(); j++) { if ( CheckTsAvailable(j) ) { memset(pGlBuf0 + i*NoOfChannels + j, multiframe[(i % NoOfFrames)*NoOfChannels+j], 1); memset(pGlBuf1 + i*NoOfChannels + j, multiframe[(i % NoOfFrames)*NoOfChannels+j], 1); } } }

4.119 Get Maximum Number of Devices Supported by Device Driver

C++ C
BYTE GetMaxDeviceCount(); BYTE GlGetMaxDeviceCount();

Parameters: None Returns: BYTE maximum number of cards supported by device driver

121

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . BYTE MaxDevices = Ifc.GetMaxDeviceCount(); }

GetNoOfDevicesInstalled

4.120
C++ C

Setting On-hook/Off-hook in a Global Transmit Buffer

void SetOnHook(BYTE DeviceNo, int SoftBufferNo, int TS, bool bOnHook = true ); void GlSetOnHook(BYTE DeviceNo, int SoftBufferNo, int TS, bool bOnHook );

Sets on-hook or off-hook signaling bit for a time slot

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) int SoftBufferNo 0 set in Tx global buffer 0, otherwise in Tx global buffer 1 int TS zero relative time slot number bool bOnHook true set on-hook, false off-hook. If omitted, the default is true; Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . // Setting on-hook in global Tx buffer 1 Ifc.SetOnHook( DevNo, 1, 23, true ); }

122

4.121
C++ C

Get Receive Line Frequency

unsigned long ReadRxLineFrequency( BYTE DeviceNo ); unsigned long GlReadRxLineFrequency( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: unsigned long - frequency on the receive line
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . unsigned long freq = Ifc.ReadRxLineFrequency( DevNo ); }

4.122 Enabling Receive and Transmit Buffers

C++ C
bool EnableTxRxBuffer( BYTE DeviceNo, DWORD IoCtlCode ); bool GlEnableTxRxBuffer( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _ActivateTxBuffer enables Tx buffer _ActivateRxBuffer enables Rx buffer Returns: bool - true OK, false failure
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . if ( EnableTxRxBuffer( DevNo, _ActivateRxBuffer ) ) { . . . } }

123

DisableTxRxBuffer

4.123 Disabling Receive and Transmit Buffers

C++ C
bool DisableTxRxBuffer( BYTE DeviceNo, DWORD IoCtlCode ); bool GlDisableTxRxBuffer( BYTE DeviceNo, DWORD IoCtlCode );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD IoCtlCode _DeActivateTxBuffer disables Tx buffer _DeActivateRxBuffer disables Rx buffer Returns: bool - true OK, false failure
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . if ( DisableTxRxBuffer( DevNo, _DeActivateTxBuffer ) ) { . . . } }

EnableTxRxBuffer

124

4.124
C++ C

Transmitting Idle Codes

void LoadTxBufferWithIdleCode( BYTE DeviceNo, UINT StartTs, UINT EndTs ); void GlLoadTxBufferWithIdleCode( BYTE DeviceNo, UINT StartTs, UINT EndTs );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) UINT StartTs, UINT EndTs specify the time slot range to transmit idle code on Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.LoadTxBufferWithIdleCode( DevNo, 0, Ifc.GetMaxTimeslot() ); }

LoadTxBufferWithMf

4.125 Filling Transmit Buffer with a Multiframe

C++ C
void LoadTxBufferWithMf( BYTE DeviceNo, BYTE* pMultiframe ); void GlLoadTxBufferWithMf( BYTE DeviceNo, BYTE* pMultiframe );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) BYTE* pMultiframe pointer to the multiframes bytes to load Returns: Nothing

125

try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.LoadTxBufferWithMF(DevNo, pMultiframe ); Ifc.EnableTxRxBuffer( DevNo, _ActivateTxBuffer); Sleep(200); Ifc.DisableTxRxBuffer( DevNo, _DeActivateTxBuffer); }

LoadTxBufferWithIdleCode

4.126 Disabling Unframed Input

C++ C
void DisableUnframedInput( BYTE DeviceNo ); void GlDisableUnframedInput( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.DisableUnframedInput( DevNo ); }

EnableUnframedInput

126

4.127 Enabling Unframed Input

C++ C
void EnableUnframedInput( BYTE DeviceNo ); void GlEnableUnframedInput( BYTE DeviceNo );

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . Ifc.EnableUnframedInput( DevNo ); }

DisableUnframedInput

4.128 Setting Tx Inversion Mask

C++ C
bool SetTxInvMask(BYTE DeviceNo, DWORD TsMask, BYTE InvMask) BOOL GlSetTxInvMask(BYTE DeviceNo, DWORD TsMask, BYTE InvMask)

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD TsMask timeslots to apply selection mask to (0x80000000 ts0) BYTE InvMask bits to invert (1 causes apropriate bit to invert) Returns: true OK, false - error
Bits defined by the mask in the speicified timeslots from the global buffers are are inverted before transmission.

SetRxInvMask, GetRxInvMask, GetTxInvMask

127

4.129 Setting Rx Inversion Mask

C++ C
bool SetRxInvMask(BYTE DeviceNo, DWORD TsMask, BYTE InvMask) BOOL GlSetRxInvMask(BYTE DeviceNo, DWORD TsMask, BYTE InvMask)

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD TsMask timeslots to apply selection mask to (0x80000000 ts0) BYTE InvMask bits to invert (1 causes apropriate bit to invert) Returns: true OK, false - error
Bits defined by the mask in the speicified timeslots are inverted upon reception before being placed into global buffers.transmission.

SetTxInvMask, GetRxInvMask, GetTxInvMask

4.130 Getting Rx Inversion Mask

C++ C
bool GetRxInvMask(BYTE DeviceNo, DWORD& TsMask, BYTE& InvMask) BOOL GlGetRxInvMask(BYTE DeviceNo, DWORD* pTsMask, BYTE* pInvMask)

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD TsMask timeslots to apply selection mask to (0x80000000 ts0) BYTE InvMask bits to invert (1 causes apropriate bit to invert) Returns: true OK, false - error
Current values of Rx inversion mask and timeslot mask set by the latest SetRxInvMask is retrieved.

SetTxInvMask, SetRxInvMask, GetTxInvMask

128

4.131
C++ C

Getting Tx Inversion Mask

bool GetTxInvMask(BYTE DeviceNo, DWORD& TsMask, BYTE& InvMask) BOOL GlGetTxInvMask(BYTE DeviceNo, DWORD* pTsMask, BYTE* pInvMask)

Parameters: BYTE DeviceNo one relative device number ( <= GetNoOfDevicesInstalled() ) DWORD TsMask timeslots to apply selection mask to (0x80000000 ts0) BYTE InvMask bits to invert (1 causes apropriate bit to invert) Returns: true OK, false - error
Current values of Tx inversion mask and timeslot mask set by the latest SetTxInvMask is retrieved.

SetTxInvMask, SetRxInvMask, GetRxInvMask

129

4.132 BioStream Class. Stream Input/Output

This class makes receiving and sending data using GL Communications T1/E1 card as easy as reading/writing disk files. The class provides blocking and non-blocking input/output operations. It allows transferring data on all channels or on a group of channels specified by mask. It also allows writing in continuous and burst mode. When using BioStream with the C interface, all functions are called with a handle as the first parameter to specify which BioStream instance to perform the function on.

4.132.1 Creating and Initializing the Basic Input Output Stream Object (BioStream constructor).

C++ C

BioStream( GlComInterface* pIfc, BYTE DeviceNo, DWORD ReadChannelMask, DWORD WriteChannelMask ); StreamHandle BioOpenStream (BYTE DeviceNo, DWORD ReadChannelMask, DWORD WriteChannelMask );

Parameters: GlComInterface* pIfc - pointer to GlComInterface object BYTE DeviceNo one relative device number ( <=GlComInterface::GetNoOfDevicesInstalled() ) DWORD ReadChannelMask read channel mask ( 0xC0000000, for example, specifies channels 1 and 2) DWORD WriteChannelMask write channel mask ( 0xFFFFFF00, for example, specifies channels 1 through 24) Returns: Nothing for C++, or a handle to the BioStream Object for C (type StreamHandle).
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . BioStream Bs(&Ifc, SelectedDeviceNo, 0xC0000000, 0xC0000000 ); } }

130

4.132.2 Creating and Initializing the Basic Input Output Stream Object (BioStream constructor).

C++ C

BioStream( GlComInterface* pIfc, BYTE DeviceNo, DWORD ChannelMask) See BioStreamOpen

Parameters: GlComInterface* pIfc - pointer to GlComInterface object BYTE DeviceNo one relative device number ( <=GlComInterface::GetNoOfDevicesInstalled() ) DWORD ChannelMask read and write channel mask ( 0xC0000000, for example, specifies channels 1 and 2) Returns: Nothing
try { GlComInterface Ifc; // Device driver interface object Ifc.Initialize(); // Set default hardware settings . . . BioStream Bs(&Ifc, SelectedDeviceNo, 0xC0000000 ); } }

Read and write channel masks are set to the same value

4.132.3 Destroying the Basic Input Output Stream Object (BioStream destructor).

C++ C

~BioStream() bool BioCloseStream( StreamHandle hBios );

Parameters: StreamHandle hBios handle of BioStream object to perform the function on. Returns: bool -true if object was destroyed, otherwise false.

131

try { BioStream *Handle; Handle = OpenStream(SelectedDeviceNo, 0xC0000000, 0xC0000000 ); . . . CloseStream(Handle); }

4.132.4

Set Read Channel Mask.

C++ C

void SetReadChannelMask( DWORD ChannelMask ); void BioSetReadChannelMask( StreamHandle pBios, DWORD ChannelMask );

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD ChannelMask read channel mask ( 0xC0000000, for example, specifies channels 1 and 2) Returns: Nothing

Read channel mask set by a constructor may be changed by this function. The function also reopens receive stream.

4.132.5

Set Write Channel Mask.

void SetWriteChannelMask( DWORD ChannelMask ); void BioSetWriteChannelMask( StreamHandle pBios, DWORD ChannelMask );

C++ C

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD ChannelMask write channel mask ( 0xC0000000, for example, specifies channels 1 and 2) Returns: Nothing

132

Write channel mask set by a constructor may be changed by this function. The function also reopens transmit stream.

4.132.6

Set Read Margins in Multiframes.

These margins are needed when the application is slow to keep with current driver position so when the driver gets ahead 2*GlobalBufferSize SafeMargins an exception is thrown and the user application can easily catch this event.

C++ C

void SetReadSafeMarginMultiFrames( DWORD MultiFrames ) void BioSetReadSafeMarginMultiFrames( StreamHandle pBios, DWORD MultiFrames)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD MultiFrames multiframes number in margins. Returns: Nothing SetWriteSafeMarginMultiframes, SetReadSafeMarginBytes, SetWriteSafeMarginBytes

4.132.7

Set Write Margins in Multiframes.

These margins are needed to write ahead of the driver that is peeking up data from the global transmit buffers. C++ void SetWriteSafeMarginMultiFrames( DWORD MultiFrames )

void BioSetWriteSafeMarginMultiFrames( StreamHandle pBios, DWORD MultiFrames )

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD MultiFrames multiframes number in margins. Returns: Nothing

133

SetReadSafeMarginMultiframes, SetReadSafeMarginBytes, SetWriteSafeMarginBytes

It is recommended to have safe write margins not less than 16 multiframes

4.132.8

Set Read Margins in Bytes.

These margins are needed when the application is slow to keep with current driver position so when the driver gets ahead 2*GlobalBufferSize SafeMargins an exception is thrown and the user application can easily catch this event.

C++ C

void SetReadSafeMarginBytes( DWORD Bytes ) void BioSetReadSafeMarginBytes( StreamHandle pBios, DWORD Bytes )

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD Bytes byte number in margins. Returns: Nothing SetReadSafeMarginMultiframes, SetWriteSafeMarginMultiframes, SetWriteSafeMarginBytes

134

4.132.9

Set Write Margins in Bytes.

These margins are needed to write ahead of the driver that is picking up data from the global transmit buffers.

C++ C

void SetWriteSafeMarginBytes( DWORD Bytes ) void BioSetWriteSafeMarginBytes( StreamHandle pBios, DWORD Bytes )

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. DWORD Bytes multiframes number in bytes. Returns: Nothing
It is recommended to have safe write margins not less than 4608 bytes (12*16*24)

SetReadSafeMarginMultiframes, SetWriteSafeMarginMultiframes, SetReadSafeMarginBytes

4.132.10

Get Missed Receive Bytes Count.

Obtains number of total missed bytes when application is too slow to read C++ DWORD GetReadMissedBytesCount()

DWORD BioGetReadMissedBytesCount(StreamHandle pBios)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. Returns: DWORD bytes missed GetWriteMissedBytesCount

135

4.132.11

Get Missed Transmit Bytes Count.

Obtains number of total missed bytes when application is too fast to write in nonblocking mode C++ DWORD GetWriteMissedBytesCount()

DWORD BioGetWriteMissedBytesCount(StreamHandle pBios)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. Returns: DWORD bytes missed GetReadMissedBytesCount

4.132.12

Read Stream (Receive).

Receives in blocking or non-blocking mode from the channels specified by mask

C++ C

DWORD Read(PBYTE pOutBuffer, DWORD Length, bool bWait = true ); DWORD BioRead(StreamHandle pBios, PBYTE pOutBuffer, DWORD Length, bool bWait);

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. PBYTE pOutBuffer - user supplied buffer to read into DWORD Length - bytes to read bool bWait - true(default) read in the blocking mode (return after all requested bytes are read), false return only bytes that are available Returns: DWORD bytes read. If an error, typically an underrun error occurs, the C++ interface throws an exception, while C interface returns value -1 (0xFFFFFFFF). Write, BioWrite

136

Bytes are received from channels specified by the ReadChannelMask in constructor or SetReadChannelMask function. See Record.exe example for usage

4.132.13

Write Stream (Transmit).

Transmits in blocking or non-blocking mode to the channels specified by mask

C++ C

DWORD Write(PBYTE pInBuffer, DWORD Length, bool bWait = true, bool bContinuous = true ); DWORD BioWrite(StreamHandle pBios, PBYTE pInBuffer, DWORD Length, bool bWait);

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. PBYTE pInputBuffer - user supplied buffer to write from DWORD Length - bytes to write bool bWait - true(default) write in the blocking mode (return after all requested bytes are written), false write only bytes that are available for transmission bool bContinuous - true(default) write continuously, false write so driver can transmit them as soon as possible Returns: DWORD bytes written. If an error, typically an overrun error occurs, the C++ interface throws an exception, while C interface returns value -1 (0xFFFFFFFF).

Read, BioRead

137

Bytes are transmitted to the channels specified by the WriteChannelMask in constructor or SetWriteChannelMask function. First write is opening the stream safe margin bytes ahead of the current driver position. Application should at this point write sufficient bytes to stay ahead of driver to avoid underrun exception See play.exe example for usage

4.132.14

Reopen Stream for Receiving.

Reopen for receiving

C++ C

void ReopenRead() void BioReopenRead(StreamHandle pBios)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. Returns: Nothing ReopenWrite, Reopen
Use this function after overrun exception occurs

4.132.15

Reopen Stream for Transmitting.

Reopen for transmitting

C++ C

void ReopenWrite() void BioReopenWrite(StreamHandle pBios)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. Returns: Nothing

ReopenRead, Reopen 138

4.132.16

Reopen Stream for Receiving, Transmitting, or both.

Reopen for receiving and/or transmitting

C++ C

void Reopen(bool bRead=true, bool bWrite=true) void BioReopen(StreamHandle pBios, bool bRead, bool bWrite)

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. bool bRead true reopen for receiving bool bWrite true reopen for transmitting Returns: Nothing ReopenRead, ReopenWrite

4.132.17

Fill Global Transmit Buffers with Idle Code

Fills transmit channels specified by the channel mask with the idle code

C++ C

void FillTxChannels( BYTE FillerByte ); void BioFillTxChannels( StreamHandle pBios, BYTE FillerByte );

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. BYTE FillerByte - byte to use as the idle code to fill in channels in global transmit buffers. Only channels specified by the channel mask are affected. Returns: nothing Overloaded FillTxChannels, FillTxGlobalBuffers

139

Bytes are filled according to the channels specified by the WriteChannelMask in constructor or SetWriteChannelMask function. See play.exe example for usage

4.132.18

Fill Global Transmit Buffers with Byte String

Fills transmit channels specified by the channel mask with the idle code

C++ C

void FillTxChannels( BYTE* pFillerBytes, DWORD Length ); void BioFillTxChannelsWithLength( StreamHandle pBios, BYTE* pFillerBytes, DWORD Length );

Parameters: StreamHandle pBios handle of BioStream object to perform the function on. BYTE* pFillerBytes - byte string pointer to use to fill in channels in global transmit buffers. Only channels specified by the channel mask are affected. DWORD Length length of the filler byte string Returns: nothing Overloaded FillTxChannels, FillTxGlobalBuffers

140

Bytes are filled according to the channels specified by the WriteChannelMask in constructor or SetWriteChannelMask function.

4.132.19

Calculate Channel Mask

Calculates and returns the channel mask between 2 timeslots

C++ C

N/A DWORD BioCalculateChannelMask( int StartTs, int EndTs );

Parameters: int StartTs int EndTs Returns: DWORD -channel mask -starting timeslot of channel mask -ending timeslot of channel mask

This only calculates a channel mask over consecutive timeslots.

From this point on, there is no C implentation for the functions.

141

4.133 BioStreamEx Class. Signaling Bits Processing.

The BioStreamEx class is derived from BioStream. It provides all the interfaces of the BioStream class and methods to receive and transmit signaling bits for both T1 and E1. For T1 multiframes consisting of 12 frames, the 8th bit of the 6th frame is used for A bit and the 8th bit of the 12th frame is used for the signalling bit B. For T1 multiframes consisting of 24 frames, the 8th bit of the 6th, 12th, 18th and 24th frame is used for the signalling bits A,B,C,D accordingly. For E1 channel associated signalling the signalling bits are transmitted in timeslot 16. The signalling bits are transmitted for channel 1-15 and 16-31 ( zero relative timeslots 115, 17-31 according to the following table.
Time slot 16 of frame 0 0000xyxx Time slot 16 of frame 1 abcd channel 1 abcd channel 16 Time slot 16 of frame 2 abcd channel 2 abcd channel 17

Time slot 16 of frame 15 abcd channel 15 abcd channel 30

The BioStreamEx class methods allows to receive and transmit data with signalling bits. The data should be transmitted and received on a single 64k channel, i.e. timeslot mask MUST specify exactly one channel for data.
SigBitsAsyncIo class provides transmitting and receiving signaling bits on multiple channels.

4.133.1

BioStreamEx Constructor

BioStreamEx( GlComInterface* pIfc, BYTE DeviceNo, DWORD ReadChannelMask, DWORD WriteChannelMask ) Parameters: GlComInterface* pIfc - pointer to the GlComInterface object BYTE DeviceNo - one relative device number (card #) DWORD ReadChannelMask - read channel mask (0x80000000 corresponds to timeslot 0, 0x40000000 - TS 1 etc.) When the read channel mask is not zero, the write channel mask MUST be zero and the object instance is used to read signalling bits and data DWORD WriteChannelMask - write channel mask (0x80000000 corresponds to timeslot 0, 0x40000000 - TS 1 etc.) When the write channel mask is not zero, the read channel mask MUST be zero and the object instance is used to write signalling bits only and/or signalling bits and data. Returns: Nothing 142

4.133.2

Reading Signalling Bits and Data

4.133.2.1 Signaling Bits Transition Item Structure

When reading data and signalling bits it is important to know when the signalling transitions are taking place. This information is reported by means of total read bytes on the selected timeslot since the moment when the stream was opened. The number of bytes is the total number of bytes before the multiframe where the signalling bit transition has occurred. On the first reading (implicit stream opening) the total signalling bytes count before transition is equal to zero and the current value of the signaling bits is returned.
struct SignalTransition { unsigned __int64 TotalBytesBeforeSig; // bytes since opening unsigned char SigBits; // Signaling bits SignalTransition( const unsigned __int64& Total, unsigned char Sig ) : TotalBytesBeforeSig(Total), SigBits(Sig) {} };

Signalling bits correspond to the following bit masks in the SigBits byte: A - 0x80, B - 0x40, C - 0x20, D - 0x10

143

4.133.2.2 Reading Data and Signalling Bits

Prerequsite: The BioStreamEx object must be created with single channel in the read channel mask and zero write channel mask. DWORD ReadDataAndSigBits(PBYTE pOutBuffer, DWORD Length, list<SignalTransition>& SigTransitions, bool fWait = true, bool fClearTransitions = true ) Parameters: PBYTE pOutBuffer DWORD Length - caller buffer where read data must be placed - bytes to read

list<SignalTransition>& SigTransitions - list of signalling transitions occurred. When the stream is just opened the initial signalling bit status is reported on the first read with the number of preceding bytes equal to zero. Only the signalling bit transitions are reported, i.e. if there is no change in the signalling bits the list will be empty. The list is cleared by the function before any signalling transitions are placed if the fClearTransitions parameter is set to true. See previous chapter on the SignalTransition structure description. signaling transition list, each item in the list is structure containing number of preceding bytes for timeline and the new signaling transition
struct SignalTransition { unsigned __int64 TotalBytesBeforeSig; // bytes since opening unsigned char SigBits; // Signaling bits SignalTransition( const unsigned __int64& Total, unsigned char Sig ) : TotalBytesBeforeSig(Total), SigBits(Sig) {} };

bool fWait

- true means do not return before the specified number of data bytes are read, false means read as much data as available - true - clear transition list parameter (SigTransitions) first DWORD - number of data bytes actually read

bool fClearTransitions Returns:

144

list<SignalTransition> TransitionHistory; // non-blocking clear transitions pBios->ReadDataAndSigBits( Data, sizeof(Data), SigTransitions, false ); for ( list<SignalTransition>::iterator it = TransitionHistory.begin(); it != TransitionHistory.end(); it++ ) { printf( "A=%c B=%c C=%c D=%c BytesBeforeSigTransitionMF = %I64u\n", (*it).SigBits & 0x80 ? '1' : '0', (*it).SigBits & 0x40 ? '1' : '0', (*it).SigBits & 0x20 ? '1' : '0', (*it).SigBits & 0x10 ? '1' : '0', (*it).TotalBytesBeforeSig ); }

4.133.2.3 Reading Signaling Transitions Only

This functions is similar to the previous one but it retrieves signaling transitions only WORD ReadSigBits( DWORD Length, list<SignalTransition>& SigTransitions, bool fWait = true, bool fClearTransitions = true ) Parameters: DWORD Length - number of bytes to receive ( to specify time interval for signaling transition history)

list<SignalTransition>& SigTransitions - signaling transition list, each item in the list is structure containing number of preceding bytes for timeline and the new signaling transition
struct SignalTransition { unsigned __int64 TotalBytesBeforeSig; // bytes since opening unsigned char SigBits; // Signaling bits SignalTransition( const unsigned __int64& Total, unsigned char Sig ) : TotalBytesBeforeSig(Total), SigBits(Sig) {} };

bool bWait

- (default true) wait till all the specified bytes are transmitted

bool bClearTransions- true clears the SigTransitions list first, false just appends new transitions Returns: number of data bytes received and discarded

145

list<SignalTransition> TransitionHistory; // non-blocking clear transitions pBios->ReadSigBits( Length, SigTransitions, false ); for ( list<SignalTransition>::iterator it = TransitionHistory.begin(); it != TransitionHistory.end(); it++ ) { printf( "A=%c B=%c C=%c D=%c BytesBeforeSigTransitionMF = %I64u\n", (*it).SigBits & 0x80 ? '1' : '0', (*it).SigBits & 0x40 ? '1' : '0', (*it).SigBits & 0x20 ? '1' : '0', (*it).SigBits & 0x10 ? '1' : '0', (*it).TotalBytesBeforeSig ); }

4.133.3 Setting Signalling Bits for the Subsequent Signalling or Data+Signalling Transmission
bool SetSigBits( unsigned char SigBits) Prerequisite: the BioStreamEx instance must be created with single timeslot set in the write channel mask parameter and read channel mask set to zero. Parameters: unsigned char SigBits - signalling bits to be set for the subsequent transmission of signalling bits only or data and signalling. Signaling bits correspond to the following bit masks in the SigBits byte: A - 0x80, B - 0x40, C - 0x20, D - 0x10

Returns:
{

- true if successful

unsigned char SigBits = 0xF0; BioStreamEx Bios( &Ifc, SelectedDeviceNo, 0, TsMask ); // open for writing Bios.SetSigBits( SigBits ); Bios.WriteSigBits(); // write and wait till xmitted // or Bios.WriteSigBits( SigBits, true ) // instead of two calls SetSigBits+WriteSigBits(true); }

146

4.133.4

Transmit Signalling Bits

bool WriteSigBits(bool fWaitTillXmitted = true ) Prerequisite: the BioStreamEx instance must be created with single timeslot set in the write channel mask parameter and read channel mask set to zero. Parameters: bool fWaitTillXmitted - true waits several milliseconds to guaranty the signalling bits set by SetSigBits were transmitted. If false is specified, the function returns immediately, but if the BioStreamEx object is destroyed before signalling bits are processed, new signalling bits are not transmitted. Returns:
{ unsigned char SigBits = 0xF0; BioStreamEx Bios( &Ifc, SelectedDeviceNo, 0, TsMask ); // open for writing Bios.WriteSigBits( SigBits, true ); }

- true if successful

4.133.5

Transmitting Data and Signalling Bits

DWORD WriteDataAndSigBits(PBYTE pInBuffer, DWORD Length, bool bWait = true, bool bContinuous = true ); Prerequisite: the BioStreamEx instance must be created with single timeslot set in the write channel mask parameter and read channel mask set to zero. Signalling bits set by SetSigBits are transmitted along with data. No signalling transition will be possible until data is transmitted. Parameters: PBYTE pInBuffer DWORD Length bool bWait bool bContinuous Returns: - user supplied buffer to write from - bytes to write - true(default) write in the blocking mode (return after all requested bytes are written), false write only bytes that are available for transmission - true(default) write continuously, false write so driver can transmit them as soon as possible

DWORD bytes written. If an error, typically an overrun error occurs, the function throws an exception

147

To control time of the signalling transitions calculate amount of data transmitted and set bWait parameter to true to ensure all data bytes are transmitted:
SetSigBits( Sig1); // set initial signalling bits WriteDataAndSigBits( Data1, Data1Length, true ); // Data1Length specifies // time before the next signalling transition SetSigBits( Sig2); // set initial signalling bits WriteDataAndSigBits( Data2, Data2Length, true ); // data with new signalling SetSigBits(Sig3); WriteSigBits();

148

4.134 SigBitsAsyncIo Class. Receiving and Transmitting Signaling Bits only on Multiple Channels
The class has a higher level interface than BioStreamEx to the signaling bits. It also provides a thread for receiving signaling bits making application design simpler.

4.134.1

SigBitsAsyncIo Constructor

SigBitsAsyncIo() Parameters: none Returns: nothing

4.134.2 Opening SigBitsAsyncIo for Singnaling Bits Reading or Writing.

int open( GlComInterface* pIfc, BYTE DevNo, DWORD TsMask, bool fOpenWrite = false, DWORD MaxQueuedSignals = 0x0010000 ); Parameters: GlComInterface* pIfc BYTE DevNo DWORD TsMask bool fOpenWrite - pointer to the device driver interface - one relative device number (card #) - timeslot mask (0x80000000 corresponds to timeslot 0, 0x40000000 - TS 1 etc.) - true means opening for transmitting signaling bits, false receiving signaling bits (default false open for reading)

DWORD MaxQueuedSignals maximum number of signals to queue for receiving. Default is 64K.

149

SigBitsAsyncIo SigBitsAsyncRd; SigBitsAsyncIo SigBitsAsyncWr; assert( !SigBitsAsyncRd.open( &Ifc, SelectedDeviceNo, NoOfChannels == 24 ? 0xFFFFFF00 : 0xFFFFFFFF ) ); assert( !SigBitsAsyncWr.open( &Ifc, SelectedDeviceNo, NoOfChannels == 24 ? 0x55555500 : 0x55555555 ) );

4.134.3
void close();

Stopping Receiving or Transmitting Signaling Bits

Parameters: none Returns: nothing

4.134.4
Parameters:

Reading Signaling Transitions

bool read( AbcdSignalInfo& FrameInfo, DWORD WaitMs = INFINITE );

AbcdSignalInfo& FrameInfo signaling transition information

struct AbcdSignalInfo { BYTE TimeStamp[8]; unsigned char DevNo; unsigned char fSubchannelsUsed : 1; unsigned char TimeslotForSubchannels : 5; unsigned char StartTs : 5; // start ts or subchannel unsigned char EndTs : 5; // end ts or subchannel BYTE ErrorFlag; BYTE Signal; };

The TimeStamp provides the time of transition with 100 nanoseconds resolution. The following function can be used to convert the time to the displayable time format:
void FormatSystemTime( const unsigned __int64& Time, // time to format char* pszFormattedTime ) // output of formatted time { unsigned __int64 mkSec; unsigned __int64 Sec; unsigned __int64 HH; unsigned __int64 MM; SYSTEMTIME systime;

150

mkSec = ( Time % 10000000 ) / 10; FileTimeToSystemTime( (LPFILETIME)&Time, &systime ); HH = systime.wHour; MM = systime.wMinute; Sec = systime.wSecond; sprintf( pszFormattedTime, "%I64u:%02I64u:%02I64u.%06I64u", HH, MM, Sec, mkSec ); }

DevNo specifies the device number ( 1 relative ) StartTs specifies the zero relative timeslot where signaling transition took place Signal specifies the signal in the first bits ( 0x80 A bit, 0x40 B bit etc ) DWORD WaitMs Returns: - time in milliseconds to wait ( 0 return immediately )

true if a signaling transition occurred in at least one timeslot selected in the open function.

4.134.5

Transmitting Signals on All Selected Timeslots

bool write( unsigned char signal ) Parameters: ] unsigned char signal - signal to transmit on all timeslots specified in open. true if a signaling transition occurred in at least one timeslot selected in Signalling bits correspond to the following bit masks in the SigBits byte: A - 0x80, B - 0x40, C - 0x20, D - 0x10 Returns: true success

4.134.6

Access to BioStreamEx for Accesing Individual Timeslots

When SigBitsAsyncIo object is opened for xmitting a number of BioStreamEx objects are created one per each selected timeslot. The following function provides a direct access to these objects enabling individual control: list<BioStreamEx*>& GetBioStreamExList() Parameters: Returns: none STL list of pointers to the opened BioStreamEx objects handling individual timeslots.

151

4.134.7

Retrieving Receive Event Handle for Signaling Transitions

When the SigBitsAsyncIo object is opened for reading and event is created that is signaled each time an unread signaling transition is queued for read-ing. An application can wait for the signaling transition on any of the selected timeslots along with waiting for some other event using WaitForMultipleObjects(Ex) API. If an application needs to wait just for signaling transition an easier way is just to use the bloking read function specifying INFINITE waiting period. HANDLE GetQueuedEventHandle() Parameters: none Returns: HANDLE of the event that is signaled when new signaling transitions are Queued. The SigBitsAsyncIo must be open for reading.

4.134.8

Getting Number of Queued Signaling Transitions

DWORD GetQueuedSignals() Parameters: none Returns: number of queued signaling transitions available to be read

4.134.9

Getting Number of Skipped Signals

DWORD GetSkippedSignals () Parameters: none Returns: number of skipped signals that will increment when the application does not issue read and the maximum size of the signaling transition queue is exceeded.

4.134.10

Getting Number of Underruns

DWORD GetOverUnderRuns() Parameters: none Returns: number of underruns encountered during reading

152

4.135 Determining if the Receive Thread is Alive

bool IsThreadAlive() When the SigBitsAsyncIo is opened for reading a thread is created for continuous reading of the signaling transitions. This function returns true if thread is still alive. Parameters: none Returns: true if thread is alive

153

4.136 BitStream Class. Subchannel Input

The BitStream class extends the capability of the BioStream class to reading and writing subchannels in one or several timeslots. Each timeslot carries 8 bits per frame. Each bit represents a 8 kbps subchannel. BitStream allows specifying bit mask to select several subchannels, for example, specifying bit mask 0xFE selects 56 kbps channel in a timeslot vs. 64 kbps (full bandwidth of a channel). 56 kbps channels are used by some industry implementations. The subchannels must be consecutive, 0x3C is OK, but 0x3D is not.
The BitStream class extracts received data from T1/E1 timeslot(s). Use OutBitStream to build outgoing stream for transmission.

OutBitStream, BioStream, FdlStream

4.136.1
BitStream() Parameters: none Returns: Nothing

BitStream Constructors

BitStream(BYTE BitMask, bool bInvert = false); Parameters: BYTE BitMask - specifies subchannels to use, 0xFE for example should be specified for 56 kbps. Bits MUST be consecutive. 0x3C, for example, is correct, 0x3D is incorrect. bool bInvert - false no bit inversion, true inverts bits in each byte, so byte 0x80 becomes 0x01 Returns: Nothing

154

4.136.2

Setting Bit Mask

void SetBitMask( BYTE BitMask ) Sets subchannel bit mask. This method also resets the stream. Parameters: BYTE BitMask - specifies subchannels to use, 0xFE for example should be specified for 56 kbps. Bits MUST be consecutive. 0x3C, for example, is correct, 0x3D is incorrect. Returns: Nothing

4.136.3

Getting Bit Mask

BYTE GetBitMask() This method returns bit mask set in constructor or in the SetBitMask method Parameters: none Returns: BYTE - subchannels bit mask used, 0xFE for 56 kbps

4.136.4

Set or Unset Bit Inversion

void SetInvert( bool bInvert ) This function sets or unsets bit inversion. The inversion produces output stream with bits inverted the most significant bit (MSB) in each byte becomes the least significant bit (LSB), for example byte 0x82 becomes 0x41 ( read bits right to left instead left to right ) Parameters: bool bInvert - true sets inversion, false - no inversion Returns: Nothing

155

4.136.5

Get Inversion Setting

bool GetInvert() Gets current inversion setting Parameters: none Returns: bool - true inversion is set, false - no inversion

156

4.136.6
void Reset()

Resetting Stream

This function interrupts continuous stream and starts it again. Parameters: none Returns: Nothing

4.136.7

Reading Stream

DWORD Extract( PBYTE pInp, DWORD InpLen, PBYTE pOut, DWORD OutLen ) This method extracts data from input stream (concatenation of timeslot(s) values usually produced by BioStream class according to bit mask and puts integral number of bytes in the output buffer. The method remembers incomplete bits and will put them first on the following Extract call before putting new bits. Parameters: PBYTE pInp DWORD InpLen PBYTE pOut DWORD OutLen Returns: DWORD - input buffer pointer - input buffer length - output buffer pointer - output buffer length, should be large enough to accommodate all the data including up to 7 bits that may have been left from previous call - number of bytes in the output buffer.

4.136.8

Get Payload Bit Count

BYTE GetPayloadBitCount() Gets number of 8 kbps subchannels used Parameters: none Returns: BYTE - Number of subchannels used 1..8. For example, for mask 0xFE the returned value will be 7. 157

4.137 OutBitStream Class. Subchannel Output

This class handles output in the specified subchannels, enabling for example, writing at a rate of 56 kbps. The class produces an output byte array with the bits set according to the subchannel bit mask and bits correspondent to zero bits in the bit mask set to one or zero. To multiplex several streams on a timeslot multiple objects must be created and the output byte strings must be OR-ed on byte by byte basis. The resulting output byte stream should be used as a parameter in BioStream::Write function to actually transmit the data over T1/E1 line. BitStream, FdlStream, BioStream

4.137.1

Constructor

OutBitStream(BYTE BitMask = 0, bool bInvert = false, bool bFillerOne = false) Parameters: BYTE BitMask - sets the 8 kbps subchannels used, specify 0xFE for 56 kbps bool bInvert bool bFillerOne true MSB to LSB invert, on byte by byte basis, so 0x80 becomes 0x01 true fill in bits correspondent to zero bits in the BitMask with ones, false (default) fill in bits correspondent to zero bits in the BitMask with zeroes.

4.137.2
Parameters:

Reinitialization of the OutBitStream Instance

void Init( BYTE BitMask, bool bInvert = false, bool bFillerOne = false )

BYTE BitMask

- sets the 8 kbps subchannels used, specify 0xFE for 56 kbps. Bits set to one define what output bits used when input bits are copied to output true MSB to LSB invert, on byte by byte basis, so 0x80 becomes 0x01 true fill in bits correspondent to zero bits in the BitMask with ones, false (default) fill in bits correspondent to zero bits in the BitMask with zeroes.

bool bInvert bool bFillerOne -

Returns: Nothing 158

4.137.3
Parameters: Returns:

Getting Bit Mask

none BYTE - bit mask, bits one are used on output when copying each input bit to the corresponding output bit. Use 0xFE for 56 kbps channels

BYTE GetBitMask()

4.137.4
Parameters: Returns:

Get Inversion
none bool - true class set to invert MSB->LSB so 0x80 becomes 0x01

bool GetInvert()

4.137.5
Parameters: Returns:

Get Filler for Zero Mask Bits

none bool - true if bits corresponding zero mask bits should be filled with ones, otherwise they are filled with zeroes.

bool GetFiller()

159

4.137.6

Write Subchannel Stream

DWORD Put( PBYTE pInp, DWORD InpLen, PBYTE pOut, DWORD OutLen ) This function writes each input bit to the output stream bytes in the positions defined by ones in the bit mask. The output bits correspondents to the zero bits in the mask are filled with zeroes or ones depending on the filler flag. When several subchannels need to be multiplexed in an output timeslots, the filler flag should be false and two objects must be used. The output byte strings from these two objects should be then OR-ed to produce merged string.
For example, Input string=0x4A3BFE, BitMask=0xF0, Filler=false yield output=0x40A030B0F0E0 Input string=0x4A3BFE, BitMask=0xF0, Filler=true yield output=0x4FAF3FBFFFEF Input string=0x4A, BitMask=0x80, Filler=false yield output=0x0080000080008000

The output always has integral number of bytes. Carry over bits will be put at the beginning of the output buffer on the successive Put call. Parameters: PBYTE pInp DWORD InpLen PBYTE pOut DWORD OutLen - pointer to the input bytes - input length in bytes - pointer to output buffer, that should be large enough - output buffer length, must be large enough to accommodate all the input bits, OutLen >= ( InpLen + 2 ) * 8 / BitsInMask

Returns:

DWORD - length of the output in bytes

BioStream* pBios; OutBitStream Obs( 0xFE, false, false ); // 56 kbps, no inversion, filler zeroes DWORD OutLen = Obs.( (PBYTE)TempBuf, TempLen, OutBuf, OutLen ); // Make stream DWORD ActLen = pBios->Write( OutBuf, OutLen, false ); // Actually write to line

160

4.138 MsbStuffBits. HDLC Bit Stuffing.

The HDLC is used to encode messages. Messages are separated by one or more flags. Each flag is the bit sequence 01111110. Sequence of message data bits, called frames are always separated by flags indicating the start and the end of a frame. Encoded frame data cannot contain more than five consecutive ones. After each five consecutive ones a zero bit is inserted; this is called bit stuffing. The MsbStuffBits function always produces integral number of bytes on output and takes care about remembering carry over bits. void MsbStuffBits( const BYTE* pIn, DWORD InLen, PBYTE pOut, DWORD& OutLen, DWORD& RemBits ); Parameters: const BYTE* pIn DWORD InLen PBYTE pOut DWORD& OutLen pointer to iput frame - input frame length - pointer to the output buffer

- (INPUT/OUTPUT) output buffer length. The output buffer should be large enough to accommodate stuffed bits ( 6 * InLen / 5 + flagCount ) DWORD& RemBits - (INPUT/OUTPUT) this parameter is used to remember the number of carry-over bits. Initially it should be multiple of 8 specifying the number of flags ( preceeding flags * 8 ). On the successive calls it add 8 * extraFlags if more than one flag should be put before each frame. Add nothing if just one flag. Returns: BitRemove
DWORD RemBits = InitialFlags * 8; MsbStuffBits( pInRecord, // pointer to input buffer to stuff 0, // just flags pOutBuf, OutLen, RemBits); // MsbStuffBits( pInRecord, // pointer to input buffer containing original frame InLength, // frame length pOutBuf, OutLen, RemBits+8*1); // One extra flag ( two flags before frame )

nothing

161

4.139 BitRemove Class. HDLC Zero Bit Removal

This is a complimentary class to the MsbStuffBits function. It removes stuffed zero bits producing original frames. The output produces a list of frames in the buffer supplied by the caller. The frames in list may include malformed frames if the encoding is incorrect. Check the frame flag to find out if the frame is OK or not. The OK frames have zero bits deleted while malformed frames contain original stuffed input including inserted zero bits. MsbStuffBits

4.139.1
Parameters:

BitRemove Constructor

BitRemove(DWORD MaxFrameSize = cMaxBufferSize/2 )

DWORD MaxFrameSize - maximum frame size, should not exceed 16K. It is recommended to use default value, i.e. specify no parameter.

4.139.2

Remove Stuffed Zero Bits

DWORD parse( PBYTE pInpBuffer, DWORD InpLength, PBYTE pOutFrames, DWORD OutLength) Parameters: PBYTE pInpBuffer - pointer to the input buffer DWORD InpLength - input buffer length PBYTE pOutFrames - output buffer to fill with frames DWORD OutLength - bytes available in the output buffer, should be large enough to contain output frames with bits removed and header information Returns: DWORD - if OK, error code if failed The output buffer is filled with the output frames and malformed frames if any. The normal frames have zero bits removed, malformed frames include stuffed bits to help diagnosing the problem. The frames comprise a list using the following data structure at the beginning:
struct BrOutputList { DWORD pFrameCount; DWORD pErrFrameCount; BrOutputFrame OutputFrames; };

162

Followed by frames:
struct BrOutputFrame { unsigned __int64 TotalInputBytesBeforeFrame; // Since reset or initialization DWORD Length; // Data length bool bOkFrame; // true when OK, false - malformed BYTE OffsErrFrameStartBit; // Offset where the first bit of malformed // frame started BYTE reserved1; BYTE reserved2; BYTE Data[1]; // Data };

BitRemove Br; Br.parse( pInpBuf, InputBufLen, pOutBuf, OutBufLen ); BrOutputList* pList = (BrOutputList*)( pOutBuf ); BrOutputFrame* pFr = &pList->OutputFrames; TotalFrCount += pList->pFrameCount + pList->pErrFrameCount; DWORD Time = pFr->TotalInputBytesBeforeFrame * 125 / Channels; // Time in mkS while ( bNotEndOf Frames ) { BrOutputFrame* pFrame = pFr; size_t len = pFrame->Length; if ( pFrame->bOkFrame) { BYTE Crc[2]; CalculateCrc( pFrame->Data, len, Crc ); if ( Crc[0] == 0xE2 && Crc[1] == 0xF0 ) Trec.ErrorFlag = 0; else Trec.ErrorFlag = ErrorFlagCrc; } pFr = (BrOutputFrame*)&(pFr)->Data[pFr->Length]; // Next frame }

4.139.3
void clear();

Reset Input

Resets input, starts looking for the flags. Parameters: none Returns: nothing

163

4.139.4

Get Statistics

void getCounts( uint64& TotalInpBytes, uint64& TotalOutputBytes, uint64& TotalFrames, uint64& TotalFlags, uint64& DiscardedFrames) Parameters: uint64& TotalInpBytes uint64& TotalOutputBytes uint64& TotalFrames uint64& TotalFlags - returns total input bytes processed so far - returns total output bytes produced so far - returns total frames produced so far - returns total flags encountered

uint64& DiscardedFrames - returns malformed frames encountered Returns: nothing

4.139.5

Set Counters

void setCounts( uint64 TotalInpBytes, uint64 TotalOutputBytes, uint64 TotalFrames, uint64 TotalFlags, uint64 DiscardedFrames) Parameters: uint64 TotalInpBytes uint64& TotalOutputBytes uint64& TotalFrames uint64& TotalFlags - total input bytes processed - total output bytes produced - total frames produced - total flags encountered

uint64& DiscardedFrames - malformed frames encountered Returns: nothing

164

4.139.6

Get Statistics and Reset Counters

void resetCounts( uint64& TotalInpBytes, uint64& TotalOutputBytes, uint64& TotalFrames, uint64& TotalFlags, uint64& DiscardedFrames) This method first gets the statistics as getCounts and then resets all counters to zero Parameters: uint64& TotalInpBytes uint64& TotalOutputBytes uint64& TotalFrames uint64& TotalFlags - returns total input bytes processed so far - returns total output bytes produced so far - returns total frames produced so far - returns total flags encountered

uint64& DiscardedFrames - returns malformed frames encountered Returns: nothing

165

4.140 FdlStream Class. Facility Data Link (FDL) Input/Output

The FDL is a 4 kbps channel used with 193E (ESF) framing format on T1 lines. The FdlStream class also enables reading and writing FPS ( frame patter sequence) bits and CRC bits. The class can also be used for 193s (D4) framing to read/write Ft/Fs bits. This class cannot be used for E1 devices. BitStream, BioStream

4.140.1

Constructor

FdlStream( GlComInterface* pIfc, BYTE DeviceNo, BYTE ReadSubchannelMask, BYTE WriteSubchannelMask ) Parameters: GlComInterface* pIfc BYTE DeviceNo BYTE ReadSubchannelMask - pointer to the device drive interface object - one relative device number to read/write - defines what to read: FDL and/or FPS and or CRC bits for ESF Ft/Fs for D4 The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll - defines what to write: FDL and/or FPS and or CRC bits Ft/Fs for D4

BYTE WriteSubchannelMask

166

The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll

167

4.141 Reinitialize FdlStream

void Init( GlComInterface* pIfc, BYTE DeviceNo, BYTE ReadSubchannelMask, BYTE WriteSubchannelMask ) Resets the stream and allows to change subchannel specification, i.e. what to read or write Parameters: GlComInterface* pIfc BYTE DeviceNo BYTE ReadSubchannelMask - pointer to the device drive interface object - one relative device number to read/write - defines what to read: FDL and/or FPS and or CRC bits for ESF Ft/Fs for D4 The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll - defines what to write: FDL and/or FPS and or CRC bits Ft/Fs for D4 The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll

BYTE WriteSubchannelMask

Returns: nothing

168

4.141.1

Set New Read Subchannel Mask

void SetReadSubchannelMask( BYTE SubchannelMask ) Sets a new read mask and resets subchannel mask Parameters: BYTE SubchannelMask - defines what to read: FDL and/or FPS and or CRC bits for ESF Ft/Fs for D4 The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll

Returns:

nothing

4.141.2

Set New Write Subchannel Mask

void SetWriteSubchannelMask( BYTE SubchannelMask ) Sets a new write mask and resets subchannel mask Parameters: BYTE SubchannelMask - defines what to write: FDL and/or FPS and or CRC bits for ESF Ft/Fs for D4 The following masks are defined for ESF: FdlEsfMaskData FdlEsfMaskCrc FdlEsfMaskFps FdlEsfMaskAll The following bit masks are defined for D4: FdlD4MaskTerminal FdlD4MaskSignal FdlD4MaskAll

Returns:

nothing

169

4.141.3

Set Safe Margins for Reading in Multiframes

Sets safe margins for reading to avoid driver underrun condition void SetReadSafeMarginMultiFrames( DWORD MultiFrames ) Parameters: DWORD MultiFrames Returns: nothing - safe margins in multiframes, recommended value is at least 12 multiframes

It is recommended to use default values, i.e. do not call this function at all

4.141.4

Set Safe Margins for Writing in Multiframes

Sets safe margins for reading to avoid the driver overrun condition void SetWriteSafeMarginMultiFrames( DWORD MultiFrames ) Parameters: DWORD MultiFrames Returns: nothing - safe margins in multiframes, recommended value is at least 12 multiframes

It 's recommended to use default values, i.e. do not call this function at all

4.141.5

Set Safe Margins for Reading in Bytes

Sets safe margins for reading to avoid the driver underrun condition void SetReadSafeMarginBytes( DWORD Bytes ) Parameters: DWORD Bytes - safe margins in multiframes, recommended value is at least 36 bytes Returns: nothing

It 's recommended to use default values, i.e. do not call this function at all

170

4.141.6

Set Safe Margins for Writing in Bytes

Sets safe margins for reading to avoid the driver overrun condition void SetWriteSafeMarginBytes( DWORD Bytes ) Parameters: DWORD Bytes Returns: - safe margins in multiframes, recommended value is at least 36

nothing

It is recommended to use default values, i.e. do not call this function at all

4.141.7

Get Used Read Bits per each Four Frames

DWORD GetReadBitsPerQuadFrame() Parameters: none Returns: Used bits for reading per each four frames according to the bit mask

4.141.8

Get Used Write Bits per each Four Frames

DWORD GetWriteBitsPerQuadFrame() Parameters: none Returns: Used bits for writing per each four frames according to the bit mask

171

4.141.9

Get Missed Bytes when Reading Underrun Occurrs

DWORD GetReadMissedBytes() Parameters: none Returns: Bytes missed

4.141.10

Get Missed Bytes when Writing Overrun Occurrs

DWORD GetWriteMissedBytes() Parameters: none Returns: Bytes missed

4.141.11
void Reset()

Reset Stream

Parameters: none Returns: nothing

4.141.12

Read Stream

DWORD Read(PBYTE pOutBuffer, DWORD Length, bool bWait = true ) Read only bits specified by the mask, concatenating them into output byte buffer Parameters: PBYTE pOutBuffer - buffer pointer to read into DWORD Length bool bWait Returns: - bytes to read - true to wait until all the requested bytes read (default) otherwise return immediately placing only available bytes into user buffer DWORD - bytes actually read

Function always places integral number of bytes in the buffer supplied by caller

172

4.141.13

Write Stream

Write only bits specified by the mask DWORD Write(PBYTE pInBuffer, DWORD Length, bool bWait = true, bool bContinuous = true ) Parameters: PBYTE pInBuffer DWORD Length bool bWait bool bContinuous Returns: - pointer to input bytes to write - bytes to write - true wait until all the bytes are written (default), false - return immediately placing as many bytes as possible - true write a continuous stream (default), false write bursty bytes (rarely used)

DWORD number of bytes that were actually written

4.141.14

Reset Input Stream

void ReopenRead() Resets stream for reading. Parameters: none Returns: nothing

4.141.15

Reset Output Stream

void ReopenRead() Resets stream for writing. Parameters: none Returns: nothing

173

4.141.16

Reset Both Input and/or Output Streams

void Reopen(bool bRead=true, bool bWrite=true) Resets stream for reading and/or writing. Parameters: bool bRead bool bWrite Returns: - true reopens for reading ( resets input stream) - true reopens for writing ( resets output stream) nothing

4.141.17

Open for Synchronous Reading

void SyncOpenRead() Is used when multiple cards must be synchronized. This function is then called for each card's FdlStream object. Parameters: none Returns: nothing

174

4.142 MemFile Class. Memory Mapped Input/Output

This class handles memory mapped input/output allowing reading and writing files using memory pointers instead of read/write functions. This class handles input/output much faster than traditional input/output functions. VarRecBuf

4.142.1
MemFile()

Constructors
- does nothing, need to call Init function to enable the object

MemFile(LPCTSTR pszFileName, DWORD& Size, PBYTE& pMem, bool bWriteAccess = true ) Opens a file for reading or creates a file for writing, initializes the memory pointer so caller can read or modify the file using this pointer. Parameters: LPCTSTR pszFileName DWORD& Size PBYTE& pMem bool bWriteAccess - file name to read or write to - mapped file size ( input parameter for writing, returned file size when opened for reading) - returned pointer to memory if file mapped successfully - true (default) create/replace file for writing, false - open existing file for reading

When opening a file for writing set size large enough to accommodate all the bytes. The unused bytes can be later trimmed before closing the file using SetEndOfFile method.

175

4.142.2

Reinitialize ( ReOpen) the Object

bool Init(LPCTSTR pszFileName, DWORD& Size, PBYTE& pMem, bool bWriteAccess = true ) Opens a file for reading or creates a file for writing, initializes the memory pointer so caller can read or modify the file using this pointer. Parameters: LPCTSTR pszFileName DWORD& Size PBYTE& pMem bool bWriteAccess Returns: - file name to read or write to - mapped file size ( input parameter for writing, returned file size when opened for reading) - returned pointer to memory if file mapped successfully - true (default) create/replace file for writing, false - open existing file for reading true - success, otherwise failed

When opening a file for writing set size large enough to accommodate all the bytes. The unused bytes can be later trimmed before closing the file using SetEndOfFile method.

4.142.3
void Close()

Close File

Closes file. If file is opened for writing and not all bytes are used call SetEndOfFile function to trim unused bytes at the end of file. Parameters: none Returns: nothing

176

4.142.4

Return Unused Bytes

void SetEndOfFile( PBYTE pMemEnd ) This method should be called for files opened for writing when there are unused bytes at the end of the file. The file size is truncated to include only useful bytes. Parameters: PBYTE pMemEnd - points to a byte immediately following the last byte to be written to file Returns: nothing

4.142.5

Return Unused Bytes

void SetEndOfFile( DWORD FileSize ) This method should be called for files opened for writing when there are unused bytes at the end of the file. The file size is truncated to include only useful bytes. Parameters: DWORD FileSize - size to truncate file to. This will be the size of the file after it's closed. Returns: nothing

4.142.6
bool IsOpen()

Check if File is Open

Parameters: none Returns: true if file is open, false otherwise

4.143 VarRecBuf Class. Variable Record Buffer

This class is designed to work in conjunction with MemFile class to work with huge number of variable length records in memory and efficiently iterate them in forward and backward direction causing minimal disk access and quick response. MemFile

177

4.143.1
VarRecBuf( )

Constructors

Does nothing, requires Init() function to enable the object VarRecBuf( PBYTE pBuffer, DWORD BufSize ) Parameters: PBYTE pBuffer DWORD BufSize - buffer pointer to use - buffer size

4.143.2

Initialization

bool Init( PBYTE pBuffer, DWORD BufSize ) This function is required if the VarRecBuf() constructor is invoked to initialize the object Parameters: PBYTE pBuffer DWORD BufSize Returns: - buffer pointer to use - buffer size - true successful completion, false otherwise

4.143.3
void Close()

Close

Disables the object Parameters: none Returns: nothing

178

4.143.4

Append a Record

DWORD AddRecord( PBYTE pRec, DWORD RecLen ) Adds a byte string (record) at the end of the list Parameters: PBYTE pRec DWORD RecLen Returns: - pointer to the byte string to add - length of the byte string to add

DWORD - total number of records including the newly added record

4.143.5

Append a Record Consisting of two Parts: Header and Data

DWORD AddTwoPartRecord( PBYTE pHead, DWORD HeadLen, PBYTE pTail, DWORD TailLen ) Two parts are concatenated and appended to the end of the list Parameters: PBYTE pHead DWORD RecLen PBYTE pTail DWORD TailLen Returns: - pointer to the byte string to place at the beginning of the record - length of the byte string to place at the beginning of the record - pointer to the byte string to place at the end of the record - length of the byte string to place at the end of the record

DWORD - total number of records including the newly added record

179

4.143.6

Direct Record Access by Record Number

bool GetRecord( DWORD RecNumber, PBYTE& pRecord, DWORD& RecLength) Gets pointer and length to the record data by record number ( array type access ). Parameters: DWORD RecNumber PBYTE& pRecord DWORD& RecLength Returns: - zero relative record number to get - returns pointer to the record - returns length of the record

bool - true success, false record number exceeds number of records

Sets current record pointer that can be used for next/previous record access

4.143.7

Sequential Access. Get Next Record

bool GetNextRecord( PBYTE& pRecord, DWORD& RecLength) Retrieves next record, i.e. record that follows lately retrieved Parameters: PBYTE& pRecord DWORD& RecLength Returns: - returns pointer to the record - returns length of the record

bool - true success, false record number exceeds number of records

Sets current record pointer that can be used for next/previous record access

180

4.143.8

Sequential Access. Get Previous Record

bool GetPrevRecord( PBYTE& pRecord, DWORD& RecLength) Retrieves previous record, i.e. record that preceeds the record lately retrieved Parameters: PBYTE& pRecord DWORD& RecLength Returns: - returns pointer to the record - returns length of the record

bool - true success, false record number exceeds number of records

Sets current record pointer that can be used for next/previous record access

4.143.9

Get Number of Records in the Buffer ( List )

DWORD GetRecordCount() Parameters: none Returns: DWORD number of records in the list

4.143.10

Get Memory Size used by Data in the List

DWORD GetUsableSize() Parameters: none Returns: DWORD number of bytes used.

181

4.143.11
bool Flush()

Flush MemFile Object Associated with VarRecBuf to Disk

Flushes MemFile to disk. Used to control when disk i/o should happen to equalize the disk activity Parameters: none Returns: bool - true if successful

4.143.12
void Clear()

Delete All Records

Deletes all records Parameters: none Returns: - nothing

4.144 Class DynamicListBuf. Dynamic List Buffer in Caller Supplied Buffer.

This class is a very efficient but limited implementation of linked list that allows filling variable length records in a buffer supplied by caller. It also provides methods to iterate the buffer. Buffer will dynamically grow if more bytes are needed for newly added record. VarRecBuf

4.144.1

Constructors

DynamicListBuf( DWORD InitialBufSize = 4096 ) Allocates buffer of the initial size Parameters: DWORD InitialBufSize - initial buffer size DynamicListBuf( const DynamicListBuf& BaseObj ) Copy constructor
DynamicListBuf b1; DynamicListBuf b2(b1);

182

4.144.2

Assignment Operator

DynamicListBuf& operator=( const DynamicListBuf& BaseObj )

DynamicListBuf b1; DynamicListBuf b2; b2 = b1;

4.144.3
Parameters:

Appending a Record

void push( const BYTE* pItem, DWORD ItemLength)

const BYTE* pItem DWORD ItemLength Returns:

- pointer to record data to add - record length - nothing

4.144.4

Getting the First Record

bool first(const BYTE*& pItem, DWORD& Length, DWORD& Offset) const Retrieves the first record pointer and length Parameters: const BYTE*& pItem DWORD& Length DWORD& Offset Returns: - returned pointer to the record data - returned length of the record

- offset to be used to call next method to retrieve the next record - true record retrieved, false - empty buffer

183

4.144.5

Getting the Next Record

bool next(const BYTE*& pItem, DWORD& Length, DWORD& Offset) const Retrieves the next record pointer and length Parameters: const BYTE*& pItem DWORD& Length DWORD& Offset Returns: - returned pointer to the record data - returned length of the record

- offset to be used to call next method to retrieve the next record - true record retrieved, false - end of the list has been reached

4.144.6
void erase()

Erase the List

Deletes all the records from the list Parameters: none Returns: - nothing

4.144.7

Get Total Size of All Records in the List

DWORD size() const Parameters: none Returns: DWORD total size of all records' data

4.144.8

Check if the List is Empty

bool isEmpty() const Parameters: none Returns: bool true if list is empty, false if it contains records

184

4.144.9

Get Number of Records in the List

DWORD count() const Parameters: none Returns: DWORD number of records in the list

4.145 Calculate CRC for HDLC

void CalculateCrc( PBYTE pMsg, int Len, PBYTE pCRC) Calculates 16 bit CRC for HDLC using x**16 + x**12 + x**5 + 1 polynomial Parameters: PBYTE pMsg int Len PBYTE pCRC Returns: - pointer to the message(frame) data to calculate CRC for - message length - pointer to two bytes where calculated CRC should be placed nothing

4.146 Invert Byte(s)

This function inverts bits in byte(s) so the most significant bit becomes the least significant bit. For example, 0xC1 becomes 0x83.

4.146.1

Invert Bits In-place

void InvertBits( PBYTE pMsg, int Length ) Each byte of the input buffer is inverted MSB->LSB Parameters: PBYTE pMsg int Length Returns: - pointer to the byte string to invert - byte string length nothing

185

4.146.2

Invert a Byte

BYTE InvertBits( BYTE InpByte) Invert a byte MSB->LSB Parameters: BYTE InpMsg Returns: - byte to invert

BYTE inverted byte

4.146.3

Copy Byte String with Inversion

void InvertBits( const BYTE* pInpBuf, int Length, PBYTE pOutBuf ) Copies input string to output inverting each byte MSB->LSB Parameters: PBYTE pInpBuf int Length PBYTE pOutBuf Returns: - pointer to the byte string to invert - byte string length - pointer to output buffer of length Length where to place inverted string

nothing

186

4.147 Asynchronous HDLC Frame Processing

The HdlcAsyncIo class provides an interface to synchronous HDLC frame processing. It automatically creates threads to assure uninterrupted HDLC frame reception and transmission. Applications using this class are released from the concern about the zero bit insertion and deletion, inserting flags between frames etc. The class provides blocking ( waits till a frame is received ) and non-blocking interface for frame reception and non-blocking frame transmission. The precise timing guaranteed by the GL hardware can be obtained for each received frame. The class interface also provides an access to various statistics, like the number of malformed frames received (errors in zero bit deletion), CRC (FCS) errors, number of discarded frames due to a slow application frame reception or to a fast rate of frame submission for transmission etc. The interface between the calling application thread and Rx thread or Tx thread is implemented via a receive frame queue or transmit frame queue accordingly. The queue size can be controlled by an application. If the application submits frames for transmission at a higher rate than the T1/E1 channel(s) throughput (write method) the Tx queue grows until it reaches the specified limit. The frames submitted by an application for transmission above the Tx queue size limit are discarded and error is reported to the application. It's up to the application to slow down and resubmit the frames. Whe an application is too slow reading the frames from the Rx queue the queue size grows till it reaches the limit. Newly received frames will be discarded till application starts retreaving (read method) the frames.

4.147.1

Constructor

HdlcAsyncIo() Parameters: None Parameters are passed when the open method is invoked.

187

4.147.2
int open(

Starting Transmission or Reception

GlComInterface* pIfc, HdlcAsyncIoAccess AccessFlag, BYTE DevNo, DWORD TsMask, BYTE ScMask = 0xFF, DWORD MaxQueuedBytes = 0x00100000 )

Opens the "frame queue" for Rx or Tx, speicifies device, timeslot mask and size of the queue. Parameters: GlComInterface* pIfc - pointer to the GlComInterface object

HdlcAsyncIoAccess AccessFlag - HdlcAsyncRead for Rx or HdlcAsyncWrite for Tx BYTE DevNo DWORD TsMask BYTE ScMask one relative device number ( <= GetNoOfDevicesInstalled() ) - timeslot mask. 0x80000000, for example, specifies timeslot 0, 0xC0000000 specifies 128kbps stream on timeslots 0-1 must be 0xFF

DWORD MaxQueuedBytes - Rx or Tx queue size. The default is 1MB Returns: 0 - opened successfully 100x - invalid parameter x, 1002 if neither read nor write is specified 1003 usually when the timeslots are already used for transmission

188

Depending on the AccessFlag the Rx or Tx thread and queues are created and the application need to issue read or write to process frames. Separate HdlcAsyncIo instances must be used for receiving and transmitting. Examples:
try { GlComInterface Ifc; // Device driver interface object printf("0\n"); Ifc.Initialize( true, GL_CARD_TYPE_DPCI_DMA ); // true to set default hardware settings unsigned char Frame[4] = { 5, 6, 7, 8 }; printf("1\n"); HdlcAsyncIo hr; HdlcAsyncIo hw; if ( hr.open( &Ifc, HdlcAsyncRead, 1, 0x40000000 ) ) // read ts 1 return 11; if ( hw.open( &Ifc, HdlcAsyncWrite, 1, 0x20000000 ) ) // write ts 2 return 12; }

4.147.3

Transmitting Frames

bool write( const BYTE* pData, DWORD length, bool fAddCrc = false ) Parameters: const BYTE* pData - pointer to frame octets to transmit DWORD length - number of octets to transmit

bool fAddCrc = false add crc to the frame octets, default is false, i.e. CRC (FCS) is already included in the length, otherwise the function calculates CRC and appends it to the frame. When fAddCrc = true, the total frame length becomes length + 2 Returns: true if frame is queued successfully false if the HdlcAsyncIo object was opened for reading, parameters of the functions are incorrect or the queue limits are exceeded ( application writes too fast )

The write function does not actually transmit frames. It just queues frames for transmission. The Tx thread constantly removes frames from the Tx queue and transmits them placing flags between frames. If there are no frames queued for transmission the Tx thread transmitts flags. 189

If application invokes the write method faster than the frames are transmitted the queue size grows until it reaches the limit. Further frames will be discarded until some frames from the queue are transmitted and removed by Tx thread and the "skip" counter is incremented. When queue size grows, so increases the time between the frame is submitted for transmission by the write method and the time when the frame is actually transmitted.

4.147.4
Parameters:

Receiving Frames

bool read( BYTE*& pData, DWORD& length, DWORD WaitMs = INFINITE )

BYTE*& pData DWORD& length DWORD WaitMs

- pointer to frame octets, application must release these memory using delete [] pData when frame is no longer needed - length of the frame including CRC (FCS) bytes milliseconds to wait if no frames are queued by the Rx thread. Default is INFINITE, i.e. blocking read. If wait times expires and still no frames received function returs false and pData is set to 0

Returns:

true - frame received, false - no frame received and/or timeout has expired

If application calls the read function slower than frames are received by the Rx thread, the frames are queued until the queue limit has been reached. When the queue limit has been reached, new frames are discarded by the Rx thread and "skip" counter is incremented.

190

4.147.5

Receiving Frames with Extended Frame Information

bool read( BYTE*& pData, DWORD& length, HdlcFrameInfo& FrameInfo, DWORD WaitMs = INFINITE ) Parameters: BYTE*& pData DWORD& length - (out) pointer to frame octets, application must release these memory using delete [] pData when frame is no longer needed - (out) length of the frame including CRC (FCS) bytes

HdlcFrameInfo& FrameInfo - (out) extended frame information: timing, time slot, error etc. DWORD WaitMs milliseconds to wait if no frames are queued by the Rx thread. Default is INFINITE, i.e. blocking read. If wait times expires and still no frames received function returs false and pData is set to 0

Returns:

true - frame received, false - no frame received and/or timeout has expired

If application calls the read function slower than frames are received by the Rx thread, the frames are queued until the queue limit has been reached. When the queue limit has been reached, new frames are discarded by the Rx thread and "skip" counter is incremented.

4.147.5.1 HdlcFrameInfo
This structure is returned with each frame by the read function and contains the following information:
struct HdlcFrameInfo { BYTE TimeStamp[8]; unsigned char DevNo; unsigned char fSubchannelsUsed : 1; unsigned char TimeslotForSubchannels : 5; unsigned char StartTs : 5; // start ts or subchannel unsigned char EndTs : 5; // end ts or subchannel BYTE ErrorFlag; };

191

TimeStamp is 64 bit integer containing number of 100s of nanoseconds since the receive (Rx) thread has started. The difference in timestamps between any two frames is very accurate. To calculate number of microseconds between two frames, for example, HdlcFrameInfo Tstamp1; HdlcFrameInfo Tstamp2; // __uint64 DiffTimeMks = ( *( (__uint64*)Tstamp2.TimeStamp ) - *( (__uint64*)Tstamp1.TimeStamp ) ) / 10; DevNo - device number ( 1 relative ) StartTs - beginning timeslot number ( 0 relative ) EndTs - ending timeslot number ( 0 relative ) For 64 kbps ( one channel ) StartTs == EndTs ErrorFlag - is zero if zero bit removal was successful and CRC is correct. Otherwise, the flag is set to ErrorFlagMalformed or ErrorFlagCrc accordingly.

4.147.6

Example of Loop Back

The following example loops back frames received on one chanel and transmitting the frames on another channel.
try { GlComInterface Ifc; // Device driver interface object printf("0\n"); Ifc.Initialize( true, GL_CARD_TYPE_DPCI_DMA ); // true to set default hardware settings HdlcAsyncIo hr; HdlcAsyncIo hw; if ( hr.open( &Ifc, HdlcAsyncRead, 1, 0x40000000 ) ) return 11; if ( hw.open( &Ifc, HdlcAsyncWrite, 1, 0x20000000 ) ) return 12; Sleep(0); PBYTE pData; DWORD DataLen; //DWORD TotalLen = 0; for ( ;; ) { if ( hr.read( pData, DataLen, 1000 ) ) { hw.write( pData, DataLen, false ); delete [] pData; } } return 0; }

192

/********************************************************************/ /* Process exceptions. All clients MUST use this error processing. */ /********************************************************************/ catch (GlComExceptions exception) { printf( "Last error: %s\n", GlcGetLastErrorMsg() ); printf( "Driver interface error. Exception description: %s\n", GetExceptionDescription( exception ) ); return 11; } catch ( DWORD lastError ) { printf( "Last error: %s\n", GlcGetLastErrorMsg() ); printf( "Driver error. GetLastError() = %lu\n", lastError ); return 12; } catch (...) { printf( "Last error: %s\n", GlcGetLastErrorMsg() ); printf("Unexpected internal error\n"); return 13; }

4.147.7
void close()

Stopping Receiving or Transmitting

Terminates the Rx or Tx tread. No read or write function can be invoked when the object is "closed". Parameters: none Returns: nothing

4.147.8

Getting the Rx or Tx Queue Size

Retrieves total number of frames queued by the Rx thread for receive object but not retrieved by application by recv function, or the total number of bytes queued for transmission but not transmitted yet. DWORD GetQueuedBytes() Parameters: none Returns: Total number of bytes in all the frames currently placed in the Rx or Tx queue. If the application submitting frames for transmission too fast using write function or the application is too slow to retrieve the frames by using read function the returned value increases till it reaches the limit specified in the open function. After this limit point the 193

new received or submitted for transmission frames will be discarded and GetSkippedFrame and GetSkippedBytes functions will return number of discarded frames and bytes accordingly.

4.147.9

Getting Total Number of CRC Errors in Received Frames

DWORD GetCrcCount() Parameters: none Returns: Total number of CRC errors in the received frames since open

4.147.10

Getting Total Number of Malformed Received Frames

DWORD GetMalformedCount() Parameters: none Returns: Total number of malformed frames received since open

4.147.11

Get Total Number of UnderRuns or OverRuns

WORD GetOverUnderRuns() Parameters: none Returns: Total number of underruns or overruns since open

This count is incremented if the system is very busy and the Rx or Tx threads do not get enough time by Windows thread scheduler.

4.147.12

Get Number of Discarded Frame Octets

When application is calling write too fast or read too slow the Tx or Rx queue reaches the limit and some frames are discarded. The number of discarded bytes is counted and returned by this function. DWORD GetSkippedBytes() Parameters: none Returns: Total number of discarded bytes in discarded frames

194

4.147.13

Get Number of Discarded Frames

When application is calling write too fast or read too slow the Tx or Rx queue reaches the limit and some frames are discarded. The number of discarded frames is counted and returned by this function. DWORD GetSkippedFrames() Parameters: none Returns: Total number of discarded frames

4.147.14

Setting Minimum Number of Flags Between Frames

By default the minimum number of flags between transmitted frames is 2, hower the minimum number of flags between frames can be set to any positive value. void SetTxMinFlags( DWORD Flags ) Parameters: DWORD Flags - minimum number of flags to insert between transmitted frames Returns: Nothing

4.147.15

Getting the Minimum Number of Flags Between Frames

Retrieves the number of flags between transmitted frames DWORD GetTxMinFlags() Parameters: none Returns: - minimum number of flags to insert between transmitted frames

195

4.148 Enabling the Sound Driver

C++ C
EnableSoundDriver() GlEnableSoundDriver()

Parameters: none Returns: nothing.

DisableSoundDriver(),IsSoundDriverEnable()

4.149 Disabling the Sound Driver

C++ C
DisableSoundDriver() GlDisableSoundDriver()

Parameters: none Returns: nothing.

EnableSoundDriver(),IsSoundDriverEnable()

4.150 Querying if the Sound Driver is Enabled

C++ C
IsSoundDriverEnable() GlIsSoundDriverEnabled()

Parameters: none Returns: nothing. EnableSoundDriver(),DisableSoundDriver

196

4.151 Get Application Instance Count Transmitting on the Card

C++ C
int GetTxBufferEnableCount ( BYTE DeviceNo ) int GlGetTxBufferEnableCount ( BYTE DeviceNo )

Parameters: BYTE DeviceNo

- one relative device number

Returns: DWORD number of application instances transmitting on the card EnableTxRxBuffer(),DisableTxRxBuffer()

4.152 Get Application Instance Count Receiving on the Card

C++ C
int GetRxBufferEnableCount ( BYTE DeviceNo ) int GlGetRxBufferEnableCount ( BYTE DeviceNo )

Parameters: BYTE DeviceNo

- one relative device number

Returns: int number of application instances receiving on the card EnableTxRxBuffer(),DisableTxRxBuffer()

4.153 Get Line Level Voltage

C++ C
double GetLineLevelVoltage(BYTE DeviceNo) double GlGetLineLevelVoltage(BYTE DeviceNo)

Parameters: BYTE DeviceNo

- one relative device number

Returns: double line level voltage

This function is for HD cards only and will cause an exception for other card types

197

4.154 Get HD Card FPGA Parameters

C++ C
Void GetFpga( BYTE DeviceNo, DWORD IoCtlCode, DWORD& Parm1, DWORD& Parm2 ) Void GlGetFpga( BYTE DeviceNo, DWORD IoCtlCode, DWORD* pParm1, DWORD* pParm2 ) - one relative device number - information type to get - returned information token 1 - returned information token 2 request information in output parameters Parm1 and Parm2

Parameters: BYTE DeviceNo DWORD IoCtlCode DWORD& Parm1 DWORD& Parm2 Returns:

This function is for HD cards only and will cause an exception for other card types

The following table contains the details for different IoCtlCode functions: IoCtlCode Parm1 Parm2 VXD_GetTxBERInversion 1 inversion on, 0 off Not used
VXD_GetRxBERInversion VXD_GetTxBERPattern VXD_GetRxBERPattern 0 - QRSS pattern 1 - 2^6-1 pattern 2 - 2^9 -1 pattern 3 - 2^11 -1 pattern 4 - 2^15-1 pattern 5 - 2^20-1 pattern 6 - 2^23-1 pattern 7 Static patterns

Not used

VXD_GetTxStaticPattern VXD_GetRxStaticPattern VXD_GetTxBERBitMask VXD_GetRxBERBitMask VXD_GetFDLBuffers VXD_GetRxBERUnframed VXD_GetTxBERUnframed VXD_GetDataErrorInsertionMode VXD_GetVFMemoryInsertionMode VXD_GetRxBERTotalBits

Static bits Bit mask for BER 0x000000FF 64k (all bits) Pointer to FDL TX buffer 1 unframed enabled 0 unframed disabled 1 set error insertion 0 no error isertion 1 set data insertion 0 no data isertion Bits compared

Static bit count Not used Pointer to FDL RX buffer Not used Not used Not used Not used

Table 19. GetFpga codes and parameters SetFpga

198

4.155 Set HD Card FPGA Parameters

C++ C
Void SetFpga( BYTE DeviceNo, DWORD IoCtlCode, DWORD Parm1, DWORD Parm2 ) Void GlSetFpga( BYTE DeviceNo, DWORD IoCtlCode, DWORD Parm1, DWORD Parm2 ) - one relative device number - information type to get - information token 1 to set - information token 2 to set, must be zero when not used nothing

Parameters: BYTE DeviceNo DWORD IoCtlCode DWORD Parm1 DWORD Parm2 Returns:

This function is for HD cards only and will cause an exception for other card types

The following table contains the details for different IoCtlCode functions: IoCtlCode Parm1 Parm2 VXD_SetTxBERInversion 1 inversion on, 0 off 0
VXD_SetRxBERInversion VXD_SetTxBERPattern VXD_SetRxBERPattern

VXD_SetTxStaticPattern VXD_SetRxStaticPattern VXD_SetTxBERBitMask VXD_SetRxBERBitMask VXD_SetFDLBuffers VXD_SetRxBERUnframed VXD_SetTxBERUnframed VXD_SetDataErrorInsertionMode VXD_SetVFMemoryInsertionMode VXD_SetRxBERTotalBits

0 - QRSS pattern 1 - 2^6-1 pattern 2 - 2^9 -1 pattern 3 - 2^11 -1 pattern 4 - 2^15-1 pattern 5 - 2^20-1 pattern 6 - 2^23-1 pattern 7 - Static patterns Static bits Bit mask for BER 0x000000FF 64k (all bits) Pointer to FDL TX buffer 1 unframed enabled 0 unframed disabled 1 set error insertion 0 no error isertion 1 set data insertion 0 no data isertion Bits compared

Static bit count 0 Pointer to FDL RX buffer 0 0 0 0

Table 20. SetFpga codes and parameters GetFpga

199

4.156 Check if Separate FDL Buffers are used

C++ C
bool isSeparateFdlBuf() BOOL GlIsSeparateFdlBuf()

Parameters: none Returns: true (TRUE) if separate buffers are used (HD card), false other types

GetSeparateFdlBuffers

4.157 Get Separate FDL Buffers Addresses

C++ C
void GetSeparateFdlBuffers( BYTE DeviceNo, PBYTE& pFdlTxBuffers, PBYTE& pFdlRxBuffers ) void GlGetSeparateFdlBuffers( BYTE DeviceNo, PBYTE* ppFdlTxBuffers, PBYTE* ppFdlRxBuffers )

Parameters: BYTE DeviceNo - one relative device number - (out) returns pointer to two adjacent FDL TX buffers - (out) returns pointer to two adjacent FDL TX buffers

PBYTE& pFdlTxBuffers PBYTE& pFdlRxBuffers Returns:

adjacent buffer pointers in pFdlTxBuffers and pFdlRxBuffers

This function is for HD cards only and will cause an exception for other card types

isSeparateFdlBuf

200

4.158 Get Signaling Information for HD Cards

C++ C
unsigned long GetSignalingInfo( BYTE DeviceNo, DWORD IoCtlCode, unsigned long Timeslot) unsigned long GlGetSignalingInfo( BYTE DeviceNo, DWORD IoCtlCode, unsigned long Timeslot)

Parameters: BYTE DeviceNo DWORD IoCtlCode Unsigned long Timeslot Returns: request information depending on the IoCtlCode
This function is for HD cards only and will cause an exception for other card types

- one relative device number - information type to get - zero relative timeslot number

The following table contains the details for different IoCtlCode functions: IoCtlCode Returns VXD_GetTxSignalingBits Tx signaling bits ABCD (D in least significant bit) VXD_GetRxSignalingBits Rx signaling bits ABCD (D in least significant bit) VXD_GetTxEnableSignalingBits 1 enabled, 0 disabled Table 21. GetSignalingInfo codes and parameters

4.159 Get Firmware Version

C++ C
int GetFirmwareVersion() int GlGetFirmwareVersion() - none - firmware version 0..255

Parameters: Returns:

This function is for HD cards only and will cause an exception for other card types

201

4.160 Set Tx Signaling Bits for a Timeslot for HD Cards

C++ C
void SetTxSignalingBits( BYTE DeviceNo, unsigned long Timeslot, unsigned long SigBits ) void GlSetTxSignalingBits( BYTE DeviceNo, unsigned long Timeslot, unsigned long SigBits )

Parameters: BYTE DeviceNo unsigned long Timeslot unsigned long SigBits Returns:
This function is for HD cards only and will cause an exception for other card types

- one relative device number - zero relative timeslot number - ABCD bits (D in least significant bit) - nothing

4.161 Get Tx Signaling Bits for a Timeslot for HD Cards

C++ C
unsigned long GetTxSignalingBits( BYTE DeviceNo, unsigned long Timeslot) unsigned long GlGetTxSignalingBits( BYTE DeviceNo, unsigned long Timeslot)

Parameters: BYTE DeviceNo unsigned long Timeslot Returns:

This function is for HD cards only and will cause an exception for other card types

- one relative device number - zero relative timeslot number - Tx ABCD signaling bits (D in least significant bit)

202

4.162 Get Rx Signaling Bits for a Timeslot for HD Cards

C++ C
unsigned long GetRxSignalingBits( BYTE DeviceNo, unsigned long Timeslot) unsigned long GlGetRxSignalingBits( BYTE DeviceNo, unsigned long Timeslot)

Parameters: BYTE DeviceNo unsigned long Timeslot Returns:

This function is for HD cards only and will cause an exception for other card types

- one relative device number - zero relative timeslot number - Rx ABCD signaling bits (D in least significant bit)

4.163 Check if Tx Signaling Bits for a Timeslot are enabled for HD Cards
C++ C
bool IsTxSignalingEnabled( BYTE DeviceNo, unsigned long Timeslot) bool GlIsTxSignalingEnabled ( BYTE DeviceNo, unsigned long Timeslot)

Parameters: BYTE DeviceNo unsigned long Timeslot Returns:

This function is for HD cards only and will cause an exception for other card types

- one relative device number - zero relative timeslot number - true if enabled, false otherwise

203

4.164 CFileCapturingOperations, Periodic File Saving Class

This object captures and creates contiguous sequential files from a continuous T1/E1 stream. This class allows the user to control the capture of a continuous stream of data in a number of ways. Its captures can be size based or time based. This has been integrated into an Analyzer module, Automated Continuous Capture. The main class, which encapsulates the data acquisition process is named CFileCapturingOperations.

4.164.1

Creating the Periodic File Saving Class

CFileCapturingOperations() N/A

C++ C

Parameters: - none Returns: - nothing

4.164.2

Initializing the Periodic File Saving Class Data Members

void AllocatePeriodicFileSavingObject( PeriodicSaveFileNameType FileNameType, const char *SeqFileNamePrefix, unsigned long SeqFileNameDigits, const char *SeqFileNameSuffix, const char *DateTimeFileNameSuffix, const char *DateTimeFileNameMask, PeriodicSaveLimitType LimitType, unsigned long SizeCountLimit, unsigned __int64 TimeLimit100ns, PeriodicSaveStopRecycleType StopRecycleType, unsigned long StopRecycleFileCount, unsigned long FileSeqNum, unsigned long NextSeqDigits, unsigned long CurrCountSizeValue, const char *FileDirectory, bool fEnableFiltering); N/A

C++

204

Parameters: PeriodicSaveFileNameType FileNameType type of continuous capture, sequential or date/time const char *SeqFileNamePrefix beginning of filename unsigned long SeqFileNameDigits - determines maximum # of files to capture, a value of 3 would mean that up to 1000 contiguous files would be captured, e.g., temp000, temp001, , temp999. const char *SeqFileNameSuffix extension of captured file const char *DateTimeFileNameSuffix extension of captured file const char *DateTimeFileNameMask a formatting string similar to the printf formatting string. Formatting codes, preceded by a percent (%) sign, are replaced by the corresponding time component. %Y year %M month %D day %H hour %I minute PeriodicSaveLimitType LimitType specify type of capture, size or time-based unsigned long SizeCountLimit maximum # of Bytes that each captured file can contain unsigned __int64 TimeLimit100ns duration of capture for each file, based on nanoseconds PeriodicSaveStopRecycleType StopRecycleType options include a. Unrestricted captures after the file with the highest sequence # is captured, the sequence # resets, and starts at zero b. Keep StopRecycleFilecount latest files c. Stop after StopRecycleFileCount files unsigned long StopRecycleFileCount - # of files that StopRecycleType limitations depend on unsigned long FileSeqNum use value of 0 unsigned long NextSeqDigits use value of 0 unsigned long CurrCountSizeValue use value of 0 const char *FileDirectory folder where captures are stored bool fEnableFiltering use value of false Returns: - nothing

205

4.164.3

Initializing the CFileCapturingOperations Data Members

Void Initialize(GlComInterface *pIfc, DWORD RdChannelMask, DWORD DevMask, DWORD BufferSize, Bool ByteReversal) N/A

C++

Parameters: GlComInterface *pIfc pointer to GlComInterface object DWORD RdChannelMask timeslot mask to specify which timeslots to capture DWORD DevMask device mask to specify which devices to capture DWORD BufferSize size of buffer that contains capture data bool ByteReversal indicates whether capture data should be reversed for each byte Returns: - nothing Remarks Sets timeslot and device capture parameters along with other initialization. This function must be called first.

4.164.4

Opening Files for Capture

void OpenPeriodicSavingFile() N/A

C++ C

Parameters: - none Returns: - nothing

Remarks This function performs the creation of the filename and opens the files that data will be written to.

206

4.164.5

Allocating Memory for Device Information

void AllocateDeviceData() N/A

C++ C

Parameters: - none Returns: - nothing

Remarks This function will allocate the space required to capture the data.

4.164.6

Deallocating Device Information

void FreeDeviceData() N/A

C++ C

Parameters: - none Returns: - nothing

Remarks This function performs cleanup for CFileCapturingOperations .

207

4.164.7

Closing the Periodic File Saving Class

void ClosePeriodicSavingFile( unsigned long RemainingBytesToWrite, DWORD BioStreamBytesLeft, CAPMESSAGES &capmsg) N/A

C++ C

Parameters: Unsigned long RemainingBytesToWrite - # of bytes left to write for the currently open file DWORD BioStreamBytesLeft # of bytes left in the biostream which have not yet been written to a file CAPMESSAGES &capmsg contains filecapture status info. The data may be displayed for user info. Returns: -nothing Remarks This function shuts down the capture process and closes all files.

4.164.8

Close all Files

Void CloseAllPeriodicFiles() N/A

C++ C

Parameters: - none Returns: Remarks This function shuts down the capture process and closes all files. - nothing

208

4.164.9

Periodic File Saving Control Loop

void ProcessFileSavingFlags(CAPMESSAGES **capmsg) N/A

C++ C

Parameters: CAPMESSAGES **capmsg contains filecapture status information. The data may be displayed for user information. Returns: - nothing Remarks The control loop which continuously runs, reads, and writes data. This is the main mechanism of the CFileCapturingOperations object.

4.164.10

Periodic File Saving Control Loop

Void GetFileName(char *filename) N/A

C++ C

Parameters: char *filename name of the filename being captured without the device string prepended to it Returns: -nothing Remarks Retrieves the filename of the file that captured data is being written to.

209

4.164.11

Periodic File Saving Control Loop

void GetFileDirectory(char *dirname) N/A

C++ C

Parameters: char *dirname name of the folder where captured sequentials are stored Returns: -nothing Remarks Retrieve the folder name where captured sequential files are being stored.

4.164.12

Clear Messages
void ClearMessages() N/A

C++ C

Parameters: - none Returns: Remarks Clear all status messages. - nothing

4.164.13

Initialization of File Saving Object

void InitalizePeriodicFileSavingObject(int initvalue); N/A

C++ C

Parameters: int initvalue initialization value for the periodic filesaving object Returns: -nothing Remarks Initializes the object for periodic file saving.

210

4.164.14

Synchronize Captures
SynchronizeCaptures(); N/A

C++ C

Parameters: - none Returns: Remarks All of the cards designated to capture data are synchronized. This should be performed at the beginning of a capture. - nothing

4.164.15

PeriodicFileSaving I/O Errors

Class FileOpenErrors(int exceptiontype) N/A

C++ C

Parameters: int exceptiontype exceptions can be thrown with one of two values 1 file cannot opened for writing 2 file closing error Returns: Remarks
throw FileOpenErrors(1); // file opening error .. .. catch(CFileCapturingOperations::FileOpenErrors FileError) { switch (FileError.FiletypeError) { case 1: // file opening error break; case 2: // file closing error break; } }

- nothing

211

4.165.16 PeriodicFileSaving Disk Usage Limitations

C++ C

class PeriodicLimitReached() N/A

Parameters: - none Returns: Remarks

throw PeriodicLimitReached; // file opening error .. .. catch(CFileCapturingOperations::PeriodicLimitReached) { }

- nothing

If the user has set file capturing limitations, the application control loop will halt when this limitation is reached.

212

5 Index
1 100 duty cycle (E1) selecting .....................................................109 5 50 duty cycle (E1) selecting .....................................................109 56 kbps reading .......................................................154 subchannels..................................................23 A abnormal termination getting description .........................................7 active global receive buffer getting index of............................................59 active global transmit buffer getting index of............................................58 active receive buffer get sequence number....................................48 active receive global buffer get offset ......................................................45 get pointer to................................................44 active transmit buffer get sequence number....................................48 active transmit global buffer get offset ......................................................46 get pointer to................................................45 AIS setting ..........................................................14 AIS per status set check............................................................87 AIS transition set check............................................................87 all per status getting ..........................................................86 all transitions getting ..........................................................86 analog loopback disabling ......................................................91 enabling .......................................................90 analog loopback in driver is set check if ........................................................87 API files ................................................................2 API library get version................................................... 22 Asyncronous Signaling Bits Transmission accessing multiple BioStreamEx objects .. 151 closing....................................................... 150 getting statistics ........................................ 152 Opening multiple timeslots for xmission .. 149 reading ...................................................... 150 retrieving event handle.............................. 152 writing to multiple timeslots ..................... 151 audio register write to ........................................................ 72 Auto resync disabling.................................................... 106 enabling.................................................... 105 auto resync enabled check if for E1 ............................................ 96 auto resync is enabled check if for T1 ............................................ 94 autoresync check........................................................... 16 disable ......................................................... 16 enable.......................................................... 16 available timeslot ....................................................... 79 B B8SZ (T1) detecting on Rx ......................................... 114 B8SZ or COFA detected check if for T1 ............................................ 94 B8ZS check........................................................... 16 Base I/O address querying ........................................... 9 BER deselect Tx/Rx ............................................ 19 get errors ..................................................... 19 load static pattern .............................19, 84, 85 select Tx/Rx ................................................ 19 BER error counter clear ............................................................ 82 read ............................................................. 82 BioCalculateChannelMask ............................ 141 BioCloseStream ............................................. 131 BioFillTxChannels......................................... 139

213

BioFillTxChannelsWithLenght ......................140 BioGetReadMissedBytesCount ......................135 BioGetWriteMissedBytesCount .....................136 BioOpenStream ..............................................130 BioRead..........................................................136 BioReopen ......................................................139 BioReopenRead..............................................138 BioReopenWrite .............................................138 BioSetReadChannelMask...............................132 BioSetReadSafeMarginBytes .........................134 BioSetReadSafeMarginMultiFrames..............133 BioSetWriteSafeMarginBytes ........................135 BioSetWriteSafeMarginMultiFrames.............133 BioStream Calculating Channel Mask.........................141 creating ..............................................130, 131 fill global transmit buffers with byte strings ..............................................................140 fill global transmit buffers with idle code..139 get missed receive bytes ............................135 get missed transmit bytes...........................136 receive........................................................136 reopen receiving ........................................138 reopen receiving and/or transmitting .........139 reopen transmitting ....................................138 set read safe margins..........................133, 134 set receive channel mask ...........................132 set transmit channel mask ..........................132 set write safe margins ........................133, 135 transmit ......................................................137 BioWrite .........................................................137 BIST setting ..........................................................14 BIST per status set check if ........................................................87 bit inversion ....................................................185 bit removing HDLC ..........................................................24 bit stuffing HDLC ..........................................................24 BitRemove Class ..........................................................162 BitRemove class using ............................................................24 BitStream class using ............................................................23 BitStream Class ..............................................154 blue alarm check............................................................16 disable..........................................................16 enable...........................................................16 blue alarm detected check if for T1 .............................................94 Borland C++ Builder API library ...................................................31

BPV error counter.............................................. 103 BPV counter check saturated............................................ 16 BPV counter saturated check if for T1 ............................................ 94 BPV error insert ........................................................... 82 BPV error counter get ............................................................... 16 resetting to a start value ............................ 104 bridge mode checking...................................................... 69 setting.......................................................... 70 Built-in debugging enable/disable messages.............................. 22 built-in diagnostic check whether enabled................................ 35 built-in self test ................................................ 87 activate........................................................ 14 C C interface object checking if object exists.............................. 41 creating ..................................................28, 40 destroying ................................................... 41 initializing ................................................... 28 CalculateCrc function .................................... 185 Calculating Channel Mask............................. 141 card I/O checking...................................................... 61 card memory checking...................................................... 62 card register initialization .................................................. 8 carrier loss detected check if for T1 ............................................ 94 CAS set 16 CAS multiframe resync check........................................................... 16 check if for E1 ............................................ 96 CAS multiframe resync criteria is fixed check if for E1 ............................................ 96 CAS multiframe sync criteria set fixed or not fixed ................................... 16 CAS multiframe sync criteria fixed (E1) setting........................................................ 108 CAS multiframe sync criteria is fixed check if for E1 ............................................ 96 CAS multiframe sync criteria not fixed (E1) setting........................................................ 108 CAS receive mode (E1) setting........................................................ 108 CAS transmit mode (E1) setting........................................................ 108

214

CASF or BER selection .......................................................11 CASF/BER set BER........................................................74 set to CASF..................................................74 CCS set 16 CCS or CAS check............................................................16 CCS receive mode setting (E1) ................................................108 CCS transmit mode (E1) setting ........................................................108 channel for transparent check if selected...........................................16 channel for Tx idle code check if selected...........................................16 check clock ............................................................78 check card I/O and memory...........................................61 check framing format ESF/D4 ........................................................16 CheckCard ........................................................61 CheckCardIo.....................................................61 CheckCardMemory ..........................................62 CheckCodec......................................................78 CheckDr ...........................................................87 CheckDrJitter....................................................92 CheckFr E1 96 T1 94 CheckFrTimeslotSelectedForTxIdleCode E1 only.........................................................97 CheckGlcEnableDbgMsg .................................35 CheckMode ......................................................69 CheckMultiTsAllAvailable ..............................80 CheckMultiTsAvailable ...................................79 clock check external ..............................................78 check internal...............................................78 check recovered ...........................................78 set to external...............................................74 set to internal ...............................................74 set to recovered............................................74 codec check drop insert enabled ............................78 check speaker on/off ....................................78 disable drop insert........................................77 enable drop insert.........................................76 get gain ........................................................75 get timeslot ..................................................75 initialization .................................................64 initialize .......................................................60 set BER........................................................74 set clock .......................................................74

set gain ........................................................ 73 set time slot ................................................. 73 turn off speaker ........................................... 77 turn off VF transmissioin ............................ 77 turn speaker on............................................ 76 turn VF transmission on.............................. 76 VF transmission on/off ............................... 78 Codec functions ..................................................... 11 Interface Latch ............................................ 11 set BER ....................................................... 11 set CASF..................................................... 11 Codec Interface Latch Check .......................................................... 11 Reset ........................................................... 11 Set ............................................................... 11 COFA check........................................................... 16 COFA (T1) detecting on Rx ......................................... 114 Compiler API library include file ............................... 31 defines for different cards ........................... 31 settings ........................................................ 31 configuration files for bit error rate testing ............................... 32 for hardware settings................................... 32 CRC calculation for HDLC ............................... 185 reading/writing............................................ 25 CRC4 get error counter.......................................... 16 CRC4 error counter E1 103 CRC4 error counter (E1) resetting to a start value ............................ 104 CRC4 Tx/Rx (E1) disabling.................................................... 106 enabling.................................................... 105 CreateCGlComInterface .................................. 40 Cross Port Functions..................................................... 14 GetCrossPort............................................... 14 Getting ........................................................ 85 Modes ......................................................... 14 SetCrossPort ............................................... 14 Setting ......................................................... 84 current pattern file name ..................................................... 67 get file name ............................................... 43 set file name ................................................ 44 D D4 framing (T1) selecting .................................................... 109 D4 is selected

215

check if for T1 .............................................94 D4 yellow alarm B2 (T1) selecting .....................................................109 D4 yellow alarm S bit (T1) selecting .....................................................109 D4 yellow alarm S Bit is set check if for T1 .............................................94 data transmission rate for T1 and E1 full frame (all channels)..........9 getting ..........................................................49 Debugging application ...................................................32 default configuration loading .........................................................63 deselect all channels for transparent ..........................16 all channels for Tx idle code........................16 all Rx channels for code insert.....................16 all timeslots for Tx idle codes......................16 channel for Tx idle code, transparent or code insert .......................................................16 deselect BER receive/transmit ...........................................84 DeselectFr.......................................................110 DeselectFrTimeslot ........................................113 deselecting time slots....................................................110 deselecting all time slots for Tx idle code..........................................110 DestroyCGlComInterface.................................41 detect Rx B8ZS or COFA ......................................16 DetectFrRx .....................................................114 device driver get selected device number ..........................50 Device driver get version....................................................22 Devices maximum number supported by device driver ..................................................................9 DFMO setting ..........................................................14 DFMO transition set check............................................................87 disable diagnostic error message boxes ...................35 interrupts......................................................16 disable all framer interrupts T1 and E1.....................................................98 disable framer alarm interrupts only T1 and E1.....................................................98 disable framer interrupts selectively T1 and E1.....................................................99 DisableCodec....................................................77 DisableDrInterruptEvents.................................85 DisableDriver ...................................................91

DisableFr ....................................................... 106 DisableFrInterrupts.......................................... 98 T1 and E1.................................................... 99 DisableTxRxBuffer ....................................... 124 DisableUnframedInput .................................. 126 disabling framer features .......................................... 106 display critical error in DEBUG builds only and throw GetLastError exception .......................... 37 driver disable interrupt events ............................... 14 enable interrupt events ................................ 14 equalizer control ......................................... 14 initialization ................................................ 60 initialization error description ................... 39 openning ..................................................... 60 query information ....................................... 14 driver attributes getting ......................................................... 86 driver interrupt events disable ......................................................... 85 enable.......................................................... 86 driver open status set check if........................................................ 87 driver register write to ........................................................ 72 driver registers resetting....................................................... 92 driver Rx monitor mode disabling...................................................... 91 enabling....................................................... 90 driver version getting ....................................................... 120 drop insert check enabled.............................................. 78 disable ......................................................... 77 enable.......................................................... 76 Drop Insert Disable ........................................................ 11 Enable ......................................................... 11 DynamicListBuf class using............................................................ 27 DynamicListBuf Class................................... 182 E enable diagnostic error message boxes .................. 35 interrupts ..................................................... 16 enable all framer interrupts T1 and E1.................................................. 100 EnableCodec.................................................... 76 EnableDrInterruptEvents ................................. 86 EnableDriver.................................................... 90 EnableFr ....................................................... 105 EnableFrInterrupts

216

T1 and E1...........................................100, 101 EnableMultiTs ..................................................79 EnableMultiTsAll.............................................80 EnableTxRxBuffer .........................................123 EnableUnframedInput ....................................127 enabling framer features..........................................105 enabling framer interrupts selectively T1 and E1...................................................101 equalizer control..........................................................14 gain setting...................................................14 equalizer control getting ..........................................................86 equalizer gain setting ..........................................................88 equalizer gain 12dB setting ..........................................................89 equalizer gain 26dB setting ..........................................................89 equalizer gain 36dB setting ..........................................................89 Error initializing....................................................32 error counter check saturated ............................................16 get BPV (T1 and E1) .................................103 get CRC4 error counter (E1)......................103 get errored superframe counter (T1) ..........103 get frame error counter (E1) ......................103 get out of frame counter (T1).....................103 error counter detected check if for T1 .............................................94 error counter is saturated check if for E1 .............................................96 error message formatting ........................................36, 37, 38 Error message displaying.....................................................22 formatting ....................................................22 errored superframe get error counter...........................................16 ES overrun transition set check............................................................87 ES OVR transition set check............................................................87 ES underrun transition set check............................................................87 ESF framing (T1) selecting .....................................................109 ESF yellow alarm check FDL ...................................................16 ESF yellow alarm FDL check if for T1 .............................................94 ESF yellow alarm FDL (T1) selecting .....................................................109

ESF yellow alarm S bit (T1) selecting .................................................... 109 exception handling ...........................................4, 6, 7, 28 suppressing messaging boxes in debug mode ............................................................. 6, 7 suppressing messaging boxes in debug mode with C interface...................................... 28 Exception get textual description................................. 22 exceptions caused by driver and system errors ............. 33 caused by invalid parameters ...................8, 33 in XE "exceptions:caused by invalid parameters" XE "exceptions:caused by driver and system errors" XE "invalid:parameters" API Library .......... 33 library, driver and system ............................. 4 ext signaling bits selected check if for E1 ............................................ 96 ext signalling bits (E1) disabling.................................................... 106 enabling.................................................... 105 external CRC check if enabled .......................................... 16 disable ......................................................... 16 external CRC (T1) disabling.................................................... 106 enabling.................................................... 105 external CRC is enabled check if for T1 ............................................ 94 external FT FPS check if enabled .......................................... 16 disable ......................................................... 16 external FT FPS (T1) disabling.................................................... 106 enabling.................................................... 105 external FT FPS is enabled check if for T1 ............................................ 94 external S bit check if enabled .......................................... 16 disable ......................................................... 16 enable.......................................................... 16 external S bit (T1) disabling.................................................... 106 enabling.................................................... 105 external S bit is enabled check if for T1 ............................................ 94 external signaling check bits set............................................... 16 external signaling bits disable ......................................................... 16 extra bits setting in framer ........................................ 116

217

F facility data link reading/writing.............................................25 Facility Data Link...........................................166 FAS check multiframe starts with........................16 FDL Input/Output...............................................166 reading/writing.............................................25 FDL Buffers checking if separate buffers are used .........200 getting Tx and Rx buffer addresses ...........200 FdlStream class using ............................................................25 FdlStream Class..............................................166 file pattern get default name...........................................43 set default name ...........................................43 fill transmit buffers............................................68 fill transmit buffer with byte string ............................................50 with idle code...............................................49 FillTxChannels .......................................139, 140 FillTxGlobalBuffers ...................................49, 50 Firmware Version retrieving....................................................201 force resync...........................................................16 format message box.....................................36, 37, 38 format and display message box in DEBUG and RELEASE builds.......................................................36 message box in DEBUG build only.............36 FPGA Attributes retrieving (HD card only) ..........................198 setting (HD card only) ...............................199 FPS reading/writing.............................................25 frame get error counter...........................................16 frame bits get national, international or extra ...............16 set national, international or extra................16 frame error detect............................................................16 frame error counter E1 103 get ................................................................16 frame error counter (E1) resetting to a start value .............................104 frame error detected check if for T1 .............................................94 Frame Information

Saving, Accessing and Loading .................. 26 frame pattern sequence reading/writing............................................ 25 frame resync check if for E1 ............................................ 96 frame resync criteria is fixed check if for E1 ............................................ 96 Framer functions ..................................................... 16 framer bits getting extra .............................................. 117 getting international .................................. 117 getting national ......................................... 117 framer receive interrupt mask register reading for T1 and E1 ............................... 102 framer receive status register reading for T1 and E1 ............................... 102 framer register write to ........................................................ 72 framer RIMR reading for T1 and E1 ............................... 102 framer RSR reading for T1 and E1 ............................... 102 framer setting check for E1................................................ 96 framer settings checking T1 ................................................ 94 framer timeslot is selected for Tx idle code E1 only........................................................ 97 Ft and Fs reading/writing............................................ 25 function calling conventions ....................................... 4 exceptions ..................................................... 4 groups ....................................................... 4, 8 naming conventions ...................................... 4 order.....................................................6, 7, 28 Function parameters..................................................... 8 functions Codec control.............................................. 11 initialization .................................................. 8 mode control (monitor, terminate, bridge).. 10 termination.................................................... 8 Functions driver control .............................................. 14 port I/O........................................................ 12 G gain set codec...................................................... 73 Gain Get .............................................................. 11 Set ............................................................... 11 get idle code...................................................... 54

218

interrupt mask register .................................16 status register ...............................................16 Get Cross Port ..................................................85 get device driver information byte offset into current buffer ......................42 current active global buffer..........................42 max multiframe index in global buffer ........42 number of frames per multiframe ................42 parallel port base address.............................42 parallel port IRQ ..........................................42 parallel port memory address.......................42 Software buffer shared by VxD and Application..............................................42 start and end channel ...................................42 start and end channels..................................42 total global buffers received ........................42 total number of received multiframes ..........42 total number of transmitted multiframes......42 get global receive buffer pointer.......................52 get global transmit buffer pointer .....................52 GetActiveRxBufPtr ..........................................44 GetActiveRxSoftBuffer....................................59 GetActiveTxBufPtr...........................................45 GetActiveTxSoftBuffer ....................................58 GetApiVersion................................................120 GetCodec ..........................................................75 GetCurrentlySelectedDeviceNo .......................50 GetCurrentPatternFileName .............................43 GetDefaultPatternFileName .............................43 GetDr................................................................86 GetExceptionDescription .................................38 GetFr T1 and E1...................................................102 GetFrBits ........................................................117 GetFrErrorCounter .........................................103 GetIdleCode......................................................54 GetLatestTimeslotData...................................119 GetMaxDeviceCount......................................121 GetMaxTimeslot.............................................121 GetMultiFrameDuration ...................................56 GetMultiFrameSize ..........................................56 GetMultiRxGlobalBuffer0 ...............................52 GetMultiRxGlobalBuffer1 ...............................52 GetMultiSharedDevicePtr ................................42 GetMultiTxGlobalBuffer0................................52 GetMultiTxGlobalBuffer1................................52 GetNoOfDevicesFound ....................................52 GetNoOfDevicesInstalled.................................51 GetNoOfFramesPerMF ....................................55 GetNoOfFramesPerSoftBuffer .........................58 GetNoOfMultiFramesPerSoftBuffer ................57 GetPrevRxBufPtr..............................................46 GetPrevTxBufPtr..............................................47 GetProtocolBytesPerMs ...................................49 GetReadMissedBytesCount............................135 GetRxActiveBufferNumber .............................48

GetRxActiveBufferOffs................................... 45 GetTimeslotData............................................ 118 GetTxActiveBufferNumber............................. 48 GetTxActiveBufferOffs................................... 46 GetUsableSoftBufferSize ................................ 57 GetVersion..................................................... 120 GetWriteMissedBytesCount .......................... 136 GlcCriticalMsg ................................................ 37 GlcDebugMsg.................................................. 36 GlcEnableDbgMsg enable/disable diagnostic error message boxes ............................................................... 35 GlcMsg ............................................................ 36 GlComExceptions............................................ 33 get description............................................. 38 global receive buffer get pointer of............................................... 52 Global receive buffer get active buffer driver position (offset) ..... 13 get active buffer pointer .............................. 13 get active buffer sequence number.............. 13 get address .................................................. 13 get address for a device............................... 13 get inactive buffer pointer........................... 13 global transmit buffer get pointer of............................................... 52 Global transmit buffer fill with idle byte strings ............................. 13 fill with idle code ........................................ 13 get active buffer driver position (offset) ..... 13 get active buffer pointer .............................. 13 get active buffer sequence number.............. 13 get address .................................................. 13 get address for a device............................... 13 get inactive buffer pointer........................... 13 H HDB3 Tx/Rx (E1) disabling.................................................... 106 enabling.................................................... 105 HDLC ............................................................ 161 Bit Removal .............................................. 162 bit stuffing................................................. 161 encoding/decoding ...................................... 24 HDLC Frames Getting Rx or Tx Queue Size.................... 193 Getting total number of CRC errors.......... 194 Getting total number of discarded frame octets .................................................... 194 Getting total number of discarded frames. 194 getting total number of over and under runs ............................................................. 194 processing ................................................. 187 receive and transmit example.................... 192 received frame information structure........ 191 received time............................................. 191

219

receiving ....................................................190 receiving with frame information (timestamp etc.) .......................................................191 Setting and getting minimum number of flags between frames .....................................195 starting receiving or transmitting...............188 stopping receiving or transmitting .............193 transmitting................................................189 High Level Data Link bit stuffing and bit removing .......................24 encoding/decoding.......................................24 High Level Data Link Control........................161 High Levele Data Link Control Bit Removal...............................................162 Hook set on/off ......................................................22 I I/O address ...........................................................8 port.................................................................8 I/O Stream ..............................................130, 131 specifying channel masks ..................130, 131 I/O Stream Fill Global tranmit buffers with byte strings ........................................................140 I/O Stream Fill Global tranmit buffers with idle code............................................................139 I/O Stream Missed Bytes........................135, 136 I/O Stream Receive ........................................136 I/O Stream Receive Channel Mask ................132 I/O Stream Reopen .................................138, 139 I/O Stream Safe Margins ................133, 134, 135 I/O Stream Transmit .......................................137 I/O Stream Transmit Channel Mask ...............132 idle code check if FF or 7F .........................................16 fill receive/transmit global buffers with.......21 getting ..........................................................54 loading Tx buffer with ...............................125 transmitting..........................................49, 125 Idle code querying .........................................................9 inactive receive global buffer get pointer to................................................46 inactive transmit global buffer get pointer to................................................47 in-band network loop down disabling ......................................................91 enabling .......................................................90 in-band network loop up disabling ......................................................91 enabling .......................................................90 Include file for API library .......................................31 initial setting ..........................................................60

initialization options .......................................................... 8 with and without hardware setup .................. 8 Initialization error ............................................................ 32 initialization error description .................................................. 39 initialize base address ................................................ 63 driver........................................................... 60 hardware ..................................................... 60 interface ...................................................... 60 IRQ ............................................................. 63 memory offset............................................. 63 Initialize........................................................... 60 InitializeCodec................................................. 64 Input/Output Stream fill channel(s) with idle code....................... 21 get overrun/underrun byte count................. 21 reopen ......................................................... 21 reset............................................................. 21 set read channel mask ................................. 21 set read/write safe margins.......................... 21 insert BPV error.................................................... 19 single error .................................................. 19 insert error BPV ............................................................ 82 logical ......................................................... 82 InsertBerError.................................................. 82 installed cards qurying number........................................... 14 installed devices get number .................................................. 51 INT FPGA loading ........................................................ 66 interface object creating ..................................................... 6, 7 initializing ................................................. 6, 7 international bits setting in framer ........................................ 116 Interrupt querying ........................................................ 9 invalid parameters................................................8, 33 Inversion Mask ...............................127, 128, 129 Getting Rx................................................. 128 Getting Tx................................................. 129 Setting Rx ................................................. 128 Setting Tx.................................................. 127 InvertBits overloaded functions................................. 185 inverting bits MSB->LSB ........................................ 185 IRQ number .......................................................... 8

220

IsObjectCreated ................................................41 J jitter attenuation ...................................................14 control..........................................................14 setting on 3Hz..............................................93 setting on 6Hz..............................................93 jitter attenuation check if disabled ..........................................92 check if set on 3Hz ......................................92 check if set on 6Hz ......................................92 disabling ......................................................91 getting ..........................................................86 set on Rx ......................................................93 set on Tx ......................................................93 jitter attenuation on Rx check if set ...................................................92 jitter attenuation on Tx check if set ...................................................92 L latest time slot data retrieving....................................................119 line attenuation getting ..........................................................86 line length getting ..........................................................86 setting ..........................................................88 Line Level Voltage retrieving....................................................197 link list of variable records using ............................................................27 Linked List .....................................................182 Linking API library ...................................................31 LoadBerStaticPattern..................................84, 85 LoadDefaultConfig...........................................63 LoadIntFpga .....................................................66 LoadStaticBerIntFpga.......................................67 LoadTxBufferWithIdleCode ..........................125 LoadTxBufferWithMf ....................................125 local framer loopback check............................................................16 enable/disable ..............................................16 local loopback disable..........................................................16 disabling ..............................................91, 106 enable...........................................................16 enabling ...............................................90, 105 local loopback in driver is set check if ........................................................87 local loopback is active check if for E1 .............................................96 check if for T1 .............................................94 logical error

insert ........................................................... 82 loopback querying analog, remot, local, remote......... 14 querying network loopback up/down.......... 14 setting analog, remot, local, remote ............ 14 setting network loopback up/down ............. 14 LOS per status set check........................................................... 87 LOS transition set check........................................................... 87 M mask interrupts ..................................................... 16 maximum devices supported by device driver getting ....................................................... 121 maximum timeslot number getting ....................................................... 121 MemFile class using............................................................ 26 MemFile Class............................................... 175 memory address .......................................................... 8 Memory Mapped Files class using............................................................ 26 Memory Mapped I/O ..................................... 175 Memory offset querying ........................................................ 9 message boxes suppressing in debug mode....................... 6, 7 suppressing in debug mode with C interface ............................................................... 28 Microsoft Visual C++ API library .................................................. 31 mode bridge .......................................................... 10 checking...................................................... 69 monitor........................................................ 10 setting.......................................................... 70 terminate ..................................................... 10 monitor mode checking...................................................... 69 setting.......................................................... 70 MsbStuffBits.................................................... 24 function ..................................................... 161 multiframe filling Tx buffer with ................................ 125 transmitting ............................................... 125 multiframe duration getting ......................................................... 56 Multiframe duration querying ........................................................ 9 multiframe size getting ......................................................... 56 Multiframe size querying ........................................................ 9

221

multiframe start with FAS disable..........................................................16 N national bits setting in framer.........................................116 network loop ..............................................................14 network loop per status set check............................................................87 network loop transition set check............................................................87 network loopback detect disabling ......................................................91 enabling .......................................................90 network loopback in driver is set check if ........................................................87 Number of cards installed querying .........................................................9 number of devices get ................................................................51 number of devices found get ................................................................52 number of devices installed get number ...................................................51 Number of frames querying .........................................................9 number of frames in software buffer getting ..........................................................58 number of frames per multiframe getting ..........................................................55 Number of frames per multiframe querying .........................................................9 Number of frames per software buffer querying .........................................................9 number of multiframes in software buffer getting ..........................................................57 Number of multiframes per software buffer querying .........................................................9 O off-hook setting ........................................................122 on-hook setting ........................................................122 OOF criteria check if 2of4 ................................................16 set 2of4 or 2of5............................................16 OOF criteria 2 of 4 (T1) setting ........................................................108 OOF criteria 2 of 5 (T1) setting ........................................................108 OOF Criteria is 2 of 4 check if for T1 .............................................94 OUT data NRZ check if selected...........................................16

select ........................................................... 16 OUT data unipolar select ........................................................... 16 out of frame get error counter.......................................... 16 out of frame counter (T1) resetting to a start value ............................ 104 out of frame error counter T1 103 OutBitStream Class ....................................... 158 output data NRS is selected check if for T1 ............................................ 94 output data NRZ (T1) selecting .................................................... 109 output data unipolar (T1) selecting .................................................... 109 P Pattern file name get current ................................................... 20 get default ................................................... 20 set current.................................................... 20 set default.................................................... 20 Periodic File Saving allocating memory .................................... 207 class members ........................................... 204 clear messages .......................................... 210 closing....................................................... 208 closing all.................................................. 208 control loop........................................209, 210 creating ..................................................... 204 disk limit ................................................... 212 errors......................................................... 211 initiailizing................................................ 206 initialization .............................................. 210 initializing ................................................. 204 opening files.............................................. 206 releasing memory...................................... 207 synchronize ............................................... 211 using............................................................ 29 port reading from................................................ 64 reading from a XE "port A,B,C:input/output" hardware port ......................................... 12 writing to..................................................... 65 writing to a hardware port........................... 12 port A,B,C input/output................................................. 12 PP pattern file name get default ................................................... 20 set default.................................................... 20 R Read............................................................... 136 ReadBerErrXlinx ............................................. 82 ReadHardwareConfig ...................................... 63

222

reading subchannels................................................154 ReadPort ...........................................................64 ReadRxLineFrequency ...................................123 receive buffer disabling ....................................................124 enabling .....................................................123 receive DMA check if for E1 .............................................96 receive in CAS mode check if for E1 .............................................96 receive in CCS mode check if for E1 .............................................96 receive line frequency getting ........................................................123 receive loss of sync check if for E1 .............................................96 receive remote alarm check............................................................16 check if for E1 .............................................96 receive signaling all ones check............................................................16 check if for E1 .............................................96 receive unframed check............................................................16 receive unframed all ones check............................................................16 received unframed all ones check if for E1 .............................................96 remote alarm check if set ...................................................16 remote loopback disabling ......................................................91 enabling .......................................................90 remote loopback in driver is set check if ........................................................87 Reopen............................................................139 ReopenRead....................................................138 ReopenWrite...................................................138 ResetBerTxRx ..................................................84 ResetCodec.......................................................74 ResetDrRegisters ..............................................92 restore time slot status .............................................81 RestoreMultiTsStatus .......................................81 resync algo10 ..........................................................16 algo24 bits....................................................16 check in progress .........................................16 check OOF on..............................................16 check using FT bits......................................16 on OOF or OOF RCL ..................................16 using FT bits ................................................16 using FT FA bits ..........................................16 resync algo 10 bits check............................................................16

check if for T1 ............................................ 94 resync criteria check........................................................... 16 fixed or not fixed......................................... 16 resync framer (E1) CAS multiframe criteria fixed ................. 115 CAS multiframe criteria not fixed ........... 115 frame criteria fixed .................................. 115 frame criteria not fixed ............................ 115 resync framer (T1 and E1) forced........................................................ 115 resync framer (T1) on OOF..................................................... 115 on OOF RCL............................................ 115 using algo 10 bits ..................................... 115 using algo 24 bits ..................................... 115 using FT FS bits...................................... 115 using FT bits ............................................ 115 resync is using FT bits check if for T1 ............................................ 94 resync on OOF check if for T1 ............................................ 94 ResyncFr ....................................................... 115 RMSYNC wait for start................................................ 68 robbed bit sig (T1) disabling.................................................... 106 enabling.................................................... 105 robbed bit signal check if enabled .......................................... 16 disable ......................................................... 16 enable.......................................................... 16 robbed bit signal is enabled check if for T1 ............................................ 94 Running application................................................... 32 Rx line attenuation............................................ 14 Rx Buffer Enable application instance count receiving ......... 197 Rx buffer running count querying ........................................................ 9 Rx channel check if selected.......................................... 16 check if selected for code insert.................. 16 Rx channel is selected for code insert check if for T1 ............................................ 97 Rx COFA check detect is selected ............................... 16 Rx COFA detect is selected check if for T1 ............................................ 94 Rx CRC4 is enabled check if for E1 ............................................ 96 Rx equalizer gain is 12 dB check if........................................................ 87 Rx equalizer gain is 26 dB

223

check if ........................................................87 Rx equalizer gain is 36 dB check if ........................................................87 Rx HDB3 is enabled check if for E1 .............................................96 Rx loss of sync check............................................................16 Rx monitor mode selected check if ........................................................87 Rx Signaling Bits retrieving for HD cards..............................203 Rx/Tx set CCS or CAS ...........................................16 Rx/Tx CRC4 check............................................................16 Rx/Tx HDB3 check............................................................16 S save time slot status .............................................81 SaveMultiTsStatus............................................81 select channel for transparent or code insert..........16 channel for Tx idle code ..............................16 driver's current device number.....................54 SLC96..........................................................16 T1DM ..........................................................16 select BER receive..........................................................83 transmit ........................................................83 SelectCurrentDeviceNo....................................54 SelectFr...........................................................109 SelectFrTimeslot ............................................112 selecting framer attributes ....................................................109 SetBerTxRx ......................................................83 SetCodec.....................................................73, 74 SetCrossPort .....................................................84 SetCurrentPatternFileName..............................44 SetDefaultPatternFileName ..............................43 SetDr...........................................................88, 89 SetDrJitter.........................................................93 SetFr ...............................................................108 SetFrBits.........................................................116 SetFrErrorCounter ..........................................104 SetMode ...........................................................70 SetOnHook .....................................................122 SetReadChannelMask.....................................132 SetReadSafeMarginBytes...............................134 SetReadSafeMarginMultiFrames ...................133 setting framer features...........................................108 line length ....................................................14 network loop ................................................14 SetTxBuffers ....................................................68

SetWriteChannelMask................................... 132 SetWriteSafeMarginBytes ............................. 135 SetWriteSafeMarginMultiFrames.................. 133 SigBitsAsyncIo class Signaling Bits Xmission in multiple timeslots ............................................................. 149 signaling bits receiving ................................................... 145 Signaling Information retrieving for HD cards ............................. 201 singaling bit transitions receiving ................................................... 145 SLC96 check........................................................... 16 SLC96 (T1) selecting .................................................... 109 SLC96 is selected check if for T1 ............................................ 94 slect yellow alarm D4 B2 or S bit................................................... 16 slect yellow alarm ESF FDL or S bit ................................................ 16 Software buffer size querying ........................................................ 9 Sound Driver ................................................. 196 checking.................................................... 196 disabling.................................................... 196 enabling..................................................... 196 speaker check on/off ................................................ 78 turn off ........................................................ 77 turn on......................................................... 76 Speaker Disable ........................................................ 11 Enable ......................................................... 11 start with FAS enable.......................................................... 16 static BER INT FPGA loading ........................................................ 67 Stream Input/Output open ............................................................ 21 subchannel 56 kbps........................................................ 23 input/output................................................. 23 subchannels writing....................................................... 158 superframe error counter T1 103 superframe error counter (T1) resetting to a start value ............................ 104 symbols used in the document .................................... 4 SyncDevices .................................................... 54 synchronize devices......................................... 54

224

T T1DM check selected ..............................................16 T1DM (T1) selecting .....................................................109 T1DM is selected check if for T1 .............................................94 terminate mode checking.......................................................69 setting ..........................................................70 throwDebug ......................................................38 time slot check if available .........................................79 make available .............................................79 make unavailable .........................................79 time slot data retrieving....................................................118 time slot status restore ..........................................................81 save ..............................................................81 time slots check whether all are available....................80 deselecting all for code insert (T1) ............110 deselecting all for transparent (T1) ............110 deselecting for code insert (T1) .................113 deselecting for transparent (T1).................113 deselecting for Tx idle code...............110, 113 make all available ........................................80 make all unavailable ....................................80 selecting for code insert (T1) .....................112 selecting for transparent (T1).....................112 selecting for Tx idle code ..........................112 timeslot check if available .........................................20 enable...........................................................20 enable all......................................................20 functions ......................................................20 restore status ................................................20 save available...............................................20 save status ....................................................20 set codec ......................................................73 write assigner range .....................................20 write start/end assigner ................................20 Timeslot maximum number..........................................9 timeslot assigner range ............................................................70 specify range................................................71 write to start .................................................70 write to stop .................................................70 timeslot selected for Tx idle check............................................................16 Toolkit Contents .........................................................2 transmit all ones

disabling...................................................... 91 enabling....................................................... 90 transmit all ones is set check if........................................................ 87 transmit buffer disabling.................................................... 124 enabling..................................................... 123 transmit buffers fill 68 transmitting all ones qurying........................................................ 14 setting.......................................................... 14 trasmit buffer setting off-hook bit.................................... 122 setting on-hook bit .................................... 122 Tx 100 duty cycle check if for E1 ............................................ 96 Tx 100 or 50 check duty cycle.......................................... 16 Tx 50 duty cycle check if for E1 ............................................ 96 Tx B8SZ disable ......................................................... 16 Tx B8ZS check active ................................................ 16 enable.......................................................... 16 Tx B8ZS (T1) disabling.................................................... 106 enabling.................................................... 105 Tx B9ZS is active check if for T1 ............................................ 94 Tx blue alarm (T1) disabling.................................................... 106 enabling.................................................... 105 Tx blue alarm is enabled check if for T1 ............................................ 94 Tx Buffer Enable application instance count transmitting..... 197 Tx buffer running count querying ........................................................ 9 Tx channel is selected for transparent check if for T1 ............................................ 97 Tx channel is selected for Tx idle code check if for T1 ............................................ 97 Tx CRC4 is enabled check if for E1 ............................................ 96 Tx DMA check if for E1 ............................................ 96 disable ......................................................... 16 enable.......................................................... 16 Tx DMA (E1) disabling.................................................... 106 enabling.................................................... 105 Tx duty cycle select 100 or 50 ........................................... 16 Tx extra

225

check bits set................................................16 Tx extra bits (E1) disabling ....................................................106 enabling.....................................................105 Tx extra bits selected check if for E1 .............................................96 Tx extra, national and international bits disable..........................................................16 Tx HDB3 is enabled check if for E1 .............................................96 Tx idle code select 7F or FF .............................................16 Tx idle code 0x7F (T1) selecting .....................................................109 Tx idle code 0xFF (T1) selecting .....................................................109 Tx idle code is 0x7F check if for T1 .............................................94 Tx idle code is 0xFF check if for T1 .............................................94 Tx in CAS mode check if for E1 .............................................96 Tx in CCS mode check if for E1 .............................................96 Tx international check bits set................................................16 Tx international bits (E1) disabling ....................................................106 enabling.....................................................105 Tx international bits selected check if for E1 .............................................96 Tx multiframe disable..........................................................16 Tx multiframe start with FAS (E1) disabling ....................................................106 enabling.....................................................105 Tx multiframe starts with FAS check if for E1 .............................................96 Tx national check bits set................................................16 Tx national bits (E1) disabling ....................................................106 enabling.....................................................105 Tx national bits selected check if for E1 .............................................96 Tx remote alarm check if for E1 .............................................96 disable..........................................................16 enable...........................................................16 Tx remote alarm (E1) disabling ....................................................106 enabling.....................................................105 Tx signaling all ones check if for E1 .............................................96 disable..........................................................16 enable...........................................................16

Tx signaling all ones (E1) disabling.................................................... 106 enabling.................................................... 105 Tx Signaling Bits checking if enabled for HD cards ......203, 204 retrieving for HD cards ............................. 202 setting for HD cards.................................. 202 Tx signaling on ones check........................................................... 16 Tx yellow alarm (T1) disabling.................................................... 106 enabling.................................................... 105 Tx yellow alarm is enabled check if for T1 ............................................ 94 Tx yellow and blue alarms check if enabled .......................................... 16 Tx/Rx CRC4 disable ......................................................... 16 enable.......................................................... 16 Tx/Rx DMA check........................................................... 16 Tx/Rx HDB3 disable ......................................................... 16 enable.......................................................... 16 U unframed all ones check set...................................................... 16 disable ......................................................... 16 enable.......................................................... 16 unframed all ones (E1) disabling.................................................... 106 enabling.................................................... 105 unframed all ones is selected check if for E1 ............................................ 96 unframed input disabling.................................................... 126 enabling..................................................... 127 unmask interrupts ..................................................... 16 usable software buffer size getting ......................................................... 57 using algo 10 bits (T1) forced........................................................ 115 V Variable Records Saving, Accessing and Loading .................. 26 VarRecBuf class using............................................................ 26 VarRecBuf Class ........................................... 177 VF Output Disable ........................................................ 11 Enable ......................................................... 11 VF transmission check on/off ................................................ 78

226

turn off .........................................................77 turn on..........................................................76 W Wait ..................................................................68 wait for start of RMSYNC ...............................68 write to audio, driver or framer register ................72 Write...............................................................137 WritePort ..........................................................65 WriteRegister....................................................72 WriteTsAssigner...............................................70 WriteTsAssignerRange.....................................71 X Xilinx loading ...................................................66, 67

Y yellow alarm check........................................................... 16 disable ......................................................... 16 enable.......................................................... 16 yellow alarm detected check if for T1 ............................................ 94 Z zero suppression B7 check........................................................... 16 set 16 setting (T1)................................................ 108 zero suppression B7 is set check if for T1 ............................................ 94 zero suppression transparent set 16 setting (T1)................................................ 108

227