Programming Library Reference and User Guide

RADCOM
Protocol Analyzers
User Programming Library
Reference & User Guide
Applicable to the following protocol analyzers:

RC-88W, RC-100W, RM-88W and RM-100W WAN Protocol Analyzers
RC-88WL, RC-100WL, RM-88WL and RM-100WL WAN/LAN Protocol Analyzers
RC-88WFL and RC-100WFL WAN/Fast LAN Protocol Analyzers
Prism200 and PrismLite WAN/LAN/ATM Protocol Analyzers
RADCOM Ltd., 2000

Fifth Edition: December, 2000
Catalog No.: 10-0122, Revision A

Copyright 2000 by RADCOM
This documentation contains proprietary information of RADCOM Ltd. and RADCOM
Equipment Inc. Such information is hereby supplied solely for the purpose of informing
explicitly and properly authorized persons of the documentation on the operation of
RADCOM equipment. Without the express prior written permission of RADCOM Ltd. and
RADCOM Equipment Inc., no part of the contents hereof may be used for any other
purpose, disclosed to persons or firms outside the recipient company, or reproduced by any
means.
The text and drawings herein are for the purpose of illustration and reference only. The
specifications on which they are based are subject to change without notice.
Catalog No.: 10-0122, Revision A
Publication Name: User Programming Library Reference & User Guide
Publication No.: DLL0296.65
Publication Date: December, 2000
Trademark Acknowledgements
DECnet is a registered trademark of Digital Corporation.
Ethernet is a registered trademark of Xerox Corporation.
IBM and IBM-PC are registered trademarks of International Business Machines
Corporation.
MS-DOS and MS-WINDOWS are registered trademarks of Microsoft Corporation.
Further Information
For further information contact:
International Headquarters:
RADCOM Ltd.
12 Hanechoshet St., Tel Aviv, 69710, Israel.
Tel: 972-3-6455055, Fax: 972-3-6474681.
E-mail: info@radcom.co.il; Internet: http://www.radcom-inc.com
US Headquarters:
RADCOM Equipment Inc.
575 Corporate Drive, Mahwah, NJ 07430, USA.
Tel: (201) 529-2020, Fax: (201) 529-0808.
E-mail:info@radcomusa.com
End-User Software License
Notice: Read this license very carefully before opening the enclosed package. Upon opening the package, you shall become subject to the
provisions of this license, and by so doing you will have signified your willingness and consent to be bound by the said provisions.
1. This License applies to the computer communications product and/or software (as defined herein below) with which it is enclosed. The
purchaser of such product/software shall be referred to herein as "Licensee"; the entity from which such product/software has been purchased
shall be referred to as "Distributor"; and the manufacturer of such product/software shall be referred to as "Licensor".
2. Licensee has signified willingness to be bound by the terms of this License and consents hereto by opening the enclosed package.
3. Definitions: Software shall mean all computer programs and related documentation, as well as all corrections, updates, new releases and new
versions of such programs and documentation. Software Products shall mean Software, as well as computer communications products
(hardware) in which Software is an inherent and integral part.
4. Subject to the terms set forth in this License, the Licensee may use the enclosed Software Product and all associated documentation furnished
herewith. Where applicable, the Licensee may use the Software for execution with a single CPU (hereinafter, "the host computer"). Such
Software may be accessed on the host computer via terminal and/or system console in a timesharing manner by more than one user and/or
may be remotely accessed via a communications line or a network line. No license, right, or interest in any trademark, trade name, or service
mark of the Licensor or any third party from whom it has acquired license rights are granted to the Licensee hereunder.
5. The Licensee may use the Software on backup equipment in the event and only so long as the host computer is inoperative.
6. The Licensee may make one backup copy of the Software or of the Software inherent in the Software Product, as applicable, provided that
the same copyright and proprietary information notices are those affixed to the original Software Product are affixed to the backup copy. In
lieu of such a backup copy, the Licensee may transfer the said Software to a single hard disk, subject to the provisions concerning copyright
and proprietary right notices as specified herein above, provided that in such case the original Software be kept solely for backup or archive
purposes.
7. All upgrades, updates, modifications and provisions of the Software Product delivered by the Licensor to the Licensee shall be subject to the
terms and conditions of this License.
8. The Software Product and its copyrights are owned by the Licensor or its suppliers, and are protected by law and by international treaties.
Except as provided under section 6 above, the Licensee may not copy the Software or reproduce the Software Product. The Licensee may
not copy or translate the written materials except by specific written consent of the Licensor, which must be obtained in advance.
9. Downloading or otherwise copying the Software Product for execution on more than one CPU is strictly prohibited. The Licensee may not
copy, modify, reverse compile, reverse engineer, sell, license, rent or transfer the Software Product or any documentation related thereto to
any third party. The software contains a module called Graphics Server SDK which is copyrighted by Bits Per Second Ltd. This module is
considered as part of the Software Product and must not be used alone.
10. The Licensor warrants solely to the Licensee for a period of twelve months from the date of the Software Product delivery to the Licensee
that the Software shall be in operable condition as described in the documentation provided therewith, and will be free from defects in
material and workmanship under normal use.
11. The warranty as set out in section 10 supra shall be the sole and exclusive warranty, and the Licensor shall accept no responsibility beyond
that which is set out therein.
12. In particular, and without derogating from the generality of the above, the Licensor does not warrant that the Software Product shall be error-
free, that the Software Product shall operate with any hardware and software other than the Software Product, as specified in the
documentation provided with the Software Product, or that the Software Product shall satisfy the Licensee's own specific requirements. The
Licensor DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The Licensor's third party suppliers, if any, assume no liability whatsoever regarding the Software Product.
13. The agents, employees, distributors and dealers of the Licensor are not authorized to make modifications to this warranty, nor are additional
warranties binding on Licensor or its suppliers, if any.
14. The Licensee's sole and exclusive remedy and the Licensor's sole and exclusive liability hereunder shall be, upon the Licensee's return of the
Software Product to a Distributor within the warranty period, replacement or repair of the Software Product that does not meet the Licensor's
limited warranty as above. The Licensor's suppliers shall not be held liable for any damages suffered or incurred by the Licensee.
15. In no event shall the Licensor or its suppliers be liable to the Licensee or any other person for any incidental, collateral, special, or
consequential damages, including without limitation, damages for loss of profits, loss of customers, loss of goodwill, work stoppage, data
loss, computer failure or malfunction, claims by any party other than Licensee or any and all other similar damages or loss.
16. The Licensor shall have no liability or responsibility for Software Products altered, modified, converted by the Licensee or by a third party,
damages resulting from accident, abuse or misapplication of the Software Products or for problems due to the malfunction of the Licensee's
equipment or software not supplied by the Licensor.
17. This License is effective until terminated and will be terminated with or without notice from the Licensor if the Licensee fails to comply with
any of its provisions. Upon termination the Licensee shall destroy the Software and all copies or portions thereof.
18. This license is governed by the laws of the State of Israel and the sole jurisdiction over all matters arising from this License shall rest with the
competent courts in Tel Aviv-Yaffo.
Table of Contents
About This Guide
Division of Chapters 1
Terminology and Conventions 2
Additional Technical Support 3
Chapter 1: Introduction
Background 1-1
Applications 1-1
Software Interface 1-2
General Functions 1-2
Name 1-3
SaveSetup 1-4
RecallSetup 1-5
ExitDLL 1-6
Chapter 2: User-Defined Analysis

Introduction 2-1
Analyzer Interface 2-1
Functions 2-2
AnalysisNames 2-2
AnalysisSetup 2-4
AnalysisInit 2-5
AnalyzeFrame 2-6
AnalysisGetYAxis 2-7
AnalysisExit 2-8
AnalysisDone 2-9
Example 2-9
Chapter 3: Decode a Single Frame

Introduction 3-1
Functions 3-2
DecodeFrameNames 3-3
DecodeFrameSetup 3-4
DecodeSingleFrame 3-5
Example 3-6
DLL0296.65 1
Chapter 4: Process All Frames in Capture Buffer

Introduction 4-1
Functions 4-2
ProcessAllFramesNames 4-2
ProcessAllFramesSetup 4-3
ProcessAllFramesInit 4-4
ProcessFrame 4-5
ProcessAllFramesExit 4-6
Example 4-6
Chapter 5: User-Defined Filter

Introduction 5-1
Functions 5-2
FilterClassNames 5-3
DefaultFilterNames 5-4
FilterExists 5-5
FilterNew 5-6
FilterEdit 5-7
FilterDelete 5-8
FilterFrame 5-9
Example 5-9
Chapter 6: Background Record

Introduction 6-1
Functions 6-2
OLProcessFramesNames 6-2
OLProcessFramesSetup 6-4
OLProcessFramesInit 6-5
OLProcessFrame 6-6
OLProcessFramesExit 6-7
Example 6-7
Chapter 7: Link to Live Analysis Data

Introduction 7-1
Functions 7-3
AnalysisLinkNames 7-3
AnalysisLinkSetup 7-5
AnalysisLinkStarted 7-6
AnalysisLinkResults 7-7
AnalysisLinkStopped 7-8
Example 7-8
2 DLL0296.65
Table of Contents
Chapter 8: Link to Live Statistics Data

Introduction 8-1
Functions 8-3
StatisticsLinkNames 8-3
StatisticsLinkSetup 8-4
StatisticsLinkStarted 8-5
StatisticsLinkResults 8-6
StatisticsLinkStopped 8-7
Example 8-7
Chapter 9: Link to Live Line Status Data

Introduction 9-1
Functions 9-3
LineStatLinkNames 9-3
LineStatLinkSetup 9-4
LineStatLinkStarted 9-5
LineStatLinkResults 9-6
LineStatLinkStopped 9-7
Example 9-7
Chapter 10: User-Defined Simulation

Introduction 10-1
Functions 10-3
SimulationNames 10-4
SimulationSetup 10-5
SimulationStarted 10-6
SimulationGetSetupStrings 10-8
SimulationGetFilter 10-9
SimulationFilterNotExist 10-10
FrameReceived 10-11
GetStatus 10-12
SimulationStopped 10-13
SimulationGetSummaryStrings 10-14
SimulationDisplayPostExecution 10-15
SimulationCloseAll 10-16
SendFrame 10-17
StopSim 10-18
DoneSim 10-19
Skeletal Program 10-19
DLL0296.65 3
Appendix A: Reference Guide

ATM Frame Header Structure 1
Definitions 1
AAL Types 1
Frame Parameters: (U32) 1
Frame Status (U16) 3
Frame Time 4
Error Messages 5
General 5
User-defined Analysis 5
User-defined Simulation 6
Decode a Single Frame 7
User-defined Filter 7
Process All Frames in Capture Buffer 7
Process Frames in Background Record Process 8
Link to Live Analysis Data 8
Link to Live Statistics Data 8
Link to Live Line Status Data 8
List of Functions and Syntax 9
4 DLL0296.65
About This Guide
Division of Chapters
This guide is divided into the following chapters:
Chapter 1 Introduction
Applications.
Software interface.
General functions.
Chapter 2 User-Defined Analyses

Analyzer interface.
Functions.
Error messages.
Example.
Chapter 3 Decode a Single Frame

Analyzer interface.
Functions.
Error messages.
Example.
Chapter 4 Process All Frames in Capture Buffer

Analyzer interface.
Functions.
Example.
Chapter 5 User-Defined Filter

Analyzer interface.
Functions.
Example.
Chapter 6 Background Record

Analyzer interface.
Functions.
Example.
DLL0296.65 1
Chapter 7 Link to Live Analysis Data

Analyzer interface.
Functions.
Example.
Chapter 8 Link to Live Statistics Data

Analyzer interface.
Functions.
Example.
Chapter 9 Link to Live Line Status Data

Analyzer interface.
Functions.
Example.
Chapter 10 User-Defined Simulation

Analyzer interface
Functions.
Skeletal program.
Appendix A Reference Guide

Frame header structure.
Definitions.
Error messages.
List of functions and syntax.
Note:
Refer to the User Guide for information on basic operation procedures.
Refer to A World of Protocols for specific information on various protocols.
Terminology and Conventions

Formatting Conventions
The following formatting conventions are used throughout the documentation:
Note: Additional information relevant to the presently-discussed subject.
Warning: Information that is essential for your safety and to avoid damaging
Caution: the hardware or software.
bold text Operations that you must perform (e.g., name of a button to be
clicked or option to be selected) or to emphasize a field or concept
being described.
2 DLL0296.65
About This Guide
bold italic text Information or text that you must provide exactly as it appears.
italic text Terms defined in the text or which are being emphasized.
Windows Terminology
Dialog boxes are used for selecting options, entering text or choosing a command button.
The following items may be contained within a dialog box to enable communication
between you and the system.
Text boxes Display information which may be modified.
List boxes Display a list of options from which you may choose.
Drop-down list Display a list of options from which you may choose. A drop-
boxes down list box looks like a text box with a down arrow on the right
side. Clicking the arrow will display a list of options to be
displayed.
Command buttons Execute the designated operation, e.g., OK, Cancel.
Option buttons Select from among several options. Option buttons generally
appear in groups where you can select only one of the buttons in
the group.
Check boxes Turn certain settings on and off.
Additional Technical Support

Documentation
In addition to this guide, your protocol analyzer includes an Installation and Configuration
Guide for installation procedures, a User Guide for working with the basic system and A
World of Protocols for detailed information about protocols.
Further Information
If you have any questions about your protocol analyzer, contact your local distributor.
DLL0296.65 3
Chapter 1
Introduction
Background
Your protocol analyzer has been designed with a modular structure that allows adding
functionality as necessary. Until now, this functionality had to be added to the system via
the companys software development team.
Software development for the analyzer will continue to be developed according to market
growth and needs. However, it may happen that you are interested in a specific application
that is not currently being developed, or that is not of general interest to protocol analyzer
users. The software now enables you to add this functionality yourself to the analyzer. At
startup, the PC program searches and loads external DLLs which are present on your hard
disk. This mechanism has several possible uses:
Allows incorporation of user-defined routines and user-defined functionality into the
analyzer software.
Allows functionality to be added to the decode mechanism.
Allows user-defined simulations.
Allows for the quick addition of features without editing the systems major DLLs.
This guide describes some applications for user-defined DLLs and gives the particular
syntax for writing them. A basic knowledge of some programming language is assumed
(e.g., PASCAL, C++) as well as some background in writing DLLs for windows-based
applications.
Applications
The analyzer software provides you with the capability to add functionality in the following
areas:
Process all frames in the Capture buffer. This DLL allows the processing of the
Capture buffer in order to perform various complicated calculations, export to custom
formats, etc.
User-defined filter. Such a filter could be based on external events, e.g., database
access, etc.
Decode a single frame. This DLL allows decodes which might take longer to process or
require outside information.
DLL0296.65 1-1
User-defined analysis. A wide range of analyses can be performed on the data in the
capture buffer.
Background Record. This DLL allows the performance of various processes on frames
while they are being saved to disk in the Background Record process.
Link to live Analysis data. This DLL allows the performance of various processes on
live Analysis data.
Link to live Statistics data. This DLL allows the performance of various processes on
live Statistics data.
Link to live line status data. This DLL allows the performance of various processes on
live line status data.
User-defined simulation. Allows you to write your own simulation application and
merge it with RADCOMs software.
Software Interface
DLLs can be compiled as 32-bit applications or as 16 bit-applications depending on the
version you have of the protocol analyzer. DLLs are loaded when the software is started. To
identify which DLLs are to be loaded, two lines should be added to the udd32.ini file (which
must be created inside your Windows directory) in the [applications] section. This directory
is named as udd.ini if you work with 16-bit applications:
DLLDirName=c:\rc2v171\dll; specifies the directory in which the DLLs reside
(c:\rc2v171\dll in this example). The directory names of the 16-bit DLL and 32 bit-DLL
must be different.
DLLNames=dllname1.dll, dllname2.dll, etc.; should give a list of all available
DLLs. In this case you can use the same name for the 16-bit DLL and the 32-bit DLL.
All user-defined DLLs should be placed in the above mentioned directory.
The system can be run under debug mode, thus providing informative error messages. In
order to define the debug mode, another line should be added to the udd.ini/udd32.ini file as
follows:
UserDLLDebugMode=T; indicates that all user DLLs are run under debug mode.
General Functions
Note:
1. DLLs can be compiled as 32-bit applications or as 16-bit applications depending on the
version you have of the protocol analyzer. In the Help menu click About to see whether
you have a 32-bit or 16-bit version of the protocol analyzer.
1-2 DLL0296.65
2. In 32-bit applications all functions should be declared as _export _stdcall

In 16-bit applications all functions should be declared as _export _FAR_pascal.
3. DLLs previously compiled in 16 bits must be recompiled using 32 bit compilation, making
the above changes.
4. Refer to Appendix A for detailed information concerning the various variable definitions
and error messages.
There are a number of general functions which are common to all services provided by the
user-defined DLL. Name is used to identify the name of the DLL. SaveSetup and
RecallSetup are used in the Save Setup and Recall Setup procedures and other similar
operations. ExitDLL is called when the DLL is unloaded. These functions must be part of
the DLL.
Name
This function is mandatory. It identifies the name of the user-defined DLL.
Syntax
char* Name(void* Reserved);
Parameters
Reserved For future use.
Return Value
char* Name of the DLL.
DLL0296.65 1-3
SaveSetup
This function is used to save the user-defined filters, analyses, etc. It is called every time the
setup is saved (Save Setup command by the user, exit from the system, load another Setup,
etc.).
Syntax
void SaveSetup(char* DirName, void* Reserved);
Parameters
DirName Directory in which to save the information.
Return Value
Nothing
1-4 DLL0296.65
RecallSetup
This function is used to recall the user-defined filters, analyses, etc. It is called every time
the setup is recalled (Recall Setup command by the user).
Syntax
void RecallSetup(char* DirName, void* Reserved);
Parameters
DirName Directory where the information is located.
Return Value
Nothing
DLL0296.65 1-5
ExitDLL
This function is called when the DLL is unloaded. It can be used to free memory, etc.
Syntax
void ExitDLL(void* Reserved);
Parameters
Return Value
Nothing
1-6 DLL0296.65
Chapter 2
User-Defined Analysis
Introduction
The analyzer currently performs a number of analyses on captured data. The analysis
software takes a group of frames and divides them into several bins, giving each bin a
descriptive name. A user-defined analysis uses an external DLL to do the same thing. The
external DLL allows:
Definition of new analyses, e.g., signalling call disconnection analysis, signalling
performance analysis, retransmission analysis.
Definition of user-specific analyses.
Analyzer Interface
Additional analyses are added to the Analysis dialog box which is accessed by clicking the
Options button in the capture buffer and selecting Analysis. The user-defined analyses will
be available for selection in the Subject and Analysis drop-down list boxes. When a selected
analysis has a setup capability, a Setup button becomes active in the Analysis dialog box.
DLL0296.65 2-1
Functions
Analyses are grouped into subjects (e.g., Ethernet). Each subject has its associated analyses
(e.g., Network Traffic Activity Pairs) and a short description (Use this analysis to view
network traffic activity between pairs of nodes.). The function AnalysisNames returns to the
analyzer the list of currently defined subjects, analyses and descriptions. AnalysisSetup is
called by the analyzer if the user clicks on the Setup button in the Analysis dialog box.
AnalysisInit is called once for initialization of the analysis, AnalyzeFrame is called for
each frame processed and AnalysisExit is executed at the end to display the analysis results.
AnalysisGetYAxis specifies a label for the Y-axis in the display. AnalysisDone frees up the
memory and structures used for the analysis.
AnalysisNames
AnalysisNames returns a list of subjects, analyses and descriptions to be displayed in the
off-line Analysis dialog box. It also specifies those options which are to be enabled for the
user to select in the off-line Analysis dialog box.
Syntax
AnalyzeNameType* AnalysisNames(void* Reserved);
Parameters
Return Value
AnalyzeNameType* Array of structures containing subject, name, description and
capabilities. The last item in the array must contain null values:
Subject=0, Name=0 and Description=0.
The format of AnalysisNames is as follows:
typedef struct {
char* Subject;
char* Name;
char* Description;
U32 Capabilities;
} AnalyzeNameType
Capabilities refers to those options in the Analysis dialog box which are to be enabled and
the line type of the analysis. The user-defined analysis only appears for supported line types.
For example, if Graphic Pie is supported then the variable PieSupported is included in the
list of capabilities for the analysis. The Graphic Pie option is then enabled in the off-line
Analysis dialog box. You can specify for which interfaces (e.g., ATM, ASYNC, Ethernet,
etc.) the analysis will be supported with the appropriate capability value (e.g.,
ATM_SAR_UNISupported, ASYNCSupported, EthernetSupported, etc.).
2-2 DLL0296.65
Values for the various capabilities are provided below:

#define BarSupported 0x00000001
#define PieSupported 0x00000002
#define FramesSupported 0x00000004
#define BytesSupported 0x00000008
#define ValueSupported 0x00000010
#define PercentSupported 0x00000020
#define SetupSupported 0x00000040
#define AllLineTypesSupported 0x00FFFF00
#define ASYNCSupported 0x00000200
#define HDLCSupported 0x00000400
#define TransparentSupported 0x00000800
#define TokenRingSupported 0x00001000
#define EthernetSupported 0x00002000
#define ATM_SAR_UNISupported 0x00010000
#define ATM_Combo_UNISupported 0x00080000
DLL0296.65 2-3
AnalysisSetup
This function is called when the user clicks the Setup button in the Analysis dialog box. It
enables the user to input additional information to the DLL.
Syntax
void AnalysisSetup(char* Subject, char* AnalysisName,HWND
parentWin, void* Reserved);
Parameters
Subject Subject selected by the user in the Analysis dialog box.
AnalysisName Analysis selected by the user in the Analysis dialog box.
parentWin Handle to parent window. This is used to open the Setup dialog
box.
Return Value
Nothing
2-4 DLL0296.65
AnalysisInit
AnalysisInit is called once to initialize the analysis. It provides the user-defined DLL with
information concerning the analysis to be run. The DLL can use this information to initialize
the analysis computations and allocate memory, etc.
Syntax
void AnalysisInit(char* Subject, char* AnalysisName, BOOL
Frames, BOOL Percent, void* Reserved);
Parameters
Subject Subject selected by the user in the Analysis dialog box.
AnalysisName Analysis selected by the user in the Analysis dialog box.
Frames True if analysis by Frames is chosen; False if analysis by Bytes
is chosen.
Percent True if analysis by Percent is chosen; False if analysis by Value
is chosen.
Return Value
Nothing
DLL0296.65 2-5
AnalyzeFrame
This function is called for each frame received by the analyzer. It is used to pass information
concerning the frame to the DLL so that the appropriate computations can be made.
Syntax
void AnalyzeFrame(TimeStruct* Timestamp, U16 FrameStatus, U32
FrameParameters, U16 FrameLength, U8* RawData, void*
Reserved);
Parameters
Timestamp Pointer to a structure containing the time. Refer to Appendix A
for the time structure format.
FrameStatus 0 is OK. Refer to Appendix A for the frame status values.
FrameParameters Line type (ATM, Ethernet, HDLC), direction, etc. Refer to
Appendix A for the frame parameters values.
FrameLength Frame length in bytes.
RawData Data received. For ATM transmissions, the first 8 bytes (before
the actual data) contain information about the desired VPI, VCI
and AAL type.
Return Value
Nothing
2-6 DLL0296.65
AnalysisGetYAxis
This function allows the DLL to define a label for the y-axis to be displayed in a bar graph.
Syntax
char* AnalysisGetYAxis(void* Reserved);
Parameters
Return Value
char* Name of y-axis.
DLL0296.65 2-7
AnalysisExit
This function allows the DLL to clean up and return the results of the analysis for the
analyzer software to display.
Syntax
AnalyzeResult* AnalysisExit(void* Reserved);
Parameters
Return Value
AnalyzeResult* Array of {BinName, BinValue}. The last item has a BinName of
Null. The maximum number of name/value pairs is 10.
The format of the results structure is shown below:
typedef struct {
char * BinName;
float BinValue;
} AnalyzeResult;
The exact values returned by this function are displayed on the graph. If the user has
requested an analysis by percent, the user-defined DLL must return percentage values.
2-8 DLL0296.65
AnalysisDone
This function is called when the user presses the Done button in the Analysis window. All
the memory and structures used for the analysis can now be freed.
Syntax
void AnalysisDone(void* Reserved);
Parameters
Return Value
Nothing
Example
The following program performs an analysis by AAL type. Each section is documented with
comments designated by "//".
#include "windows.h"
#include "defs.h"
#include "stdio.h"
// This section of the program contains the variable definitions.
extern "C"
{
// This array should list all names of the analyses supported by the DLL.
// In this case there is only one. It is used in the AnalysisNames function.
AnalyzeNameType anlyssNames[ ] =
{
{ "User-defined analysis",
"My AAL Type",
"My first user-defined analysis",
BarSupported|PieSupported|FrameSupported|BytesSupported|
ValueSupported|PercentSupported|ATM_SAR_UNISupported
},
{NIL, NIL, NIL, 0}
};
// These variables are used to calculate the DLL results.

AnalyzeResult anlyssResults[MaxAnalysisSegments];
BOOL framesAnalysis;
DLL0296.65 2-9
BOOL percentAnalysis;
// Defines and variables for AAL type distribution.

typedef struct AalVal
{
int aalVal;
float framesNum;
};
#define MaxAALVal 5
#define AALInData 6
int aalCounter;
AalVal aalAnalysisArray[MaxAALVal];
// Function: AnalysisNames
// =======================
// This function returns the list of names of the analyses that this DLL
// supports. This list has been created above.
// Parameters:
// -----------
// void* reserved - for later use
// ===========================================================
AnalyzeNameType* _export _stdcall AnalysisNames(void* /*reserved*/)
{
return anlyssNames;
}
// Function: AnalysisSetup
// =======================
// This function is used in order to open a setup dialog box for the user
// to provide additional information. In this example, the analysis does not
// have any setup, so this function does nothing.
// Parameters:
// -----------
// char* subject - the subject of the chosen analysis
// char* analysisName - the name of the analysis that should open the setup
// window
// HWND parentWin - Parent window, to open the setup window on
// ===========================================================
void _export _stdcall AnalysisSetup(char* subject,
char* analysisName,
HWND parentWin,
2-10 DLL0296.65
void* /*reserved*/)
{
}
// Function: AnalysisInit
// ======================
// This function initializes the local variables and prepares everything for
// the analysis. In this example, it initializes the arrays that will count
// the types of AALs in the frames.
// Parameters:
// -----------
// char* subject - The subject of the chosen analysis
// char* analysisName - The name of the chosen analysis
// BOOL frames - frames/bytes to be calculated in the analysis
// BOOL percent - analysis calculates value/percent
// ===========================================================
void _export _stdcall AnalysisInit(char* subject,
char* analysisName,
BOOL frames,
BOOL percent,
void* /*reserved*/)
{
framesAnalysis = frames;
percentAnalysis = percent;
// Init variables for AAL type analysis

aalCounter = 0;
for (int i=0; i < MaxAALVal; i++)
{
aalAnalysisArray[i].aalVal = 0;
aalAnalysisArray[i].framesNum = 0;
}
// Init results array

for (i=0; i < MaxAnalysisSegments; i++)
{
anlyssResults[i].binName = NIL;
anlyssResults[i].binValue = 0;
}
}
// Function: AnalyzeFrame
DLL0296.65 2-11
// ======================
// This function gets one frame of the buffer and analyses it. In this
// example it calculates the frame AAL value and adds 1 to the bin of this
// AAL. This is the section of the program where calculations per frame are
// performed.
// Parameters:
// -----------
// TimeStruct* timeStamp - Time stamp of the frame
// U16 frameStatus - Status of the frame. See appendix for options
// U32 frameParameters - Line type, direction etc.
// U16 frameLength - Number of bytes in the frame
// U8* rawData - The data of the frame
// void* reserved - For later use
// ===========================================================
void _export _stdcall AnalyzeFrame(TimeStruct* timeStamp,
U16 frameStatus,
U32 frameParameters,
U16 frameLength /* in bytes */,
U8* rawData,
void* /*reserved*/)
{
if (frameLength*2 > AALInData)
{
// Find value of AAL type in the frame
int aal = rawData[AALInData];
BOOL frameCounted = FALSE;
// Find this AAL type in the analysis array

for (int i=0; i < aalCounter; i++)
{
if (aalAnalysisArray[i].aalVal == aal)
{
if (framesAnalysis)
{
aalAnalysisArray[i].framesNum ++;
} else {
aalAnalysisArray[i].framesNum += frameLength;
}
frameCounted = TRUE;
break;
}
}
2-12 DLL0296.65
// If this AAL type doesn't exist in the array, add it.

if (!frameCounted)
{
if (aalCounter < MaxAALVal)
{
aalAnalysisArray[i].aalVal = aal;
if (framesAnalysis)
{
aalAnalysisArray[aalCounter].framesNum ++;
} else {
aalAnalysisArray[aalCounter].framesNum +=
frameLength;
}
aalCounter++;
}
}
}
// Function: AnalysisExit
// ======================
// This function is called when all the frames have been sent to the DLL. It
// finishes the calculations and returns an array of the analysis results.
// After this function returns, the system opens the dialog box with the
// analysis results.
// Parameters:
// -----------
// ===========================================================
AnalyzeResult* _export _stdcall AnalysisExit(void* /*reserved*/)
{
char *text;
{
text = new char[10];
sprintf(text, "%d", aalAnalysisArray[i].aalVal);
anlyssResults[i].binName = text;
anlyssResults[i].binValue = aalAnalysisArray[i].framesNum;
}
return anlyssResults;
}
DLL0296.65 2-13
// Function: AnalysisGetYAxis
// ==========================
// This function is called before opening the results window. It returns the
// string that describes the Y-axis of the analysis graph.
// Parameters:
// -----------
// ===========================================================
char* _export _stdcall AnalysisGetYAxis(void* /*reserved*/)
{
return "AAL value";
}
// Function: AnalysisDone
// ======================
// This function is called after the user closes the dialog box of the
// analysis results. It frees all the memory that has been allocated for
// this analysis.
// Parameters:
// -----------
// ===========================================================
void _export _stdcall AnalysisDone(void* /*reserved*/)
{
{
if (anlyssResults[i].binName)
delete[ ] anlyssResults[i].binName;
}
}
}
2-14 DLL0296.65
Chapter 3
Decode a Single Frame
Introduction
The analyzer currently performs the decoding of a variety of protocols. The analyzer
software receives information from the line and interprets and displays the information on
the screen. There are instances, both on-line and in post-capture analysis, where the current
analyzer decode mechanism cannot deal with all possible requirements. Examples are:
Complex calculations, e.g., CRC.
Live links to other applications.
Custom decodes not supported by the analyzer.
Extracting the name of an SNMP object.
Extracting information from a user database, e.g., the link between the Ethernet station
address and the user name.
The user-defined decode uses an external DLL to add custom decodes, or replace existing
decodes with user-defined strings.
Analyzer Interface
Additional decodes are accessed via the Frame Display Options dialog box. Click the
Options button in the Capture buffer and select External.
Any available operations provided by the user-defined DLL are displayed. An optional
Setup button is available to enable the user to change various parameters in the DLL. Once
the decode is specified in this dialog box (off-line analysis), it is used for all subsequent
Capture runs (on-line and off-line).
DLL0296.65 3-1
The user-defined decode may display its output in one of several forms:
1. Add information to the capture buffer. In order to do this it is suggested that the process
return a string which can:
Replace the frame status in Summary mode.
In Partial and Full Details modes, add lines to be displayed either after the entire
frame or after the frame header (direction, timestamp, status) and before the decode
begins.
Indicate whether or not to show the program-supplied decode lines.
2. Output to an external file, printer, etc.
Functions
The function DecodeFrameNames informs the analyzer of the various types of operations
defined by the DLL. DecodeFrameSetup is called by the analyzer when the user clicks on
the Setup button. Every time a frame is received and an operation is required by the user
DLL, the function DecodeSingleFrame is called. This function may run on-line or off-line
as necessary.
3-2 DLL0296.65
DecodeFrameNames
DecodeFrameNames returns a list of all operations that may be performed on a particular
frame. The user may then select the desired operation.
Syntax
DecodeNameType* DecodeFrameNames(void* /*Reserved*/);
Parameters
Return Value
DecodeNameType* Array of structures containing name and capabilities.
The last item in the array must contain null values.
The format of DecodeFrameNames is as follows:
typedef struct {
char* decodeName;
U32 Capabilities;
} DecodeNameType
When SetupSupported is defined, the Setup button is enabled. The supported line types
specify for which line types the user-defined DLL may be called.
DLL0296.65 3-3
DecodeFrameSetup
This optional function is called when the user clicks the Setup button in the user-defined
decode dialog box. The Setup button is enabled if SetupSupported is specified in
decodeFrameNames. This function enables the user to input additional information to the
DLL.
Syntax
void DecodeFrameSetup(char* DecodeName, HWND parentWin, void*
Reserved);
Parameters
DecodeName Name of decode selected by the user.
parentWin Handle to parent window. This is used to open the Setup
dialog box.
Return Value
Nothing
3-4 DLL0296.65
DecodeSingleFrame
This function is called for each frame received by the analyzer. It is used to pass information
concerning the frame to the DLL so that the appropriate computations can be made and
returned to the analyzer.
Syntax
DecodeResult* DecodeSingleFrame(char* DecodeName, TimeStruct*
Timestamp, U16 FrameStatus, U32 FrameParameters, U16
FrameLength, U8* RawData, char* StartingProtocol, U32 Offset,
U8 DispMode, BOOL SingleProtocol, char** Decode,
U8 spareChars, void* Reserved);
Parameters
DecodeName Name of decode selected by the user.
Timestamp Pointer to a structure containing the time. Refer to
Appendix A for the format of the time structure.
FrameStatus 0 is OK. Refer to Appendix A for the status values.
FrameParameters Line type (ATM, Ethernet, HDLC), direction, etc. Refer
to Appendix A for the parameter values.
RawData Data received. For ATM transmissions, the first 8 bytes
(before the actual data) contain information about the
desired VPI, VCI and AAL type.
StartingProtocol Starting protocol, Ethernet in the following example.
DLL0296.65 3-5
Offset Offset in bits chosen by the user. The offset is 0 in the

previous example.
DispMode Display mode (0=Summary, 1=Partial, 2=Full Details).
BOOL SingleProtocol False indicates multi-protocol mode; True indicates
single-protocol mode.
Decode Text version of the decode.
spareChars Number of characters that remained in the line.
Return Value
DecodeResult* Pointer to a structure containing strings to be displayed
before and after the standard analyzer decode.
The format of decodeStrings is as follows:
typedef struct {
char**stringsBefore;
char**stringsAfter;
BOOL displayRADCOMDecode;
} DecodeResult
When displayRADCOMDecode is true, the standard analyzer decode is displayed between

stringsBefore and stringsAfter. If displayRADCOMDecode is false, only stringsBefore and
stringsAfter are displayed (if they exist).
Example
The following program decodes additional fields for the Ethernet protocol. Each section is
documented with comments designated by "//".
#include "defs.h"
#include "stdio.h"
#include "string.h"
extern "C"
{
// Structure that will hold the new decode lines created by this DLL.
DecodeResult singleFrameDecode;
3-6 DLL0296.65
// The lines for Ethernet fields decode. There will be 3 lines and the last
// item must be NIL.
char *decodeLines[4]; // Holds all the lines
char firstLine[100];
char secondLine[100];
char thirdLine[100];
// This is the array of decode names that the DLL supports.

// This array MUST be terminated by NIL name.
DecodeNameType decodeTypes[] =
{
{
"My Ethernet", // Name of the decode.
EthernetSupported // This decode is relevant only for Ethernet lines.
},
{NIL, 0}
};
// Function: DecodeFrameNames
// ==========================
// This function returns the list of names of the decode that this DLL
// Parameters:
// -----------
// ===========================================================
DecodeNameType* _export _stdcall DecodeFrameNames(void* /*reserved*/)
{
return decodeTypes;
}
// Function: DecodeFrameSetup
// ==========================
// This function is used in order to open a setup window to the user.
// In this example, the decode does not have any setup, so this function
// does nothing.
// Parameters:
// -----------
// char* decodeName - The name of the decode that should open setup window
// HWND parentWin - Parent window, to open the setup window on
// void* reserved - for later use.
// ===========================================================
DLL0296.65 3-7
void _export _stdcall DecodeFrameSetup(char* /*decodeName*/,

HWND /*parentWin*/,
void* /*reserved*/)
{
}
// Function: DecodeSingleFrame
// ===========================
// This is the main decode function. It gets the frame and all its
// parameters from the system. It also gets the decode line that the system
// already created. The function should return lines to add to the frame
// decode.
// Parameters:
// -----------
// char* decodeName - The name of the decode.
// TimeStruct* timeStamp - Time stamp of the frame.
// U16 frameStatus - Status of the frame. See appendix for options.
// U16 frameLength - Number of bytes in the frame.
// U8* rawData - The data of the frame.
// char* startingProtocol - Name of the starting protocol.
// U32 offset - Offset of the starting protocol in the frame.
// U8 dispMode - Level of details in the capture window.
// BOOL singleProtocol - Single/multi protocol in the capture window.
// char** decode - Lines of decode already created by the system.
// U8 spareChars - Number of characters left in the line (for summary mode).
// void* reserved - For later use.
// ===========================================================
DecodeResult* _export _stdcall DecodeSingleFrame(char* decodeName,
TimeStruct* timeStamp,
U16 frameStatus,
U16 frameLength,
U8* rawData,
char* startingProtocol,
U32 offset,
U8 dispMode,
BOOL singleProtocol,
char** decode,
U8 spareChars,
void* /*reserved*/)
{
// Check if this is a decode supported by this DLL.
3-8 DLL0296.65
if (strcmp(decodeName, "My Ethernet") == 0)

{
// Update the lines to be shown before the system decode,
// according to the Ethernet protocol.
sprintf(firstLine, "Destination address:
%02hX%02hX%02hX%02hX%02hX%02hX",
rawData[0],rawData[1],rawData[2],rawData[3],
rawData[4],rawData[5]);
sprintf(secondLine, "Source address:
%02hX%02hX%02hX%02hX%02hX%02hX",
rawData[6],rawData[7],rawData[8],rawData[9],
sprintf(thirdLine, "Length/Type: %02hX%02hX",
decodeLines[0] = firstLine;
decodeLines[1] = secondLine;
decodeLines[2] = thirdLine;
decodeLines[3] = NIL;
singleFrameDecode.stringsBefore = decodeLines;
// There are no lines to add after the system decode.

singleFrameDecode.stringsAfter = NIL;
// The system should show the system lines with the DLL lines
// (and not remove the original lines)
singleFrameDecode.displayRADCOMDecode = TRUE;
}
else
{
return NIL;
}
return &singleFrameDecode;
}
}
DLL0296.65 3-9
Chapter 4
Process All Frames in
Capture Buffer
Introduction
After the Capture process ends, there are instances where the entire buffer must be
processed. One such instance, which is implemented by the analyzer, is saving the
information to a file on the PC disk. Other possible applications include:
Exporting to custom formats.
Retransmission analysis (analyzing sequence numbers in a frame).
Reassembly of segmented frames (IP over X.25, ATM cells).
Station learn.
Applications which link between two or more buffers.
This DLL allows the user to perform custom operations on the contents of the Capture,
Background Record or Off-line Analysis buffers.
Analyzer Interface
DLLs which process the entire Capture buffer are accessed via the Frame Display Options
dialog box. Click the Options button in the capture buffer and select Application.
Clicking this button will open a dialog box with a list of all possible applications. A Setup
button is optionally enabled to allow the user to provide additional information to the DLL.
When the OK button is clicked in this dialog box, the entire contents of the capture buffer
are processed accordingly.
DLL0296.65 4-1
Results of this user-defined DLL may be one of the following:

Output to an external file, printer, etc.
Creation of a new window and display messages in a private window.
In both instances, the system maintains a progress window while processing the contents of
the capture buffer.
Functions
The function ProcessAllFramesNames informs the analyzer of the various types of
operations defined by the DLL. ProcessAllFramesSetup is called by the analyzer when the
user clicks on the Setup button. To process all the frames, ProcessAllFramesInit is called
once. To process each frame, ProcessFrame is called. The function ProcessAllFramesExit
is called once at the end of the processing.
ProcessAllFramesNames
ProcessAllFramesNames returns a list of all operations that may be performed on the buffer.
The user may then select the desired operation.
Syntax
ProcessNameType* ProcessAllFramesNames(void* /*Reserved*/);
Parameters
Return Value
ProcessNameType* Array of structures containing the names and
capabilities. The array is terminated with a null name.
The format of ProcessNameType is as follows:
typedef struct {
char* Name;
U32 Capabilities;
} ProcessNameType
4-2 DLL0296.65

specify for which line types the Process All Frames in Capture Buffer DLL may be called.
ProcessAllFramesSetup
This function is called when the user clicks the Setup button for a specific operation. This
Syntax
void ProcessAllFramesSetup(char* ProcessName, HWND parentWin
void* Reserved);
Parameters
ProcessName Name of operation selected by the user.
parentWin Handle to parent window. This is used to open the Setup
dialog box.
Return Value
Nothing
DLL0296.65 4-3
ProcessAllFramesInit
This function is called once at the beginning of the processing of the capture buffer. It is
used to inform the DLL that the application is about to start sending frames. The user-
defined DLL should perform all startup code in this function.
Syntax
void ProcessAllFramesInit(char* ProcessName, U32 TotalFrames,
U32 BytesPerSecond, char* windowName, HWND parentWIN, void*
Reserved);
Parameters
ProcessName Name of operation selected by the user.
TotalFrames Total number of frames.
BytesPerSecond Baud rate of the line of the capture buffer.
WindowName Title of the window from which the process is called.
parentWin Handle to parent window. This can be used in opening
child windows, dialog boxes, etc.
Return Value
Nothing
4-4 DLL0296.65
ProcessFrame
This function is called for each frame to be processed. It is used to pass information
returned.
Syntax
BOOL ProcessFrame(TimeStruct* Timestamp, U16 FrameStatus, U32
FrameParameters, U16 FrameLength, U8* RawData, void*
/*Reserved*/);
Parameters
Timestamp Pointer to a structure containing the time. Refer to
Appendix A for the format of the time structure.
FrameStatus 0 is OK. Refer to Appendix A for the status values.
FrameParameters Line type (ATM, Ethernet, HDLC), direction, etc. Refer
Return Value
BOOL When this parameter is true, no more frames are passed
to the DLL.
DLL0296.65 4-5
ProcessAllFramesExit
This function is called at the end of the processing or after an abort request has been issued.
Syntax
void ProcessAllFramesExit(void* Reserved)
Parameters
Return Value
Nothing
Example
The following program creates a file, each line being the summary decode for a frame in the
capture buffer. Each section is documented with comments designated by "//".
#include "defs.h"
#include "stdio.h"
#include "commdlg.h"
#include "string.h"
extern "C"
{
extern HANDLE dllInstance;
// Names of the user processes supported by the DLL.

ProcessNameType applicationNames[] =
{
{ "Capture buffer summary",
HDLCSupported|ATM_SAR_UNISupported
},
{NIL, 0}
};
// Hold the file name and handler.

char fileToSave[256] = {0};
FILE *framesFile = NULL;
int idx;
4-6 DLL0296.65
// Function: ProcessAllFramesNames
// ===============================
// This function returns the list of names of off-line applications that
// this DLL supports.
// This list has been created above.
// Parameters:
// -----------
// ===========================================================
ProcessNameType* _export _stdcall ProcessAllFramesNames(void* /*reserved*/)
{
return applicationNames;
}
// Function: ProcessAllFramesSetup
// ===============================
// This function is used in order to open a setup window to the user. In
// this example, it is used to get the file name from the user.
// Parameters:
// -----------
// char* processName - The name of the process that should open the setup
// window
// HWND parentWin - Parent window, to open the setup window on.
// ===========================================================
void _export _stdcall ProcessAllFramesSetup(char* processName,
HWND parentWindow,
void* /*reserved*/)
{
OPENFILENAME ofn;
char szDirName[256];
char szFile[256], szFileTitle[256];
UINT i, cbString;
char szFilter[256];
GetWindowsDirectory(szDirName, sizeof(szDirName));
szFile[0] = '\0';
// Prepare structure for the Windows' "open file" dialog.
strcpy(szFilter, "All Files (*.*)|*.*|Text Files (*.txt)|*.txt|");

int len = strlen(szFilter);
for (i=0; i < len; i++)
DLL0296.65 4-7
{
if (szFilter[i] == '|') // Each string in the buffer should end with 0
szFilter[i] = '\0';
}
memset(&ofn, 0, sizeof(OPENFILENAME));
ofn.lStructSize = sizeof(OPENFILENAME);
ofn.hwndOwner = parentWindow;
ofn.lpstrFilter = szFilter;
ofn.nFilterIndex = 1;
ofn.lpstrFile = szFile;
ofn.nMaxFile = sizeof(szFile);
ofn.lpstrFileTitle = szFileTitle;
ofn.nMaxFileTitle = sizeof(szFileTitle);
ofn.lpstrInitialDir = szDirName;
ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT | OFN_HIDEREADONLY;
// Open the dialog box and get the name of the file. Save the name
// in a global parameter.
if (GetSaveFileName(&ofn))
strcpy(fileToSave, ofn.lpstrFile);
}
// Function: ProcessAllFramesInit
// ==============================
// This function initializes local variables and prepares everything for
// the process. In this example, it opens the file of the summary.
// Parameters:
// -----------
// char* processName - The name of the process that is about to begin
// U32 totalFrames - Number of frames in the capture buffer.
// U32 bytesPerSecond - Rate of the line.
// char* windowName - The title of the window that this process started
// from.
// ===========================================================
void _export _stdcall ProcessAllFramesInit(char* processName,
U32 totalFrames,
U32 bytesPerSecond,
char* windowName,
4-8 DLL0296.65
HWND parentWindow,
void* /*reserved*/)
{
// Check if the user defined a file name.
if (fileToSave[0] == 0)
{
MessageBox(parentWindow, "No file name has been specified",
processName, MB_ICONHAND);
return;
}
idx = 0;
// Try to open the file.

framesFile = fopen(fileToSave, "w");
if (framesFile == NULL)
{
MessageBox(parentWindow, "Cannot open frames file", processName,
MB_ICONHAND);
}
}
// Function: ProcessFrame
// ======================
// This function processes one frame of the buffer. In this example it
// creates a string of descriptions of the frame and writes it to the file.
// Parameters:
// -----------
// TimeStruct* timeStamp - Time stamp of the frame.
// U16 frameStatus - Status of the frame.
// U8* rawData - Data of the frame.
// ===========================================================
BOOL _export _stdcall ProcessFrame(TimeStruct*timeStamp,
U16 frameStatus,
U16 frameLength,
U8* rawData,
void* /*reserved*/)
{
// Exit if file is not opened
DLL0296.65 4-9
if (framesFile == NULL)
return TRUE;
idx++;
// Write the frame description to the file.

fprintf(framesFile, "%d. Status: %u, Length: %u, Date: %hu/%hu/%u\n",
idx, frameStatus, frameLength, timeStamp->day, timeStamp->month,
timeStamp->year);
return FALSE;
}
// Function: ProcessAllFramesExit
// ==============================
// This function is called when the process is finished. It should close
// everything and free the memory that has been allocated for this process.
// In this example, it closes the file.
// Parameters:
// -----------
// ===========================================================
void _export _stdcall ProcessAllFramesExit(void* /*reserved*/)
{
if (framesFile)
{
fclose(framesFile);
framesFile = NULL;
}
}
4-10 DLL0296.65
Chapter 5
User-Defined Filter
Introduction
The analyzer currently defines filters on a frame-by-frame basis. Examples of such filters
are:
ATM signalling channel (VPI=0, VCI=5).
Ethernet broadcasts.
FR messages to DLCI 123 with FECN bit.
IP messages to station 192.13.14.15.
LAN Emulation data from LEC ID 0x64.
Signalling SETUP messages.
Signalling Call Reference 0x23.
A user-defined DLL which accepts a frame and determines whether it meets the filter
criteria allows:
Definition of user-defined filters.
Definition of a dynamic filter (based on external events such as database access, etc.).
Analyzer Interface
User-defined filters are accessed via the Filters dialog box. Click the New Filter
button in the Capture buffer and select External.
DLL0296.65 5-1
Clicking this button will open a dialog box with a list box containing the name of the filters
supplied by the external DLL.
The New and Delete buttons are enabled allowing creation and deletion of filters. The Edit
button will optionally open a user-defined setup window.
The user-defined filter returns a Boolean value which contains the result of the filter. It has
no output.
Functions
User-defined filters allow the user to define new filters. The user can define several filter
types. In the standard analyzer software, an example of a filter type is a string match filter,
frame status filter, etc. Individual filters are instances of the filtertype. For example, a
quick brown fox string match filter is an instance of a string match filter type.
FilterClassNames returns the various classes that are supported by the user-defined DLL.
DefaultFilterNames returns a list of hard-coded (pre-defined) filters which may exist.
These are the default filters. Since filters may be defined and perhaps not saved by the user-
defined DLL, the analyzer calls FilterExist on startup in order to verify that filters defined
in previous sessions still exist. FilterNew allows the DLL to create a new filter (instance) of
a specified filter class. FilterEdit allows the DLL to edit an existing filter. FilterDelete
informs the DLL to delete an existing filter. FilterFrame is called whenever a frame has to
be filtered.
5-2 DLL0296.65
FilterClassNames
FilterClassNames returns a list of subjects (e.g., Signalling, String Match) of user-defined
filters that are supported.
Syntax
FilterNameType* FilterClassNames(void* Reserved);
Parameters
Return Value
FilterNameType* Array of structures containing the name and capabilities
(combination of masks). The array is terminated by a
null name.
The format of FilterNameType is as follows:
typedef struct {
char*Name;
U32 Capabilities;
} FilterNameType
specify for which line types the filter may be called.
DLL0296.65 5-3
DefaultFilterNames
This function returns a list of hard-coded filters. Filters which are dynamically defined by
the user should not be returned by this function.
Syntax
FilterNameType* FilterDefaultNames(void* /*reserved*/);
Parameters
Return Value
FilterNameType* Array of structures containing the name and capabilities
(combination of masks). The array is terminated with a
null name.
The format of FilterNameType is as follows:
typedef struct {
char*Name;
U32 Capabilities;
} FilterNameType
#define ATM_Combo_UNISupported 0X00080000
When SetupSupported is defined, the Setup button is enabled for the filter. The supported
line types specify for which line types the filter may be called.
5-4 DLL0296.65
FilterExists
This function checks, on system startup, whether filters which were defined in previous
sessions still exist.
Syntax
BOOL Exist(char* Name, void* Reserved);
Parameters
Name Filter name.
Return Value
BOOL Boolean variable which is true if the filter exists.
DLL0296.65 5-5
FilterNew
This function creates a new filter.
Syntax
char* FilterNew(char* ClassName, HWND parentWin, void*
Reserved);
Parameters
ClassName Filter class name.
parentWin Handle to parent window. This is used to open a dialog
box for new filter definition.
Return Value
char* Name of the user-defined filter. Null if no filter is
defined.
5-6 DLL0296.65
FilterEdit
This function edits an existing filter.
Syntax
char* FilterEdit(char* FilterName, HWND parentWin, void*
Reserved);
Parameters
FilterName Name of filter to be edited.
parentWin Handle to parent window. This is used to open a dialog
box for filter editing.
Return Value
char* If this name is different than the name passed as the
parameter, a new filter is created with this name, but the
old filter is maintained.
DLL0296.65 5-7
FilterDelete
This function deletes an existing filter.
Syntax
BOOL FilterDelete(char* FilterName, void* Reserved);
Parameters
FilterName Name of filter to be deleted.
Return Value
BOOL Boolean value which is true if the delete operation is
legal and was executed; false otherwise. If false, the
filter is not removed from the filter list.
5-8 DLL0296.65
FilterFrame
This function is called for each frame to be processed. It is used to determine if the filter
passes the filter criteria or not.
Syntax
BOOL FilterFrame(char* FilterName, TimeStruct* Timestamp, U16
FrameStatus, U32 FrameParameters, U16 FrameLength, U8*
RawData, void* Reserved);
Parameters
FilterName Name of the filter to be executed.
Timestamp Pointer to a structure containing the time.
FrameStatus 0 is OK.
FrameParameters Line type (ATM, Ethernet, HDLC), direction, etc.
Return Value
BOOL Boolean value which is true if the frame matches the
filter definition.
Example
The following program creates a filter based on the length of the frame by matching frames
between the given minimum and maximum length values. In addition, this example provides
two default filters for offset+data. Each section is documented with comments designated by
"//".
#include "defs.h"
#include "stdio.h"
#include "string.h"
#include "filter.rh"
#include <stdlib.h>
extern "C"
{
DLL0296.65 5-9
#define DLG_CANCEL 0
#define DLG_OK 1
#define NAME_LEN 50
#define MAX_FILTERS_NUM 10
// Names of default filters that will be added to the system at

// the beginning.
#define OFFSET_0_DATA_FF "Offset 0 data FF"
#define OFFSET_0_DATA_09 "Offset 0 data 09"
LONG FAR PASCAL FilterDialog(HWND hWnd, WORD wMsg, WPARAM wParam, LPARAM
lParam);

char filterNameBuf[NAME_LEN];
// List of all the filters defined by the user.

struct LengthFilterParams
{
char name[NAME_LEN];
int fromLength;
int toLength;
};
LengthFilterParams lengthFiltersList[MAX_FILTERS_NUM] = {0};
LengthFilterParams newFilter;
int numOfFilters = 0;
// List of filter names and types that are supported by this DLL.
FilterNameType filterNamesList[] =
{
{ "Length Filter", 0xFFFFFFFF },
{ NIL, 0 }
};
FilterNameType defaultNamesList[] =
{
{ OFFSET_0_DATA_FF, 0xFFFFFFFF },
{ OFFSET_0_DATA_09, 0xFFFFFFFF },
{ NIL, 0 }
};
5-10 DLL0296.65
// Function: FilterClassNames
// ==========================
// This function returns the list of names of filters that this DLL
// Parameters:
// -----------
// ===========================================================
FilterNameType* _export _stdcall FilterClassNames(void* /*reserved*/)
{
return filterNamesList;
}
// Function: FilterDefaultNames
// ============================
// This function returns the list of names of default filters that this DLL
// Parameters:
// -----------
// ===========================================================
FilterNameType* _export _stdcall FilterDefaultNames(void* /*reserved*/)
{
return defaultNamesList;
}
// Function: FilterExists
// ======================
// This function gets a name of a filter and returns if this filter is
// supported by the DLL or not. It can be a regular filter or a default
//filter. This function is used when the system is loaded and only
// the supported filters are shown in the list.
// Parameters:
// -----------
// char* name - The name of the filter.
// ===========================================================
BOOL _export _stdcall FilterExists(char *name,
void* /*reserved*/)
{
if ( strcmp(OFFSET_0_DATA_FF, name) == 0 )
return TRUE;
if ( strcmp(OFFSET_0_DATA_09, name) == 0 )
DLL0296.65 5-11
return TRUE;
for (int i=0; i < numOfFilters; i++)

{
if (strcmp(name, lengthFiltersList[i].name) == 0)
return TRUE;
}
return FALSE;
}
// Function: FilterNew
// ===================
// This function is called when the user tries to create a new filter from
// a class supported by this DLL. The DLL should open a dialog window in
// order to get the parameters of the filter. In this case, there is a
// dialog box that gets the required minimum and maximum length of the
//frames.
// The function returns the name of the created filter.
// Parameters:
// -----------
// char* className - The name of the class. This parameter is used when
// more then one class is supported by the DLL.
// HWND parentWin - parent window, for the dialog window.
// ===========================================================
char* _export _stdcall FilterNew(char *className,
HWND parentWin,
void* /*reserved*/)
{
if (numOfFilters == MAX_FILTERS_NUM)
return NIL;
newFilter.name[0] = 0;
// Open a dialog box in order to get the parameters from the user.
int retDlg = DialogBoxParam(dllInstance, "LENGTH_FILTER", parentWin,
(FARPROC)FilterDialog, (LPARAM)&newFilter);
if (retDlg == DLG_OK) {
lengthFiltersList[numOfFilters] = newFilter;
numOfFilters++;
return lengthFiltersList[numOfFilters-1].name;
}
5-12 DLL0296.65
return NULL;
}
// Function: FilterEdit
// ====================
// This function is called when the user tries to edit an existing filter.
// The DLL should open a dialog box in order to let the user change
// the parameters of the filter.
// The function returns the name of the filter. It will be the same
// name or a new name.
// Parameters:
// -----------
// char* filterName - The name of the filter.
// HWND parentWin - parent window, for the dialog window.
// ===========================================================
char* _export _stdcall FilterEdit(char *filterName,
HWND parentWin,
void* /*reserved*/)
{
strcpy(filterNameBuf, filterName);
// Show the description of the default filters.

if ( strcmp(OFFSET_0_DATA_FF, filterName) == 0 )
{
MessageBox(parentWin, "Filter for data FF in offset 0", "Edit
Filter", MB_ICONHAND);
return filterNameBuf;
}
if ( strcmp(OFFSET_0_DATA_09, filterName) == 0 )
{
MessageBox(parentWin, "Filter for data 09 in offset 0", "Edit
Filter", MB_ICONHAND);
}
// Open dialog box in order to edit the filter.

{
if (strcmp(filterName, lengthFiltersList[i].name) == 0)
{
newFilter = lengthFiltersList[i];
DLL0296.65 5-13
int retDlg = DialogBoxParam(dllInstance, "LENGTH_FILTER",

parentWin,
(FARPROC)FilterDialog, (LPARAM)&newFilter);
if (retDlg == DLG_OK) {
if (strcmp(filterNameBuf, newFilter.name) != 0)
{
lengthFiltersList[numOfFilters] = newFilter;
numOfFilters++;
return lengthFiltersList[numOfFilters-1].name;
}
}
break;
}
}
}
// Function: FilterDelete
// ======================
// This function is called when the user tries to delete an existing filter.
// The DLL should delete it from the internal list.
// The function is True on success, False otherwise.
// Parameters:
// -----------
// ==============================================================
BOOL _export _stdcall FilterDelete(char *filterName,
void* /*reserved*/)
{
// Default filter cannot be deleted.
if ( strcmp(OFFSET_0_DATA_FF, filterName) == 0 )
{
MessageBox(NIL, "Cannot delete this filter", "Delete Filter",
MB_ICONHAND);
return FALSE;
}
if ( strcmp(OFFSET_0_DATA_09, filterName) == 0 )
{
MessageBox(NIL, "Cannot delete this filter", "Delete Filter",
MB_ICONHAND);
return FALSE;
}
5-14 DLL0296.65
// Delete the filter from the list.

{
if (strcmp(filterName, lengthFiltersList[i].name) == 0)
{
for (int j=i+1; j < numOfFilters; j++)
lengthFiltersList[j-1] = lengthFiltersList[j];
numOfFilters--;
break;
}
}
return TRUE;
}
// Function: FilterFrame
// =====================
// This function is the main function of the filter. It gets a frame and
// checks if the frame matches the condition of the filter or not. It
// returns True if it does.
// Parameters:
// -----------
// TimeStruct* timeStamp - The time the frame was captured.
// U16 frameStatus - Status of the frame.
// U16 frameLength - Length of the frame, in bytes.
// U8* rawData - Buffer of the frame data.
// ==============================================================
BOOL _export _stdcall FilterFrame(char* filterName,
TimeStruct* timeStamp,
U16 frameStatus,
U16 frameLength,
U8* rawData,
void* /*reserved*/)
{
// The default filters are pattern match filter. Check the data at
// the specified offset.
if ( strncmp(filterName, OFFSET_0_DATA_FF, strlen(OFFSET_0_DATA_FF)) ==
0 )
DLL0296.65 5-15
{
if (rawData[8] == 0xFF)
return TRUE;
}
if ( strncmp(filterName, OFFSET_0_DATA_09, strlen(OFFSET_0_DATA_09)) ==
0 )
{
if (rawData[8] == 0x9)
return TRUE;
}
// For length filter, check the length of the frame.

{
if ( strcmp(lengthFiltersList[i].name, filterName) == 0 )
if ( (frameLength > lengthFiltersList[i].fromLength) &&
(frameLength < lengthFiltersList[i].toLength) )
return TRUE;
}
return FALSE;
}
// Function for initializing the dialog window

void InitDialog(HWND hWnd, LengthFilterParams* filterPrms)
{
if (filterPrms->name[0] != 0){
// The name is not empty: edit an existing filter.

char length[10];
// Update the parameters of the filter in the dialog box.

HWND controlHwnd = GetDlgItem(hWnd, EDIT_NAME);
SendMessage(controlHwnd, WM_SETTEXT, 0, (LPARAM)filterPrms->name);
itoa(filterPrms->fromLength, length, 10/*radix*/);

controlHwnd = GetDlgItem(hWnd, EDIT_FROM);
SendMessage(controlHwnd, WM_SETTEXT, 0, (LPARAM)length);
itoa(filterPrms->toLength, length, 10/*radix*/);

controlHwnd = GetDlgItem(hWnd, EDIT_TO);
SendMessage(controlHwnd, WM_SETTEXT, 10, (LPARAM)length);
}
5-16 DLL0296.65
SetWindowLong(hWnd, DWL_USER, (LPARAM)filterPrms);

}
// Function for getting the parameters from the dialog window.

void SaveFilterOptions(HWND hWnd)
{
char length[10];
LengthFilterParams* newFilter =
(LengthFilterParams*)GetWindowLong(hWnd, DWL_USER);
if (newFilter)
{
// Save the parameters defined by the user to a temporary
// structure.
HWND controlHwnd = GetDlgItem(hWnd, EDIT_NAME);
SendMessage(controlHwnd, WM_GETTEXT, NAME_LEN, (LPARAM)newFilter-
>name);
controlHwnd = GetDlgItem(hWnd, EDIT_FROM);

SendMessage(controlHwnd, WM_GETTEXT, 10, (LPARAM)length);
newFilter->fromLength = atoi(length);
controlHwnd = GetDlgItem(hWnd, EDIT_TO);

SendMessage(controlHwnd, WM_GETTEXT, 10, (LPARAM)length);
newFilter->toLength = atoi(length);
}
}
// Messages function of the dialog window.

LONG FAR PASCAL FilterDialog(HWND hWnd, WORD wMsg, WPARAM wParam, LPARAM
lParam)
{
// process the message
switch( wMsg )
{
// process command from one of the child controls
case WM_COMMAND:
switch(wParam)
{
// OK or cancel, so end the dialog.
case IDOK:
{
SaveFilterOptions(hWnd);
DLL0296.65 5-17
EndDialog(hWnd, DLG_OK);
break;
}
case IDCANCEL:
{
EndDialog(hWnd, DLG_CANCEL);
break;
}
}
break;
// Initialize the dialog.

case WM_INITDIALOG:
InitDialog(hWnd, (LengthFilterParams*)lParam);
return FALSE;
}
return FALSE;
}
// Save the list of the filters in the INI file.

void SaveFilters(char* dirName)
{
char field[50], txt[50], fileName[50];
// Prepare the file name (including the full path).

sprintf(fileName, "%s\\ex_fil.ini", dirName);
itoa(numOfFilters, txt, 10);

WritePrivateProfileString("Filters", "FiltersNum", txt, fileName);
{
sprintf(field, "name%d", i);
WritePrivateProfileString("Filters", field,
lengthFiltersList[i].name, fileName);
sprintf(field, "from%d", i);

itoa(lengthFiltersList[i].fromLength, txt, 10);
WritePrivateProfileString("Filters", field, txt, fileName);
sprintf(field, "to%d", i);

itoa(lengthFiltersList[i].toLength, txt, 10);
WritePrivateProfileString("Filters", field, txt, fileName);
5-18 DLL0296.65
}
}
// Read the list of the filters from the INI file.

void LoadFilters(char* dirName)
{
char field[50], txt[50], fileName[50];
// Prepare the file name (including the full path).

sprintf(fileName, "%s\\ex_fil.ini", dirName);
numOfFilters = GetPrivateProfileInt("Filters", "FiltersNum", 0,

fileName);
{
sprintf(field, "name%d", i);
GetPrivateProfileString("Filters", field, "",
lengthFiltersList[i].name, 50, fileName);

sprintf(field, "from%d", i);
GetPrivateProfileString("Filters", field, "", txt, 50, fileName);
lengthFiltersList[i].fromLength = atoi(txt);
sprintf(field, "to%d", i);

GetPrivateProfileString("Filters", field, "", txt, 50, fileName);
lengthFiltersList[i].toLength = atoi(txt);
}
}
} // extern "C"
/***************************************************************************
*
filter.rc
produced by Borland Resource Workshop
****************************************************************************
*/
#include "filter.rh"
LENGTH_FILTER DIALOG 70, 63, 194, 104
STYLE DS_MODALFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU
DLL0296.65 5-19
CAPTION "Frame Length Filter"

FONT 8, "MS Sans Serif"
{
DEFPUSHBUTTON "OK", IDOK, 22, 84, 50, 14
PUSHBUTTON "Cancel", IDCANCEL, 121, 84, 50, 14
EDITTEXT EDIT_NAME, 62, 6, 117, 12
EDITTEXT EDIT_FROM, 60, 36, 42, 12
EDITTEXT EDIT_TO, 60, 56, 42, 12
LTEXT "Filter name:", -1, 12, 6, 45, 8
LTEXT "From length:", -1, 12, 36, 45, 8
LTEXT "To length:", -1, 12, 56, 45, 8
LTEXT "bytes", -1, 108, 36, 45, 8
LTEXT "bytes", -1, 108, 56, 45, 8
}
/***************************************************************************
*
filter.rh
produced by Borland Resource Workshop
****************************************************************************
*/
#define EDIT_FROM 102

#define EDIT_TO 103
#define EDIT_NAME 101
5-20 DLL0296.65
Chapter 6
Background Record
Introduction
The Background Record process saves the captured frames to the hard disk. DLLs can be
created which will perform various processes on these frames while they are being saved to
the disk. It is also possible to use a DLL to cancel the save to disk option and replace it with
any other required operation. Possible applications include:
Export to custom formats.
On-line analysis.
Reassembly of segmented frames (IP over X.25, ATM cells).
Station learn.
Analyzer Interface
These DLLs are accessed using the Setup dialog box of the Background Record process.
DLL0296.65 6-1
The Application drop-down list in this dialog box provides the user with a list of all
available applications. The default selection is none. Selecting none also cancels the last
application chosen. The Setup button allows the user to provide additional information to
the DLL. This button is enabled or disabled according to the application selected.
When a DLL application is selected, the Save to disk checkbox becomes active. Check this
box to save to disk. After choosing an application the application name is saved with the
process parameters.
Click the OK button in this dialog box, and then the Go button in the Background Record
window to start the process.
Results of this user-defined DLL may be one of the following:
Output to an external file, printer, etc.
Creation of a new window and display messages in a private window.
Functions
The function OLProcessFramesNames informs the analyzer of the various types of
operations defined by the DLL. OLProcessFramesSetup is called by the analyzer when the
user clicks on the Setup button. To process all the frames, OLProcessFramesInit is called
once. To process each frame, OLProcessFrame is called. The function ProcessFramesExit
is called once at the end of the processing.
OLProcessFramesNames
OLProcessFramesNames returns a list of all operations that may be performed on the buffer.
The user may then select the desired operation.
Syntax
OLProcessNameType* OLProcessFramesNames (void* Reserved);
6-2 DLL0296.65
Parameters
void* Reserved For future use.
Return Value
OLProcessNameType* Array of structures containing the operation names. The
array is terminated with a null string.
The format of the structure is as follows:
typedef struct
{
char* processName;
U32 Capabilities;
}OLProcessNameType
DLL0296.65 6-3
OLProcessFramesSetup
This function is called when the user clicks the Setup button for a specific operation. This
Syntax
void OLProcessFramesSetup (char* ProcessName, HWND ParentWin,
U8 channelNum, void* Reserved);
Parameters
char* ProcessName Name of operation selected from the array received by
OLProcessFramesNames.
HWND parentWin Handle to parent window. This is used to open the Setup
dialog box.
U8 channelNum The number of the channel the process is running on.
void *Reserved For future use.
Return Value
Nothing
6-4 DLL0296.65
OLProcessFramesInit
This function is called once at the beginning of the process to inform the DLL that the
application is about to start sending frames. The user-defined DLL should perform all
startup codes in this function.
Syntax
BOOL OLProcessFramesInit(char *ProcessName, U32
BytesPerSecond, HWND parentWin, U8 portNumber, char*
protocolsFileName, void *Reserved);
Parameters
char *ProcessName Name of operation selected, out of the array received by
OLProcessFramesNames.
U32 BytesPerSecond Baud rate of the line.
HWND parentWin Handle to parent window. This can be used in opening
child windows, dialog boxes, etc.
U8 channelNumber The number of the channel the process is running on.
char* The name of the file containing the names and identity
protocolsFileName numbers of the protocol. The protocol file contains
structures of 32 bytes. 2 bytes of protocols ID; 30 bytes of
protocol name.
Return Value
BOOL Indicates if the process can be started.
DLL0296.65 6-5
OLProcessFrame
This function is called for each frame to be processed. It is used to pass information
returned.
Syntax
void OLProcessFrame (TimeStruct* Timestamp, U16 FrameStatus,
U32 FrameParameters, U16 FrameLength, U8* RawData, U8
protocolMapSize, ProtocolStruct* protocolMap, U8 portNumber,
void *Reserved);
Parameters
TimeStruct* Pointer to a structure containing the time. Refer to
Timestamp Appendix A for the format of the time structure.
U16 FrameStatus 0 is OK. Refer to Appendix A for the status values.
U32 FrameParameters Line type (ATM, Ethernet, HDLC), direction, etc. Refer
U16 FrameLength Frame length in bytes.
U8* RawData Data received. For ATM transmissions, the first 8 bytes
desired VPI, VCI and AAL type (refer to appendix;
Frame header structure).
U8 protocolMapSize Number of protocols in this frame.
ProtocolStruct* List of protocols in the frame, including the offset of
protocolMap each protocol.
U8 portNumber The number of the channel this process is running on.
Return Value
Nothing
The format of ProtocolStruct* ProtocolMap is as follows:
typedef struct
{
U16 ProtocolId;
S32 ProtocolOffset;
}ProtocolStruct;
6-6 DLL0296.65
OLProcessFramesExit
This function is called at the end of the processing.
Syntax
void OLProcessFramesExit (U8 PortNumber, void *Reserved);
Parameters
U8 portNumber The number of the channel the process is running on.
Return Value
Nothing
Example
The following program creates a file, each line being the summary decode for a frame in the
capture buffer. Each section is documented with comments designated by "//".
#include "defs.h"
#include "stdio.h"
#include "commdlg.h"
#include "string.h"
#ifdef _WIN32_
#define DLL_FUNCTION _stdcall
#else
#define DLL_FUNCTION _pascal
#endif
extern "C"
{
typedef struct
{ // structure for captured item time
U16 year;
U8 month;
U8 day;
U32 seconds;
U32 microSeconds;
} TimeStruct;
DLL0296.65 6-7
typedef struct
{ // structure that represents one on-line process type.
char* ProcessName;
U32 capabilities;
} OLProcessNameType;
typedef struct
{// structure for protocols
U16 protocolId;
S32 protocolOffset;
}ProtocolStruct;
// Names of the user processes supported by the DLL.

OLProcessNameType olApplicationNames[] =
{
{ "My Application",
AllLineTypesSupported|SetupSupported
},
{ "Your Application",
AllLineTypesSupported
},
{NIL, 0}
};
// Hold the file name and handler.

char fileNameToSave[256] = {0};
FILE *frameFile = NULL;
char protocolsIdsFileName[256] = {0};
FILE *protocolsFile = NULL;
int indx;
int testCounter = 0;
// Function: OnLineProcessFramesNames
// ===================================
// This function returns the list of names of on-line applications that
// this DLL supports.
// Parameters:
// -----------
6-8 DLL0296.65
//
==========================================================================
OLProcessNameType* _export DLL_FUNCTION OLProcessFramesNames(void*
/*reserved*/)
{
return olApplicationNames;
}
// Function: OnLineProcessFramesSetup
// ===================================
// This function is used in order to open a setup window to the user. In
// this example, it is used to open the browser for choosing a file.
// Parameters:
// -----------
// char* processName - The name of the process that should open the setup
// window.
// U8 portNumber - The number of the channel this process is running
// on.
// void* reserved - for future use.
//
==========================================================================
void _export DLL_FUNCTION OLProcessFramesSetup(char* processName,

HWND parentWindow,
U8 portNumber,
void* )
{
OPENFILENAME ofn;
char szDirName[256];
char szFile[256], szFileTitle[256];
UINT i, cbString;
char szFilter[256];
GetWindowsDirectory(szDirName, sizeof(szDirName));
szFile[0] = '\0';
// Prepare structure for the Windows' "open file" dialog.
strcpy(szFilter, "All Files (*.*)|*.*|Text Files (*.txt)|*.txt|");

int len = strlen(szFilter);
DLL0296.65 6-9
for (i=0; i < len; i++)

{
if (szFilter[i] == '|') // Each string in the buffer should end
//with 0
szFilter[i] = '\0';
}
memset(&ofn, 0, sizeof(OPENFILENAME));
ofn.lStructSize = sizeof(OPENFILENAME);
ofn.hwndOwner = parentWindow;
ofn.lpstrFilter = szFilter;
ofn.nFilterIndex = 1;
ofn.lpstrFile = szFile;
ofn.nMaxFile = sizeof(szFile);
ofn.lpstrFileTitle = szFileTitle;
ofn.nMaxFileTitle = sizeof(szFileTitle);
ofn.lpstrInitialDir = szDirName;
ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT | OFN_HIDEREADONLY;
// Open the dialog box and get the name of the file. Save the name
// as a global parameter.
if (GetSaveFileName(&ofn))
strcpy(fileNameToSave, ofn.lpstrFile);
// Function: OnLineProcessFramesInit
// ===================================
// This function initializes local variables and prepares everything for
// the process. In this example, it opens the file for the summary.
// Parameters:
// -----------
// char* processName - The name of the process that is about to begin.
// U32 bytesPerSecond - Rate of the line.
// U8 portNumber - The number of the channel this process is
// running on.
// char* protocolsFileName - The name of the file containing names and
// id's of protocols.
// returns:
6-10 DLL0296.65
//---------
// Bool - indicates if the process can be started.
//
==========================================================================
BOOL _export DLL_FUNCTION OLProcessFramesInit(char* processName,
U32 bytesPerSecond,
HWND parentWindow,
U8 portNumber,
char* protocolsFileName,
void* /*reserved*/)
{
strcpy(protocolsIdsFileName, protocolsFileName);
// Check if the user defined a file name.

if (fileNameToSave[0] == 0)
{
MessageBox(parentWindow, "No file name has been specified",
processName, MB_ICONHAND);
return FALSE;
}
indx = 0;
// Try to open the file.

frameFile = fopen(fileNameToSave, "w");
if (frameFile == NULL)
{
MessageBox(parentWindow, "Cannot open frames file", processName,
MB_ICONHAND);
}
return TRUE;
}
// Function: OnLineProcessFrame
// ============================
// This function processes one frame.
// In this example it prepares a summary of the frame and writes it to the
// file.
// For each frame it writes the status, length, date, protocolMapSize,
//channelNumber and the list of the protocols that are in the frame.
DLL0296.65 6-11
// Parameters:
// -----------
// TimeStruct* timeStamp - Time stamp of the frame
// U16 frameStatus - Status of the frame. See appendix for
// options.
// U8* rawData - The data of the frame.
// U8 protocolMapSize - Number of protocols in this frame.
// ProtocolStruct* protocolMap - List of protocols in the frame, including
// the offset.
// U8 portNumber - The number of the channel this process
// is running on.
//
==========================================================================
void _export DLL_FUNCTION OLProcessFrame(TimeStruct* timeStamp,
U16 frameStatus,
U16 frameLength,
U8* rawData,
U8 protocolMapSize,
ProtocolStruct* protocolMap,
U8 portNumber,
void* /*reserved*/)
{
// Exit if file is not opened

if (frameFile == NULL)
return ;
protocolsFile = fopen(protocolsIdsFileName, "rb");
if (protocolsFile == NULL)
{
MessageBox(NULL, "Cannot open 'protocols.ids' file", "UDD Frame",
MB_ICONHAND);
}
indx++;
U16 idPrtcl;
6-12 DLL0296.65
char protocolName[30];
unsigned prtclFile;
// Write the frame description to the file.

fprintf(frameFile, "%d. Status: %u, Length: %u, Date: %hu/%hu/%u\n",
indx, frameStatus, frameLength, timeStamp->day, timeStamp-
>month, timeStamp->year);
fprintf(frameFile, " ProtocolMapSize : %u, portNumber: %u\n",

protocolMapSize, portNumber );
for (int i=0; i<protocolMapSize; i++)
{
prtclFile = 1;
fseek(protocolsFile, 0L, SEEK_SET);
while ((protocolMap[i].protocolId != idPrtcl) && prtclFile)
{
prtclFile = fread(&idPrtcl,sizeof(U16),1,protocolsFile);
prtclFile =
fread(protocolName,sizeof(protocolName),1,protocolsFile);
}
if (protocolMap[i].protocolId == idPrtcl)
fprintf(frameFile, " %d ==> protocolId = %d ,
protocolOffset = %ld Name = %s\n",
i, protocolMap[i].protocolId,
protocolMap[i].protocolOffset,protocolName );
else
fprintf(frameFile, " %d ==> protocolId = %d ,
protocolOffset = %ld Name = NOT FOUND!!\n",
i, protocolMap[i].protocolId,
protocolMap[i].protocolOffset);
}
fclose(protocolsFile);
return;
}
// Function: OLProcessFramesExit
// ==============================
// This function is called when the process is finished. It should close
// everything and free the memory that has been allocated for this process.
// In this example, it closes the summary file.
// Parameters:
DLL0296.65 6-13
// -----------
// U8 portNumber - The number of the channel this process is running on.
// void* reserved - for future use.
//
==========================================================================
void _export DLL_FUNCTION OLProcessFramesExit(U8 portNumber,
void* /*reserved*/)
{
if (frameFile)
{
fclose(frameFile);
frameFile = NULL;
}
}
6-14 DLL0296.65
Chapter 7
Link to Live Analysis Data
Introduction
Various real-time analyses are performed by the analyzer today. The Link to Live Analysis
Data external DLL allows the user to receive the analysis data as it is displayed on the
screen.
This enables the user to perform applications such as:
Generation of various reports.
Generation of graphical analyses and performing various calculations on them.
Historical recording of analysis data.
Creation of links between the analysis and other processes (e.g. you can display in the
Capture buffer more than 10% erroneous frames).
Analyzer Interface
Access the Link to Live Analysis applications from the analysis process setup dialog box.
Click the External button in the Analysis setup dialog box. When there is no external DLL
this button is not active.
DLL0296.65 7-1
The External Analysis dialog box is displayed with a list of available analysis programs.
Click on the required program and click the OK button. Click the OK button in the Analysis
setup dialog box and then click the Go button in the analysis window.
7-2 DLL0296.65
Functions
Analyses are grouped into subjects (e.g., Ethernet). Each subject has its associated analyses
(e.g., Network Traffic Activity Pairs) and a short description (Use this analysis to view
network traffic activity between pairs or nodes.). Use the user defined DLL to perform
custom operations on on-line analyses. The function AnalysisLinkNames gives a list of the
possible operations provided by the user. AnalysisLinkSetup is called by the analyzer if the
user clicks on the Setup button in the Analysis dialog box. AnalysisLinkStarted informs
the DLL that the analysis has started. AnalyzeLinkResults reports the analysis data as it is
displayed on the screen and AnalysisLinkStopped responds to the user stopping the
analysis process.
AnalysisLinkNames
AnalysisLinkNames returns names of links which can receive analyses to be displayed in the
Analysis setup dialog box.
Syntax
OLAnalyzNameType* AnalysisLinkNames (void* reserved);
Parameters
Return Value
OLAnalyzNameType* Array of structures containing null-terminated strings showing
the analysis names and capabilities. The last item in the array
must contain a null string.
The structure of the OLAnalyznameType is as follows:
typedef struct
{
char* name;
U32 capabilities;
}OLAnalyzNameType;
DLL0296.65 7-3

7-4 DLL0296.65
AnalysisLinkSetup
This function is called when the user clicks the Setup button in the Analysis dialog box.
Syntax
void AnalysisLinkSetup (char *LinkName, HWND Parent, Int
channelNum, void *Reserved);
Parameters
char *LinkName The name of the link selected from the array received by
AnalysisLinkNames.
HWND Parent Handle for the parent window that opens setup. This can be used
in opening child windows, dialog boxes, etc.
Return Value
nothing
DLL0296.65 7-5
AnalysisLinkStarted
AnalysisLinkStarted is called when the analysis has started.
Syntax
void AnalysisLinkStarted (char *LinkName, char *Subject, char
*Analysis, char *Filter, U8 Units, U8 Calculation, U8 Yaxis,
U8 GraphicDisplay, U32 channelNum, void *Reserved);
Parameters
char *LinkName Name of the link selected from the array received by
AnalysisLinkNames.
char *Subject Subject chosen by the user in the Analysis setup dialog box.
char *Analysis Analysis chosen by the user in the Analysis setup dialog box.
char *Filter Name of the analysis filter chosen by the user.
U8 Units User choice for analysis units; 0 for frames or 1 for bytes.
U8 Calculation User choice for calculation; 0 for average, 1 for per cycle or 2
for total.
U8 Yaxis User choice for Y-axis display; 0 for value or 1 for percent.
U8 User choice for graphic display; 0 for pie or 1 for bar.
GraphicDisplay
Return Value
Nothing
7-6 DLL0296.65
AnalysisLinkResults
Called every time analysis data is updated on the screen.
Syntax
void AnalysisLinkResult (void *Results, U32 numElements, U32
Parameters
void *Results Array of results of whose type differs from one control (e.g.
pie/bar) to another thus declared as (void*).
U32 numElements Number of items in the above array.
Return Value
Nothing
DLL0296.65 7-7
AnalysisLinkStopped
This function informs the DLL that the user has pressed the Stop button.
Syntax
void AnalysisLinkStopped (U32 channelNum, void* Reserved);
Parameters
Return Value
Nothing
Example
The following program creates a file, with the results of the analysis. Each section is
#include <windows.h>
#include "defs.h"
#include <stdio.h>
#include <commdlg.h>
#include <string.h>
#include <dir.h>
#define MAX_COL 11
#define NO_ADDR 2
#define MaxItemTitleLen 30
#define MAX_MAT 10
extern "C"
{
char anlzName[80];
// Names of the analysis processes supported by the DLL.

OLAnalzNameType analzTypes[] =
{
{
"Analysis report", //The name of the analysis
},
{NIL, 0}
7-8 DLL0296.65
};
// Structures for the analysis results (depends on the type of analysis)
// for numeric analysis

typedef struct _Row
{
S32 rowVal ;
U32 col[MAX_COL] ;
} Row;
// for pairs analysis for user defined dll (avoiding U64 type)
typedef struct _UDDDblPairsRow
{
U32 addrHigh[NO_ADDR] ;
U32 addrLow[NO_ADDR] ;
double val[NO_ADDR] ;
double sum[NO_ADDR] ;
char descr[NO_ADDR][16] ;
} UDDDblPairsRow;
// for user-defined live analysis

typedef struct _SendUserDLLResults
{
char name[MaxItemTitleLen] ;
float val ;
} SendUserDLLResults;
// for user-defined live cross analysis

typedef struct _UDDCrossRow
{
char name[MaxItemTitleLen];
double val[MAX_MAT] ;
} UDDCrossRow;
// Hold the file handlers.

HFILE theFile[MaxChannelsNum];
char Name[80];
int counter;
DLL0296.65 7-9
// Function: AnalysisLinkNames
// ===========================
// This function returns the list of names of analysis applications that
//this DLL supports.
// Parameters:
// -----------
//
==========================================================================
OLAnalzNameType* _export _stdcall AnalysisLinkNames(void* /*reserved*/)
{
return analzTypes;
}
// Function: AnalysisLinkSetup
// ===========================
// This function is used in order to open a setup window for the user. In
//this example, the setup window is not used, so this function does nothing.
// Parameters:
// -----------
// char* AnalysisName - The name of the process that should open the setup
//dialog box.
// HWND parentWin - Parent window, to open the setup dialog box on.
// U32 channelNum - The number of the channel that runs the analysis
//process.
//
==========================================================================
void _export _stdcall AnalysisLinkSetup(char* /*AnalysisName*/,
HWND /*parentWin*/,
U32 /*channel Num */,
void* /*reserved*/)
{
}
// Function: AnalysisLinkStarted
7-10 DLL0296.65
// =============================
// This function is called when the analysis process starts. The DLL
//should initialize local variables and prepare everything for the
//process.
// In this example, it creates a directory and opens the summary file.
// Parameters:
// -----------
// char* Name - The name of the DLL process that is about to begin.
// char* Subject - The subject of the analysis process.
// char* Analysis - The analysis process that is running.
// char *Filter - The name of the filter that is in use in the analysis
//process.
// U8 Units - The units that are used in the analysis process
(frames/bytes).
// U8 Calculation - The type of calculation that is done in the analysis
//process (per cycle/history/average).
// U8 Yaxis - (value over total/percent/value).
// U8 GraphicDisplay - The display type(bar/pie).
// U32 Chnl - The number of the channel that runs the analysis process.
//
==========================================================================
void _export _stdcall AnalysisLinkStarted(char* Name,
char * Subject,
char * Analysis,
char * Filter,
U8 Units,
U8 Calculation,
U8 Yaxis,
U8 GraphicDisplay,
U32 Chnl /*channel num */,
void* /*reserved*/)
{
counter = 1;
char st2[80];
char st[200];
mkdir("c:\\uddtemp");
sprintf(st2,"c:\\uddtemp\\Analz%d.txt",Chnl+1);
strcpy(anlzName,Analysis);
if ((theFile[Chnl]=_lcreat(st2,0))==HFILE_ERROR)
DLL0296.65 7-11
::MessageBox(0,"external analysis creat failed!!","Error!!",MB_OK);

_lwrite(theFile[Chnl],"\n",1);
sprintf(st,"Name:%s Subject:%s Analysis:%s Filter:%s Options:%hu-%hu-%hu-
%hu ",Name,Subject,Analysis,Filter,
Units,Calculation,Yaxis,GraphicDisplay);
_lwrite(theFile[Chnl],st,strlen(st));
}
// Function: AnalysisLinkResults
// =============================
// This function processes one message of analysis results. The type of the
// results depends on the analysis type. In this example it saves all the
// results in the file of this channel.
// Parameters:
// -----------
// LnsResult* Result - Array of results for the last period.
// U32 numElements - Number of elements in the results array.
// U32 Chnl - The number of the channel that runs the Analysis process.
//
==========================================================================
void _export _stdcall AnalysisLinkResults(
void *Result,
U32 numElements,
U32 Chnl /*channelNum */,
void* /*reserved/)
{
char st[200],st2[200];
sprintf(st,"**************** %d ***************\n",counter);
if (!strncmp(anlzName,"Overall Station Activity (3D)",29)) {

UDDCrossRow *uddCrossRow=(UDDCrossRow *) Result;
for (U32 i=0;i<numElements;i++) {
sprintf(st,"Name: %s Values: ",uddCrossRow[i].name);
for (U32 j=0;j<numElements;j++) {
7-12 DLL0296.65
sprintf(st,"%f, ",uddCrossRow[i].val[j]);
}
}
}
if (!strncmp(anlzName,"Frame Direction Distribution (tabular)",38) ||

!strncmp(anlzName,"Protocol Distribution (tabular format)",26)) {
Row *row=(Row *) Result;
for (U32 i=1;i<numElements+1;i++) {
sprintf(st,"rowVal: %ld Col: ",row[i].rowVal);
for (U32 j=0;j<7;j++) {
sprintf(st,"%lu, ",row[i].col[j]);
}
}
}
if (!strncmp(anlzName,"Traffic Distribution by Destination

Address",43))
{
SendUserDLLResults *userDLLResults2=(SendUserDLLResults *) Result;
sprintf(st,"Name: %s Value:
%f\n",userDLLResults2[i].name,userDLLResults2[i].val);
}
}
if (!strncmp(anlzName,"Network Traffic Activity (pairs)",32)) {

UDDDblPairsRow *uddDblPairsRow=(UDDDblPairsRow *) Result;
for (U32 j=0;j<NO_ADDR;j++) {
strcpy(st2,uddDblPairsRow[i].descr[j]);
st2[MaxItemTitleLen]=0;
sprintf(st,"%d)Addr: %lu%lu Value: %f Sum: %f
Description:
%s\n",j+1,uddDblPairsRow[i].addrHigh[j],
uddDblPairsRow[i].addrLow[j],uddDblP
airsRow[i].val[j],uddDblPairsRow[i].sum[j],
DLL0296.65 7-13
uddDblPairsRow[i].descr[j]);
}
}
}
counter++;
}
// Function: AnalysisLinkStopped
// =============================
// This function is called when the analysis process is stopped. It should
//close everything and free the memory that has been allocated for this
//process.
// Parameters:
// -----------
// U32 Chnl - The number of the channel that runs the analysis process.
//
==========================================================================
void _export _stdcall AnalysisLinkStopped(U32 Chnl /*channel num */,
void* /*reserved*/)
{
if (_lclose(theFile[Chnl])==HFILE_ERROR)
::MessageBox(0,"external analysis _lclose
failed!!","Error!!",MB_OK);
}
} //extern "C"
7-14 DLL0296.65
Chapter 8
Link to Live Statistics Data
Introduction
The analyzer displays various statistics about the data on the screen. The Link to Live
Statistics data external DLL allows the user to receive statistics data as it is displayed on
screen and perform on it various operations. This is useful if you frequently have to perform
the same operation on your Statistics data.
This enables the user to perform applications such as:
The generation of various reports.
The generation of graphical statistics and performing various calculations on them.
Historical recording of Statistics data.
Creation of links between Statistics and other processes (e.g. display in the Capture
buffer more than 10% erroneous frames).
Global alarm window consolidating various information from many processes.
Analyzer Interface
Access the Link to Live Statistics applications by clicking the External button in the
Statistics setup dialog box.
DLL0296.65 8-1
When there is no external DLL this button is not active. The External Statistics window
opens with a list of available Statistics programs.
Click the required program and click the OK button. Click the OK button in the Statistics
setup dialog box and then click the Go button in the Statistics window.
8-2 DLL0296.65
Functions
The function StatisticsLinkNames gives a list of the possible operations provided by the
user. StatisticsLinkSetup is called by the analyzer if the user clicks the Setup button in the
Statistics dialog box. StatisticsLinkStarted informs the DLL that the statistics has started,
StatisticsLinkResults reports the statistics data as it is displayed on the screen and
StatisitcsLinkStopped responds to the user stopping the statistics process.
StatisticsLinkNames
StatisticsLinkNames returns names of links which can receive statistics to be displayed in
the Statistics setup dialog box.
Syntax
StatNameType* StatisticsLinkName (void *Reserved);
Parameters
Return Value
StatNameType Array of structures containing strings showing the Statistics
names and capabilities. The last item in the array must contain a
null string.
The structure of the StatNameType is as follows:
typedef struct
{
char *featureName;
U32 capabilities;
}StatNameType;
DLL0296.65 8-3
StatisticsLinkSetup
This function is called when the user clicks the Setup button in the Statistics window.
Syntax
void StatisticsLinkSetup (char *LinkName, HWND Parent, U32
Parameters
StatisticsLinkName.
Return Value
Nothing
8-4 DLL0296.65
StatisticsLinkStarted
StatisticsLinkStarted is called when the Statistics process starts.
Syntax
void StatisticsLinkStarted (char *LinkName, char *Filter, U32
Parameters
StatisticsLinkName.
char *Filter Name of the statistics filter chosen by the user.
void *TypesArr An array of strings containing more information on the
statistics:
TypesArr[0] - Number of elements in this array, excluding this
element.
TypesArr[1] - Start trigger as defined by the user in statistics
setup.
TypesArr[2] Hours: the period of time to run the statistics as
defined by the user in statistics setup.
TypesArr[3] - Minutes: the period of time to run the statistics as
defined by the user in statistics setup.
TypesArr[4] - Recording resolution: as defined by the user in
statistics setup (seconds=0, minutes=1, hours=2).
TypesArr[5] - Port Number: the number of the channel this
process is running on.
TypesArr[6] - Interface type: the interface the analyzer is
working with (see enumeration declaration in the reference
guide).
Return Value
Nothing
DLL0296.65 8-5
StatisticsLinkResults
Called every time the statistics is updated on the screen.
Syntax
void StatisticsLinkResults (TimeStruct *Timestamp, U32
FramesFromUser, U32 FramesFromNetwork, U32 BytesFromUser, U32
BytesFromNetwork, U32 channelNum, void *Reserved);
Parameters
TimeStruct A structure containing the time.
*Timestamp
U32 Number of frames received from user.

FramesFromUser
U32 Number of frames received from network.

FramesFromNetwork
U32 BytesFromUser Number of bytes received from user.

U32 Number of bytes received from network.
BytesFromNetwork
void *UtilsArr Array of strings containing more information on the statistics:
TypesArr[0] - number of elements in the array excluding this
element.
TypesArr[1] - Network utilization.
Return Value
Nothing
8-6 DLL0296.65
StatisticsLinkStopped
This function informs the DLL that the user has pressed the Stop button.
Syntax
void StatisticsLinkStopped (U32 channelNum, void *Reserved);
Parameters
Return Value
Nothing
Example
The following program creates a report about the traffic of each channel. Each section is
#include "defs.h"
#include <stdio.h>
#include <string.h>
#include <dir.h>
extern "C"
{
// Names of the Statistics processes supported by the DLL.

StatNameType statTypes[] =
{
{
"Statistics report", // The name of the stat
},
{NIL, 0}
};

HFILE fil[MaxChannelsNum];
char name[80];
U32 counter;
DLL0296.65 8-7
// Function: StatisticsLinkNames
// =============================
// This function returns the list of names of statistics applications that
//this DLL supports.
// Parameters:
// -----------
//
==========================================================================
StatNameType* _export _stdcall StatisticsLinkNames(void* /*reserved*/)
{
return statTypes;
}
// Function: StatisticsLinkSetup
// =============================
// This function is used in order to open a setup window for the user. In
//this example, the setup window is not used, so this function does
//nothing.
// Parameters:
// -----------
// char* StatisticsName - The name of the process that should open the setup
//window.
// HWND parent - Parent window, the window to open the setup window on.
// U32 Chnl - The number of the channel that runs the Statistics process.
//
==========================================================================
void _export _stdcall StatisticsLinkSetup(char* StatisticsName,
HWND parent /*parentWin*/,
void* reserved /*reserved*/)
{
}
// Function: StatisticsLinkStarted
// ===============================
8-8 DLL0296.65
// This function is called when the Statistics process starts. The DLL
//should initialize local variables and prepare everything for the
//process.
// Parameters:
// -----------
// char* StatisticsName - The name of the process that is about to begin.
// char* FilterName - The name of the filter that is in use in the
//Statistics process.
// void* TypesArr - Additional information about the statistics process.
//
==========================================================================
void _export _stdcall StatisticsLinkStarted(char* /*StatisticsName*/,
char* /*FilterName*/ ,
void* TypesArr)
{
counter=1;
Get TypesArray(TypesArr);
char st[80];
sprintf(st,"c:\\uddtemp\\stat%d.txt",Chnl+1);
if ((fil[Chnl]=_lcreat(st,0))==HFILE_ERROR)
::MessageBox(0,"external statistic creat failed!!","Error!!",MB_OK);
}
// Function: StatisticsLinkResults
// ===============================
// This function processes one message of Statistics results. In this
//example it saves all the results in the file of this channel.
// Parameters:
// -----------
// TimeStruct* TimeStamp - The time of the received results.
// U32 FramesFromUser - Number of frames received from user.
// U32 FramesFromNetwork - Number of frames received from network.
// U32 BytesFromUser - Number of bytes received from user.
// U32 BytesFromNetwork - Number of bytes received from network.
// void* UtilsArr array of strings containing more information on the
// statistics.
DLL0296.65 8-9
//
==========================================================================
void _export _stdcall StatisticsLinkResults(TimeStruct *TimeStamp ,
U32 FramesFromUser,
U32 FramesFromNetwork,
U32 BytesFromUser,
U32 BytesFromNetwork,
U32 Chnl ,
void* UtilsArr)
{
char st[200];
sprintf(st,"**************** %d ***************",counter);
_lwrite(fil[Chnl],st,strlen(st));
_lwrite(fil[Chnl],"\n",1);
sprintf(st,"time: %u-%hu-%hu-%lu-%lu ",TimeStamp->year,TimeStamp-
>month,TimeStamp->day,
TimeStamp->seconds,TimeStamp->microSeconds);
sprintf(st,"FramesFromUser: %lu",FramesFromUser);
sprintf(st,"FramesFromNetwork: %lu",FramesFromNetwork);
sprintf(st,"BytesFromUser: %lu",BytesFromUser);
sprintf(st,"BytesFromNetwork: %lu",BytesFromNetwork);
sprintf(st,"channelNum: %u",Chnl+1);
counter++;
double util=GetUtilization (UtilsArr);
}
// Function: StatisticsLinkStopped
// ===============================
8-10 DLL0296.65
// This function is called when the Statistics process is stopped. It

//should close everything and free the memory that has been allocated for
//this process.
// Parameters:
// -----------
//
==========================================================================
void _export _stdcall StatisticsLinkStopped(U32 Chnl /*channel num */,
void* /*reserved*/)
{
if (_lclose(fil[Chnl])==HFILE_ERROR)
::MessageBox(0,"external statistic _lclose failed!!","Error!!",MB_OK);
}
} //extern "C"
//This function extracts the information from the array.

void GetTypesArray(void *Arr)
{
char *Element;
char *ElementsInArray=((char **)Arr)[0];
int num = atoi(ElementsInArray);
for (int i=1 ;I <= num; I++)
{
Element =((char **)Arr)[I];
// do something with Element
}
}
//This function extracts the utilization from the array.
double GetUtilization(void *Arr)
{
char *UtilString;
double NetworkUtils = 0;
if (num >=1)
{
UtilString =((char **)Arr)[I];
NetworkUtils = atoi(UtilsString);
DLL0296.65 8-11
}
return NetworkUtils;
}
8-12 DLL0296.65
Chapter 9
Link to Live Line Status Data
Introduction
The Link to Live Line Status data external DLL allows the user to receive and manipulate
the Line Status data as it is displayed on screen.
This allows the use of applications such as:
Generation of various reports.
Generation of graphical statistics and performance of various calculations on them.
Historical recording of the Line Status data.
Creation of links between Line Status and other processes (e.g. display in the Capture
buffer more than 10% erroneous frames).
Global alarm window consolidating various information from many processes.
Analyzer Interface
Access the Link to Live Line Status data from the Line Status window.
DLL0296.65 9-1
Click the External button to access the External Line Status dialog box which contains a list
of available external DLLs.
When there is no external DLL this button is not active. Click on the required program and
click the OK button. Click the Go button in the Line Status window.
9-2 DLL0296.65
Functions
The function LineStatLinkNames gives a list of the possible operations provided by the
user. LineStatLinkSetup is called by the analyzer if the user clicks on the Setup button in
the Line Status dialog box. LineStatLinkStarted informs the DLL that the process has
started. LineStatLinkResults reports the Line Status data as it is displayed on the screen
and LineStatLinkStopped responds to the user stopping the Line Status process.
LineStatLinkNames
LineStatLinkNames returns names of links which can receive Line Status features to be
displayed in the Line Status Setup window.
Syntax
LnsNameType* LineStatLinkNames (void *Reserved);
Parameters
Return Value
LnsNameType* Array of structures containing strings showing the Line Status
names and capabilities. The last item in the array must contain a
null string.
The structure of the LnsNameType is as follows:
typedef struct
{
char* name;
U32 capabilities;
}LnsNameType;
DLL0296.65 9-3
LineStatLinkSetup
This function is called when the user clicks the Setup button in the External Line Status
dialog box.
Syntax
void LineStatLinkSetup (char *LinkName, HWND Parent, U32
Parameters
LineStatusLinkNames.
Return Value
Nothing
9-4 DLL0296.65
LineStatLinkStarted
LineStatLinkStarted is called when the Line Status process starts.
Syntax
void LineStatLinkStarted (char *LinkName, U32 channelNum, void
*Reserved);
Parameters
char *LinkName Name of the link selected from the array received by
LineStatusLinkNames.
void *TypesArr An array of strings containing more information on the line
status:
TypesArr[0] The number of elements in this array, excluding
this element.
TypesArr[1] - Port number: the number of the channel this
process is running on.
TypesArr[2] - Interface type: the interface the analyzer is
working with (see enumeration declaration in the reference
guide).
Return Value
Nothing
DLL0296.65 9-5
LineStatLinkResults
Called every time Line Status is updated on the screen.
Syntax
void LineStatLinkResults (LnsResult* Result, U32 numElements,
U32 channelNum, void *Reserved);
Parameters
LnsResult*Result An array containing the results.
U32 numElements The number of elements in the above array.
Return Value
Nothing
The structure of the LnsResult is as follows:
typedef struct
{
char* name;
U32 val;
} LnsResult;
9-6 DLL0296.65
LineStatLinkStopped
This function informs the DLL that the user has pressed the stop button.
Syntax
void LineStatLinkStopped (U32 channelNum, void *Reserved);
Parameters
Return Value
Nothing
Example
The following program creates a file, with the Line Status results. Each section is
#include "defs.h"
#include <stdio.h>
#include <string.h>
#include <dir.h>
extern "C"
{
char lnsName[80];
// This function returns the list of names of the analyses that this DLL
//supports.
LnsNameType lnsType[] =
{
{
"Line Status report", // The name of the LineStat
},
{NIL, 0}
};

HFILE FileLns[MaxChannelsNum];
DLL0296.65 9-7
U32 counter;
// Function: LineStatLinkNames
// ===========================
// This function returns the list of names of the Line Status applications
// that this DLL supports. This list has been created above.
// Parameters:
// -----------
//
==========================================================================
LnsNameType* _export _stdcall LineStatLinkNames(void* /*reserved*/)
{
return lnsType;
}
// Function: LineStatLinkSetup
// ===========================
// This function is used in order to open a setup dialog box for the user
// to provide additional information. In this example the line status does
// not have any setup, so this function does nothing.
// Parameters:
// -----------
// char* LnsName - The name of the process that should open the setup
// window.
// HWND parent - Parent window, to open the setup window on.
// U32 Chnl - The number of the channel that runs the Line Status process.
//
==========================================================================
void _export _stdcall LineStatLinkSetup(char* /*LnsName*/,
HWND /*parent*/,
U32 /*Chnl*/,
void* /*reserved*/)
{
}
// Function: LineStatLinkStarted
// =============================
// This function is called when the Line Status process starts. The DLL
9-8 DLL0296.65
// should initialize local variables and prepare everything for the

// process.
// Parameters:
// -----------
// char* Name - The name of the process that is about to begin.
// U32 Chnl - The number of the channel that runs the line status process.
// void* TypesArr - Additional information about the line status process.
//
==========================================================================
void _export _stdcall LineStatLinkStarted(char* Name,
U32 Chnl,
void* TypesArr)
{
counter = 1;
char st[200],st2[200];
Get TypesArray(TypesArr);
strcpy(lnsName,Name);
sprintf(st2,"c:\\uddtemp\\Lns%d.txt",Chnl+1);
if ((FileLns[Chnl]=_lcreat(st2,0))==HFILE_ERROR)
::MessageBox(0,"external Line Status creat failed!!","Error!!",MB_OK);
_lwrite(FileLns[Chnl],"\n",1);
sprintf(st,"Name:%s Channel:%d",Name,Chnl+1);
_lwrite(FileLns[Chnl],st,strlen(st));
}
// Function: LineStatLinkResults
// =============================
// This function processes one message of the Line Status results. In this
// example it saves all the results in the file of this channel.
// Parameters:
// -----------
// LnsResult* Result - Array of results for the last second.
// U32 numElements - Number of elements in the results array.
//
==========================================================================
DLL0296.65 9-9
void _export _stdcall LineStatLinkResults(

LnsResult *Result,
U32 numElements,
U32 Chnl ,
void* /*reserved*/)
{
char st[200];
sprintf(st,"**************** %d ***************\n",counter);

sprintf(st,"%d) Name: %s Value: %lu ;
",i,Result[i].name,Result[i].val);
}
counter++;
}
// Function: LineStatLinkStopped
// =============================
// This function is called when the Line Status process is stopped. It
// should close everything and free the memory that has been allocated for
// this process.
// Parameters:
// -----------
//
==========================================================================
void _export _stdcall LineStatLinkStopped(U32 Chnl,
void* /*reserved*/)
{
if (_lclose(FileLns[Chnl])==HFILE_ERROR)
::MessageBox(0,"external Line Status _lclose
failed!!","Error!!",MB_OK);
}
} //extern "C"
//This function extracts the information from the array
void GetTypesArray(void *Arr)
9-10 DLL0296.65
{
char *Element;
for (int i=1 ;I <= num; I++)

{
Element =((char **)Arr)[I];
// do something with Element
}
}
DLL0296.65 9-11
Chapter 10
User-Defined Simulation
Introduction
The User-Defined Simulation external DLL allows you to write your own simulation
application and merge it with RADCOMs software.
Using this package you can build a range of simulation capabilities such as:
State machine dependent simulation.
Conditional generation of frames.
Dynamic control of the generated frame size, content and rate, depending on the
incoming traffic.
Note:
The User-Defined Simulation external DLL is applicable to the PrismLite protocol analyzer
with WAN/LAN interfaces.
Analyzer Interface
To access User-Defined Simulation:
1. In the System Configuration dialog box, choose the appropriate FEP.
2. Click the Configuration button , or choose Channel Assignment from the

Configuration menu. In the LIM box for the port that you are using, select the
appropriate LIM.
DLL0296.65 10-1
3. In the Working Mode box, choose one of the options for User-Defined Simulation.
These options are added to the standard working mode options by the external DLL. For
example, the working mode below is set to UDD Sim1 (Using UDP Filter). Click the
OK button.
Note the following:

If you select a working mode that involves a filter that is not installed, you will
receive an error message when you try to run the simulation. If you receive this
message, define the missing filter by choosing Filters from the File menu. Refer to
the Filters chapter in the PrismLite User Guide.
If a User-Defined Simulation does not support any line type, it will not appear in
the list of working modes.
3. Click the Processes button and select the Simulation process for the port
that you are using. Click the Apply button.
4. Click the icon for User-Defined Simulation. In the example, click UDD Sim1
. The Ready view is displayed. Click the Setup button to define
application parameters. You can only use the Setup button if the Setup flag is activated
in the external DLL (refer to Skeletal Program in this chapter). Click the Go button to
run the User-Defined Simulation.
10-2 DLL0296.65
5. Click the Stop button to end the process.

6. Click the Details button to view additional information. You can only use the Details
button if the Details flag is activated in the external DLL (refer to Skeletal Program in
this chapter). Click the Print button to print the displayed statistics. Click the Done
button to clear the statistics and return to the Ready view.
Functions
The following functions are used by the external DLL for user-defined simulation:
SimulationNames gives a list of the possible types of simulation (such as Frame Relay)
provided by a specific user-defined DLL. The capabilities of each simulation are also
described, for example, whether it opens its own windows, if there is a post-simulation
window, etc.
When the user clicks the Setup button in the Simulation Setup dialog box, SimulationSetup
is called by the analyzer. GetFilter is called to receive the filter to be used on the received
frames. The description of this filter appears in the Ready view. If this filter does not exist,
the function FilterNotExist is called with the original filter that was requested and the
default filter AllFrames is used.
When the user clicks the Go button, SimulationStarted informs the DLL that the process
has started. FrameReceived is called by the application program to signify that a frame was
received. The function SendFrame transmits a frame. More than one frame can be queued
for transmission without receiving an acknowledgement message. If the DLL uses
RADCOM windows, the GetStatus function is called to receive the string for display from
the DLL. StopSimulation signifies that the simulation should be stopped.
When the user clicks the Stop button, SimulationStopped responds. Once the simulation
has stopped, the SimulationGetSummaryStrings is called to receive the string for display
from the DLL, if the DLL uses RADCOM windows. Alternatively, if the user marked the
flag in the capabilities mask, a separate window can be opened that displays user-defined
information; this is accomplished by clicking the Details button that calls
SimulationDisplayPostExecution.
For additional information about these functions, see the sections that follow.
DLL0296.65 10-3
SimulationNames
SimulationNames returns the names of the kinds of simulation which are supported by the
DLL.
Syntax
FeatureNameType* SimulationNames (void *Reserved);
Parameters
Return Value
USimulationNameType* Array of structures containing strings showing
the simulation names and capabilities. The last
item in the array must contain a null string.
The structure of USimulationNameType is:
typedef struct
{
char* simulationName;
U32 capabilities;
} USimulationNameType;
The capabilities variable for USimulationNameType is:
#define DLLDisplayWindows 0x000000000001L
#define DisplayPostExecSupported 0x000000000002L
#define SetupSupported 0x000000000040L
To view how these are implemented, see Skeletal Program in this chapter.
10-4 DLL0296.65
SimulationSetup
This function is called when the user clicks the Setup button in the Simulation dialog box.
Syntax
void SimulationSetup (char *processName, HWND parentWindow, U8
portNum, Void *Reserved);
Parameters
char *processName The name of the simulation selected as it
appears in the SimulationNames array.
HWND parentWindow Pointer to the parent window.
U8 portNum Port number.
Void *Reserved For future use.
Return Value
None
DLL0296.65 10-5
SimulationStarted
SimulationStarted is called when the simulation process starts.
Syntax
void SimulationStarted (char* simulationName, SendFrame
sendFrame, StopSim stopSimulation, DoneSim doneSimulation, U8
portNum, UsimDetails &simDetails, void *Reserved);
Parameters
char* simulationName Pointer to the string that contains the simulation
name.
SendFrame sendFrame Callback function address that allows the DLL
to send frames.
StopSim stopSimulation Callback function that allows the DLL to stop
the simulation.
DoneSim doneSimulation Callback function that allows the DLL to return
the process to the Ready state.
UsimDetails &simDetails Pointer to the UsimDetails structure.
Return Value
None
The structure of UsimDetails is as follows:
typedef struct
{
U32 szStruct;
U32 theLineType;
U32 theInterface;
char *startingProtocol;
} USimDetails;
Values for the various capabilities are provided below. These values are needed for the
LineType variable in the structure above.
#define AllLineTypesSupported 0x00FFFFFFFF00L
#define FirstLineType 0x00000100L
#define AllLineTypesSupported 0x00FFFF00L
#define ASYNCSupported 0x00000100L
#define HDLCSupported 0x00000200L
#define TransparentSupported 0x00000400L
10-6 DLL0296.65
#define TokenRingSupported 0x00000800L

#define EthernetSupported 0x00001000L
#define Fast_EthernetSupported 0x00100000L
#define ATM_SAR_UNISupported 0x00008000L
#define ATMComboUNISupported 0x00040000L
Values for the various interface types are provided below:
#define T1Mask 0x0000000001L
#define V35Mask 0x0000000002L
#define MultiMask 0x0000000004L
#define RS232Mask 0x0000000008L
#define E1Mask 0x0000000010L
#define E1IntegMask 0x0000000020L
#define T1IntegMask 0x0000000040L
#define MultiIntegMask 0x0000000080L
#define E1SplitMask 0x0000000100L
#define T1SplitMask 0x0000000200L
#define MultiSplitMask 0x0000000400L
#define ISDNMask 0x0000000800L
#define LanInterfaceMask 0x0000001000L
#define OC3C_STM1_Mask 0x0000002000L
#define DS1_Mask 0x0000004000L
#define DS3_Mask 0x0000008000L
#define DS3_PDH_Mask 0x0000010000L
#define E1_Mask 0x0000020000L
#define E3_Mask 0x0000040000L
#define TAXI_Mask 0x0000080000L
#define _25UTP_Mask 0x0000100000L
#define ATM_SAR_Mask 0x0000200000L
#define ATM_Cell_Mask 0x0000400000L
DLL0296.65 10-7
SimulationGetSetupStrings
SimulationGetSetupStrings retrieves strings for display in the Ready view.
Syntax
char** SimulationGetSetupStrings (char* simulationName, U8
portNum, void* /*reserved*/)
Parameters
char* simulationName Simulation name.
Return Value
Pointer to the string that is displayed in the Ready view.
10-8 DLL0296.65
SimulationGetFilter
Retrieves a filter name from the DLL and displays a description of it in the Ready view.
This filter is used on the received frames. If the filter does not exist, it is replaced by the All
Frames filter and the DLL is notified by the SimulationFilterNotExist function.
Syntax
char* SimulationGetFilter(char* simulationName, U8 portNum,
void* reserved)
Parameters
void* reserved Reserved for future use.
Return Value
Returns a string that contains the filter name.
DLL0296.65 10-9
SimulationFilterNotExist
Called when the filter defined by the DLL does not exist in the filter list. Therefore, the
filter is replaced by the All Frames filter.
Syntax
void SimulationFilterNotExist(char* simulationName, U8
portNum, char* oldFilter, char* newFilter, void*)
Parameters
char* oldFilter String that contains the name of the old filter.
char* newFilter String that contains the name of the new filter.
void* Reserved for future use.
Return Value
None
10-10 DLL0296.65
FrameReceived
Gives the DLL the last retrieved frame.
Syntax
void FrameReceived(char* simulationName, TimeStruct*timeStamp,
U32 frameParameters, U16 frameStatus, U16 frameLength, U8*
rawData, UDDProtocolStruct* protocolMap, U8 portNum, void*
/*reserved*/)
Parameters
TimeStruct*timeStamp Pointer to the structure for the captured item time.
U32 frameParameters Parameters of the frame.
U16 frameStatus Status of the frame.
U16 frameLength Length of the frame.
U8* rawData Pointer to the data contained in the frame.
UDDProtocolStruct* Pointer to the structure that represents the protocol
protocolMap map type.
Return Value
None
The structure of TimeStruct is as follows:
typedef struct
{
U16 year;
U8 month;
U8 day;
U32 seconds;
U32 microSeconds;
} TimeStruct;
The structure of UDDProtocolStruct is as follows:
typedef struct
{
U16 protocolId;
S32 protocolOffset;
}UDDProtocolStruct;
DLL0296.65 10-11
GetStatus
Receives status strings to display in the Running view. This function is called only if the
DLL did not choose to show its own windows.
Syntax
char** GetStatus(char* simulationName, U8 portNum, void*)
Parameters
Return Value
Pointer to a string.
10-12 DLL0296.65
SimulationStopped
Informs the DLL that the simulation has been stopped. This can occur either because the
user pressed the Stop button or because the DLL has called the StopSimulation function.
This indicates that the Stop process is complete.
Syntax
void SimulationStopped(char* simulationName, U8 portNum,
void*)
Parameters
Return Value
None
DLL0296.65 10-13
SimulationGetSummaryStrings
Retrieves strings to display in the post-simulation view.
Syntax
char** SimulationGetSummaryStrings(char* simulationName, U8
portNum, void*)
Parameters
Return Value
Pointer to a string.
10-14 DLL0296.65
SimulationDisplayPostExecution
When the user presses the Details button in the post-simulation view, the DLL is directed to
open the dialog box that displays details. The user can choose not to implement this function
by not flagging this capability in the capabilities mask.
Syntax
void SimulationDisplayPostExecution(char* simulationName, U8
portNum, HWND parentWindow, void*)
Parameters
HWND parentWindow Pointer to the parent window.
Return Value
None
DLL0296.65 10-15
SimulationCloseAll
Indicates to the DLL that the process is switching to the Ready state, and it should free all
allocated memory.
Syntax
void SimulationCloseAll(char *simulationName, U8 portNum,
void*)
Parameters
Return Value
None
10-16 DLL0296.65
SendFrame
This callback function allows the user to send a frame from the DLL to the PrismLite.
Syntax
Void SendFrame (U8* data, U32 length, U32 seqNum,
UsimulationFrameInfo &frameInfo, U8 chnl);
Parameters
U8* data Pointer to the data buffer that will be sent.
U32 length Length of the data buffer
U32 seqNum Frame sequence number.
USimulationFrameInfo Address for the structure that contains parameters
&frameInfo describing the frame being sent.
U8 chnl Channel number.
Return value
None
The structure of USimulationFrameInfo is as follows:
typedef struct
{
U32 szStruct;
U32 numOfFrames;
U32 utilization;
U8 uddPriority;
} USimulationFrameInfo;
The following are definitions of the priorities for the frames sent from the DLL:
#define UDD_HIGH 1
#define UDD_LOW 0
DLL0296.65 10-17
StopSim
This callback function informs the RADCOM code to stop the Simulation process.
Syntax
VoidStopSimulation(U8 portNum)
Parameters
Return Value
None
10-18 DLL0296.65
DoneSim
The purpose of this callback function is similar to pressing the Done button. It informs the
RADCOM software to end the simulation and open the Ready view in anticipation of a new
simulation.
Syntax
VoidDoneSim(U8 portNum)
Parameters
Return Value
None
Skeletal Program
The following is a sample skeletal program:
extern "C"
{
extern HINSTANCE hInst;
// Names of the user processes supported by the DLL and the capabilities of
each simulation.
USimulationNameType userSimulationNames[] =
{
{"UDD Sim1 (UDP)",
AllLineTypesSupported|SetupSupported|DisplayPostExecSupported|DLLDisplayWind
ows},
{"UDD Sim2 (TCP)", AllLineTypesSupported},
{"UDD Sim3 (IP)", AllLineTypesSupported},
{"UDD Sim4 (All Frames)", AllLineTypesSupported},
{NIL, 0}
};
HWND pWHand;
SendFrame pSendFrame;
StopSim pStopSim;
DoneSim pDoneSim;
DLL0296.65 10-19
USimulationNameType* _export DLL_FUNCTION SimulationNames(void* )

{
return userSimulationNames;
}
void _export DLL_FUNCTION SimulationSetup(char* processName,

HWND parentWindow,
U8 portNum,
void* /*reserved*/)
{
/*This function is called when the user clicks the Setup button in the
Simulation dialog box.*/
}
char** _export DLL_FUNCTION SimulationGetSetupStrings(char* simulationName,
U8 portNum,
void* /*reserved*/)
{
static char *setupStrings[] = {"This working mode",
"filters UDP frames and",
"responds by sending
frames with random
priority.",
NIL};
return (setupStrings);
}
char* _export DLL_FUNCTION SimulationGetFilter(char* simulationName,

U8 portNum,
void*)
{
static char *filter = new char[25];
filter = "UDP";
return filter
}
void _export DLL_FUNCTION SimulationFilterNotExist(char* simulationName,

U8 portNum,
char* oldFilter,
char* newFilter,
void*)
10-20 DLL0296.65
{
/* Called when the filter defined by the DLL does not exist in the filter
list. Therefore, the filter is replaced by the All Frames filter.*/
}
void _export DLL_FUNCTION SimulationStarted(char* simulationName,

SendFrame sendFrame,
StopSim stopSimulation,
DoneSim doneSimulation,
U8 portNum,
USimDetails &simDetails,
void*)
{
/*These are the pointers to the callback functions used by the DLL.*/
pSendFrame = sendFrame;
pStopSim = stopSimulation;
pDoneSim = doneSimulation;
}
void _export DLL_FUNCTION FrameReceived(char* simulationName,

TimeStruct*timeStamp,
U16 frameStatus,
U16 frameLength,
U8* rawData,
UDDProtocolStruct* protocolMap,
U8 portNum,
void* /*reserved*/)
{
/*The user can process the received frame (save the frame, send it back,
etc.) without limitation.*/
}
char** _export DLL_FUNCTION GetStatus(char* simulationName,

U8 portNum,
void*)
{
static char *statusStrings[] = {"This working mode filters",
"UDP frames and responds by",
"sending frames with random
priority.",
NIL};
DLL0296.65 10-21
return (statusStrings);
}
void _export DLL_FUNCTION SimulationStopped( char* simulationName,

U8 portNum,
void*)
{
/*As an example for what we can do in SimulationStopped, we can call the
pDoneSim callback function.*/
pDoneSim(portNum);
}
char** _export DLL_FUNCTION SimulationGetSummaryStrings(char*

simulationName,
U8 portNum,
void*)
{
static char *summaryStrings[] = {" UDD filtering and",
"simulation has stopped.",
NIL};
return (summaryStrings);
}
void _export DLL_FUNCTION SimulationDisplayPostExecution(char*

simulationName,
U8 portNum,
HWND parentWindow,
void*)
{
/*This function activates windows defined by the user for post-simulation
processing.*/
}
void _export DLL_FUNCTION SimulationCloseAll(char *simulationName,

U8 portNum,
void*)
{/* Indicates to the DLL that the process is switching to the Ready state,
and it should free all allocated memory.*/
}
10-22 DLL0296.65
Appendix A
Reference Guide
ATM Frame Header Structure
For reference, the ATM frame header structure as used by the analyzer is given below:
Status Reserved Port VPI VCI AAL type GFC PTI CLP
1 0 4:7 1:3 0
0 1 2 3 4 5 6 7
ATM frame header structure
VPI, VCI, AAL type, GFC, PTI and CLP are as in the ATM standard. Port refers to the port
number of the analyzer which can be 1 or 2 (01 or 10 binary).
Definitions
The following definitions are to be made in the user-defined DLLs:
AAL Types
The various AAL types have the following values:
AAL 3/4 value 0
AAL 5 value 1
AAL 0 Cell 2
AAL 1 Cell 3
AAL 2 Cell 4
AAL 3/4 Cell 5
AAL 5 Cell 6
Frame Parameters: (U32)

The following frame parameters must be defined:
Direction
#define DirectionMask 0x00000001
#define Network_Value 0x00000000
#define User_Value 0x00000001
DLL0296.65 A-1
Line Type
#define AllLineTypesSupported 0x00FFFFFFFF00L
#define FirstLineType 0x00000100L
#define AllLineTypesSupported 0x00FFFF00L
#define ASYNCSupported 0x00000100L
#define HDLCSupported 0x00000200L
#define TransparentSupported 0x00000400L
#define TokenRingSupported 0x00000800L
#define EthernetSupported 0x00001000L
#define Fast_EthernetSupported 0x00100000L
#define ATM_SAR_UNISupported 0x00008000L
#define ATMComboUNISupported 0x00040000L
InterfaceType
#define NoInterface 0x00000000
#define T1Interface 0x00000001
#define V35Interface 0x00000002
#define RS530_RS449_X21Interface 0x00000003
#define RS232Interface 0x00000004
#define E1Interface 0x00000005
#define E1InterfaceInteg 0x00000006
#define T1InterfaceInteg 0x00000007
#define MultiInterfaceInteg 0x00000008
#define E1InterfaceSplit 0x00000009
#define T1InterfaceSplit 0x0000000A
#define MultiInterfaceSplit 0x0000000B
#define ISDNInterface 0x0000000C
#define LanInterface 0x0000000D
#define OC3C_STM1_Interface 0x0000000E
#define DS1_Interface 0x0000000F
#define DS3_Interface 0x00000010
#define DS3_PDH_Interface 0x00000011
#define E1_Interface 0x00000012
#define E3_Interface 0x00000013
#define TAXI_Interface 0x00000014
#define _25UTP_Interface 0x00000015
#define ATM_SAR_Interface 0x00000016
#define ATM_Cell_Interface 0x00000017
#define DDSInterface 0x00000018
#define LastInterface 0x00000019
A-2 DLL0296.65
Frame Status (U16)

The following are the values of the status bits and their respective meanings.
All Line Types:
0x0000 OK
HDLC Errors:
0x0001 CD Lost
0x0002 RX Overrun
0x0004 CRC Error
0x0008 Abort Sequence
0x0010 Non-octet Aligned
0x0020 Length Violation
0x0040 Tx Underrun
Transparent Errors:
0x0001 CD Lost
0x0002 RX Overrun
0x0040 Tx Underrun
ASYNC Errors:
0x0001 CD Lost
0x0002 RX Overrun
0x0008 Parity error
0x0010 Missing stop bits
0x1000 Escape followed by Flag (PPP over ASYNC)
0x2000 Frame too short (PPP over ASYNC)
0x4000 Frame too long (PPP over ASYNC)
0x8000 FCS error (PPP over ASYNC)
Ethernet Errors:
(status & 0x0010) EQ 0 =>> Monitor
0x0001 Late Collision
0x0400 CRC/Alignment
0x0800 CRC Error
(status & 0x0010) EQ 0x0010 =>> Simulation
0x0020 Too many Collisions
0x0800 Late Collision
0x0080 Deferred
0x0040 Generated CRC error frame
Token Ring Errors:

0x0001 Burst Error
0x0002 Violation Error
DLL0296.65 A-3
0x0004 Bad end delimiter

0x0080 AC & FS Undetermined
0x0800 CRC error
0x0400 Alignment CRC
ATM/SAR UNI Errors:

0x0010 parity error
(status & 0x2f) EQ 3 =>> Out of Sequence
(status & 0x2f) EQ 5 =>> Invalid Length
(status & 0x29) EQ 9 =>> Payload CRC Error
(status & 0x2f) EQ 0x21 =>> Short Cell
(status & 0x2d) EQ 0x8 =>> 32 Bit CRC Error
(status & 0x2f) EQ 0x20 =>> End of Packet Error
(status & 0x27) EQ 0x2 =>> Buffer Overflow
(status & 0x27) EQ 0x22 =>> Last cell not received
(status & 0xf) EQ 0x4 =>> Packet aging process
Frame Time
The time structure is as follows:
typedef struct {
U16 year;
U8 month;
U8 day;
U32 seconds;
U32 microSeconds;
} TimeStruct;
A-4 DLL0296.65
Error Messages
When the DLLs are run in debug mode (refer to Software Interface in Chapter 1), a number
of error messages are provided. The following is a list of error conditions and their
associated messages divided according to the function to which they are applicable.
General
Illegal Condition Expected Behavior Debug Mode Error Message
The name of the DLL The DLL should not DLLName doesnt exist in the
appears in the .ini file but appear in the DLLs array directory.
the file does not exist in the and should not be called.
specified directory (refer to
Software Interface for more
information).
Function Name is not The DLL should be Name is not implemented by
implemented by the DLL. removed from the DLLs DLLName.
array and should not be
called.
NIL returned from Name The DLL should be Name returns NIL in
routine. removed from the DLLs DLLName.
called.
DLL doesnt support any The DLL should be DLLName exists but doesnt
feature. removed from the DLLs support any feature.
called.
User-Defined Analysis
One of the analysis All analyses supported by Routine is required for

functions is not the DLL should be analysis but not supported by
implemented by the DLL. ignored. DLLName.
Illegal instance of This analysis should be AnalysisNames returns illegal
AnalysisNameType in the ignored. All other analyses value in DLLName - analysis
array received from in the DLL should be ignored.
AnalysisNames routine. used.
(e.g., NIL subject or NIL
name).
DLL0296.65 A-5
Analysis with no graph type Bar type set to analysis as Analysis subject: subject,
supported. default. Name: name: Graph type not
supported.
Analysis with no line type Analysis will be ignored Analysis subject: subject,
supported. by the analysis setup Name: name: No line type
dialog box. supported.
Name received from The analysis should be AnalysisName already exists
AnalysisNames already ignored. in analysis library.
exists in library.
NIL returned from The analysis results AnalysisExit returns NIL in
AnalysisExit routine. window will be opened DLLName - no analysis
with an error message. results.
Illegal instance of The illegal bin will No error message.
AnalyzeResult in the array terminate the array
of results received from
AnalysisExit routine (e.g.,
NIL name).
Array of results received The first 10 bins will be AnalysisExit returns too
from AnalysisExit routine is used. All the other bins many values in DLLName -
too long. will be summarized and only first 10 bins are used.
will be shown as Others.
One of the bins received The first 20 characters of No error message.
from AnalysisExit has too the name will be used.
long a name.
User-Defined Simulation
The working mode uses a User must install the Opens a message box when
filter that is not defined. missing filter. Go is pressed.
Simulation with no line The simulation will not No error message.
type supported. appear as a working mode
option.
A-6 DLL0296.65
Decode a Single Frame

One of the decode functions All the decodes supported Routine is required for
is not implemented by the by the DLL should be decode but not supported by
DLL. ignored. DLLName.
Decode with no line type The decode should be Decode name:name: No line
supported. ignored. type supported.
Name received from The decode should be DecodesName already exists
DecodeFrameNames ignored. in the decode list.
already exists in the list.
NIL returned from No line will be added to DecodeSingleFrame returns
DecodeSingleFrame the frame decode lines. NIL DLLName - no frame
routine. decode.
Decode line received from The line will be divided No error message.
DecodeSingleFrame is too into many lines.
long.
User-Defined Filter
One of the filter functions is All the filters supported by Routine is required but not
not implemented by the the DLL should be supported by DLLName.
DLL. ignored.
Filter with no line type Filter should be ignored. Filter class name: No line
supported. type supported.
Process All Frames in Capture Buffer

One of the process all All the processes Routine is required but not
frames functions is not supported by the DLL supported by DLLName.
implemented by the DLL. should be ignored.
Process with no line type Process should be ignored. Process name: No line type
supported. supported.
DLL0296.65 A-7
Process Frames in Background Record Process

One of the functions All the processes Routine is required but not
required is not implemented supported by the DLL supported by DLLName.
by the DLL. should be ignored.
Link to Live Analysis Data

Link to Live Statistics Data

Link to Live Line Status Data

A-8 DLL0296.65
List of Functions and Syntax

Following is a list of all available functions in alphabetical order.
Function Name Syntax
AnalysisDone void AnalysisDone(void* Reserved);

AnalysisExit AnalyzeResult* AnalysisExit(void*
Reserved);
AnalysisGetYAxis char* AnalysisGetYAxis(void* Reserved);
AnalysisInit void AnalysisInit(char* Subject, char*
AnalysisName, BOOL Frames, BOOL Percent,
void* Reserved);
AnalysisLinkNames Char** LinkNames AnalysisLinkNames (void*
reserved);
AnalysisLinkResults void AnalysisLinkResult (void *Results,
int numElements, int channelNum, void
*Reserved);
AnalysisLinkSetup void AnalysisLinkSetup (char *LinkName,
HWND Parent, int channelNum, void
*Reserved);
AnalysisLinkStarted void AnalysisLinkStarted (char *LinkName,
char *Subject, char *Analysis, char
*Filter, U8 Units, U8 Calculation, U8
Yaxis, u8 GraphicDisplay, int channelNum,
void* Reserved);
AnalysisLinkStopped void AnalysisLinkStopped (int channelNum,
void* Reserved);
AnalysisNames AnalyzeNameType* AnalysisNames(void*
Reserved);
AnalysisSetup void AnalysisSetup(char* Subject, char*
AnalysisName,HWND parentWin, void*
Reserved);
AnalyzeFrame void AnalyzeFrame(TimeStruct* Timestamp,
U16 FrameStatus, U32 FrameParameters, U16
FrameLength, U8* RawData, void* Reserved);
DecodeFrameNames DecodeNameType* decodeFrameNameArray(void*
Reserved);
DLL0296.65 A-9
DecodeFrameSetup void DecodeFrameSetup(char* DecodeName,

HWND parentWin, void* Reserved);
DecodeSingleFrame DecodeResult* DecodeSingleFrame (char*
DecodeName, TimeStruct* Timestamp, U16
FrameStatus, U32 FrameParameters, U16
FrameLength, U8* RawData, char*
StartingProtocol, U32 Offset, U8 DispMode,
BOOL SingleProtocol, char** Decode,
U8 spareChars, void* Reserved);
DefaultFilterNames FilterNameType* DefaultFilterNames(void*
Reserved);
DoneSim VoidDoneSim(U8 portNum)
ExitDLL void ExitDLL(void* Reserved);
FilterClassNames FilterNameType* FilterClassNames(void*
Reserved);
FilterDelete BOOL FilterDelete(char* FilterName, void*
Reserved);
FilterEdit char* FilterEdit(char* FilterName, HWND
FilterExists BOOL Exist(char* Name, void* Reserved);
FilterFrame BOOL* FilterFrame(char* FilterName,
TimeStruct* Timestamp, U16 FrameStatus,
U32 FrameParameters, U16 FrameLength, U8*
RawData, void* Reserved);
FilterNew char* FilterNew(char* ClassName, HWND
FrameReceived void FrameReceived(char* simulationName,
TimeStruct*timeStamp, U32 frameParameters,
U16 frameStatus, U16 frameLength, U8*
rawData, UDDProtocolStruct* protocolMap,
U8 portNum, void* /*reserved*/)
FrameSent void FrameSent(char* simulationName,U32
frameNum,U8 portNum, void*)
GetStatus char** GetStatus(char* simulationName, U8
portNum, void*)
A-10 DLL0296.65
LineStatLinkNames Char** LinkNames LineStatLinkNames (void

*Reserved);
LineStatLinkResults void LineStatLinkResults (LnsResult*
Result, int numElements, U32 channelNum,
void *Reserved);
LineStatLinkStarted void LineStatLinkStarted (char *LinkName,
U32 channelNum, void *Reserved);
LineStatLinkStopped void LineStatLinkStopped (U32 channelNum,
void *Reserved);
Name char* Name(void* Reserved);
OLProcessFrame void OLProcessFrame (TimeStruct*
Timestamp, U16 FrameStatus,
U32FrameParameters, U16 FrameLength, U8
RawData, U8 protocolMapSize,
ProtocolStruct* protocolMap, U8
portNumber, void *Reserved);
OLProcessFramesExit void OLProcessFramesExit (U8 PortNumber,
void *Reserved);
OLProcessFramesInit BOOL OLProcessFramesInit(char
*ProcessName, U32 BytesPerSecond, HWND
parentWin, U8 portNumber, char*
protocolsFileName, void *Reserved);
OLProcessFramesNames ProcessNameType* OLProcessFramesNames
(void* Reserved);
OLProcessFramesSetup void OLProcessFramesSetup (char*
ProcessName, HWND ParentWin, void*
Reserved);
ProcessAllFramesExit void ProcessAllFramesExit(void* Reserved);
ProcessAllFramesInit void ProcessAllFramesInit(char*
processName,
U32 totalFrames,
U32 bytesPerSecond,
char* windowName,
HWND parentWindow,
void* /*reserved*/);
DLL0296.65 A-11
ProcessAllFramesNames ProcessNameType*
ProcessAllFramesNameArray(void* Reserved);
ProcessAllFramesSetup void ProcessAllFramesSetup(char*
ProcessName, HWND parentWin void*
Reserved);
ProcessFrame BOOL Abort(TimeStruct* Timestamp, U16
FrameStatus, U32 FrameParameters,
U16 FrameLength, U8* RawData, void*
Reserved);
RecallSetup void RecallSetup(char* DirName, void*
Reserved);
SaveSetup void SaveSetup(char* DirName, void*
Reserved);
SendFrame Void SendFrame (U8* data, U32 length, U32
seqNum, UsimulationFrameInfo &frameInfo,
U8 chnl);
SimulationCloseAll void SimulationCloseAll(char
*simulationName, U8 portNum, void*)
SimulationDisplayPost void SimulationDisplayPostExecution(char*
Execution simulationName, U8 portNum, HWND
parentWindow, void*)
SimulationFilterNotExist void SimulationFilterNotExist(char*
simulationName, U8 portNum, char*
oldFilter, char* newFilter, void*)
SimulationGetFilter char* SimulationGetFilter(char*
simulationName, U8 portNum, void*
reserved)
SimulationGetSetup char** SimulationGetSetupStrings (char*
Strings simulationName, U8 portNum, void*
/*reserved*/)
SimulationGetSummary char** SimulationGetSummaryStrings(char*
Strings simulationName, U8 portNum, void*)
SimulationNames FeatureNameType* SimulationNames (void
*Reserved);
A-12 DLL0296.65
SimulationSetup void SimulationSetup (char *processName,

HWND parentWindow, U8 portNum, Void
*Reserved);
SimulationStarted void SimulationStarted (char*
simulationName, SendFrame sendFrame,
StopSim stopSimulation, DoneSim
doneSimulation, U8 portNum, UsimDetails
&simDetails, void *Reserved);
SimulationStopped void SimulationStopped(char*
simulationName, U8 portNum, void*)
StatisticsLinkNames Char** LinkNames StatisticsLinkName (void
*Reserved);
StatisticsLinkResults void StatisticsLinkResults (TimeStruct
*Timestamp, U32 FramesFromUser, U32
FramesFromNetwork, U32 BytesFromUser, U32
BytesFromNetwork, Int channelNum, void
*Reserved);
StatisticsLinkSetup void StatisticsLinkSetup (char *LinkName,
HWND *Parent, int channelNum, void
*Reserved);
StatisticsLinkStarted void StatisticsLinkStarted (char
*LinkName, char *Filter, int channelNum,
void *Reserved);
StatisticsLinkStopped void StatisticsLinkStopped (int
StopSimulation VoidStopSimulation()
DLL0296.65 A-13
Index
A Link to Live Analysis Data 7-8
AAL Types A-1 Link to Live Line Status Data 9-7
AnalysisDone 2-9 Link to Live Statistics Data 8-7
AnalysisExit 2-8 Process all Frames in Capture Buffer 4-6
AnalysisGetYAxis 2-7 User-Defined Analysis 2-9
AnalysisInit 2-5 User-Defined Filter 5-9
AnalysisLinkNames 7-3 User-Defined Simulation 10-19
AnalysisLinkResults 7-7 ExitDLL 1-6
AnalysisLinkSetup 7-5
AnalysisLinkStarted 7-6 F
AnalysisLinkStopped 7-8 FilterClassNames 5-3
AnalysisNames 2-2 FilterDelete 5-8
AnalysisSetup 2-4 FilterEdit 5-7
AnalyzeFrame 2-6 FilterExists 5-5
Analyzer Interface FilterFrame 5-9
Background Record 6-1 FilterNew 5-6
Decode a Single Frame 3-1 Frame Parameters A-1
Link to Live Analysis Data 7-1 Frame Status A-3
Link to Live Line Status Data 9-1 FrameReceived 10-11
Link to Live Statistics Data 8-1 Functions
Process all Frames in Capture buffer 4-1 Background Record 6-2
User-Defined Analysis 2-1 Decode a Single Frame 3-2
User-Defined Filter 5-1 Link to Live Analysis Data 7-3
User-Defined Simulation 10-1 Link to Live Line Status Data 9-3
ATM Frame Header Structure A-1 Link to Live Statistics Data 8-3
List of A-9
B Process all Frames in Capture Buffer 4-2
Background Record 6-1 User-Defined Analysis 2-2
Analyzer Interface 6-1 User-Defined Filter 5-2
Example 6-7 User-Defined Simulation 10-3
Functions 6-2
G
D General functions 1-3
Debug mode 1-2 General Functions 1-2
Decode a Single Frame 3-1 ExitDLL 1-6
Analyzer Interface 3-1 Name 1-3
Example 3-6 RecallSetup 1-5
Functions 3-2 SaveSetup 1-4
DecodeFrameNames 3-3 GetStatus 10-12
DecodeFrameSetup 3-4
DecodeSingleFrame 3-5 I
DefaultFilterNames 5-4 Identifying DLLs in ini file 1-2
DoneSim 10-19
L
E LineStatLinkNames 9-3
Error Messages A-5 LineStatLinkResults 9-6
Examples LineStatLinkSetup 9-4
Background Record 6-7 LineStatLinkStarted 9-5
Decode a single Frame 3-6 LineStatLinkStopped 9-7
DLL0296.65 1
Link to Live Analysis Data 7-1 SimulationSetup 10-5

Analyzer Interface 7-1 SimulationStarted 10-6
Example 7-8 SimulationStopped 10-13
Functions 7-3 Skeletal Program 10-19
Link to Live Line Status Data 9-1 Software Interface 1-2
Analyzer Interface 9-1 StatisticsLinkNames 8-3
Example 9-7 StatisticsLinkResults 8-6
Functions 9-3 StatisticsLinkSetup 8-4
Link to Live Statistics Data 8-1 StatisticsLinkStarted 8-5
Analyzer Interface 8-1 StatisticsLinkStopped 8-7
Example 8-7 StopSim 10-18
Functions 8-3 Syntax A-9
List of Functions and Syntax A-9
U
N UDD
Name 1-3 Applications 1-1
Background 1-1
O General functions 1-3
OLProcessFrame 6-6 General Functions 1-2
OLProcessFramesExit 6-7 Software Interface 1-2
OLProcessFramesInit 6-5 UDD Sim1 10-2
OLProcessFramesNames 6-2 User-Defined Analysis
OLProcessFramesSetup 6-4 Analyzer Interface 2-1
Overview 1-1 Example 2-9
Functions 2-2
User-Defined Filter 5-1
P Analyzer Interface 5-1
Process all Frames in Capture Buffer Example 5-9
Analyzer Interface 4-1 Functions 5-2
Example 4-6 User-Defined Simulation
Functions 4-2 Analyzer Interface 10-1
Process All Frames in Capture Buffer 4-1 Functions 10-3
ProcessAllFramesExit 4-6 Introduction 10-1
ProcessAllFramesInit 4-4
ProcessAllFramesNames 4-2
ProcessAllFramesSetup 4-3
ProcessFrame 4-5
R
RecallSetup 1-5
Reference Guide A-1
S
SaveSetup 1-4
SendFrame 10-17
Setup 3-1
Setup button 2-1
SimulationCloseAll 10-16
SimulationDisplayPostExecution 10-15
SimulationFilterNotExist 10-10
SimulationGetFilter 10-9
SimulationGetSetupStrings 10-8
SimulationGetSummaryStrings 10-14
SimulationNames 10-4
2 DLL0296.65
Catalog No. 10-0122, Revision A RADCOM, 12.00

International Headquarters: RADCOM Ltd.
12 Hanechoshet Street, Tel-Aviv, 69710, Israel, Tel: +972-3-6455055, Fax: +972-3-6474681
US Office: RADCOM Equipment Inc.
575 Corporate Drive, Mahwah, NJ 07430, USA, Tel: (201) 529-2020, Fax: (201) 529-0808
Web site: www.radcom-inc.com

Programming Library Reference and User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Programming Library Reference and User Guide

Uploaded by

Copyright:

Available Formats

User Programming Library

Reference & User Guide

Applicable to the following protocol analyzers:

RADCOM Ltd., 2000

Chapter 2: User-Defined Analysis

Chapter 3: Decode a Single Frame

Chapter 4: Process All Frames in Capture Buffer

Chapter 5: User-Defined Filter

Chapter 6: Background Record

Chapter 7: Link to Live Analysis Data

Chapter 8: Link to Live Statistics Data

Chapter 9: Link to Live Line Status Data

Chapter 10: User-Defined Simulation

Appendix A: Reference Guide

Chapter 2 User-Defined Analyses

Chapter 3 Decode a Single Frame

Chapter 4 Process All Frames in Capture Buffer

Chapter 5 User-Defined Filter

Chapter 6 Background Record

Chapter 7 Link to Live Analysis Data

Chapter 8 Link to Live Statistics Data

Chapter 9 Link to Live Line Status Data

Chapter 10 User-Defined Simulation

Appendix A Reference Guide

Terminology and Conventions

Additional Technical Support

2. In 32-bit applications all functions should be declared as _export _stdcall

Values for the various capabilities are provided below:

// This section of the program contains the variable definitions.

// These variables are used to calculate the DLL results.

// Defines and variables for AAL type distribution.

// Init variables for AAL type analysis

// Init results array

// Find this AAL type in the analysis array

// If this AAL type doesn't exist in the array, add it.

Offset Offset in bits chosen by the user. The offset is 0 in the

When displayRADCOMDecode is true, the standard analyzer decode is displayed between

// This is the array of decode names that the DLL supports.

void _export _stdcall DecodeFrameSetup(char* /*decodeName*/,

if (strcmp(decodeName, "My Ethernet") == 0)

// There are no lines to add after the system decode.

Results of this user-defined DLL may be one of the following:

#define ATM_SAR_UNISupported 0x00010000

extern HANDLE dllInstance;

// Names of the user processes supported by the DLL.

// Hold the file name and handler.

// Prepare structure for the Windows' "open file" dialog.

strcpy(szFilter, "All Files (*.*)|*.*|Text Files (*.txt)|*.txt|");

// Try to open the file.

// Write the frame description to the file.

// Names of default filters that will be added to the system at

extern HANDLE dllInstance;

// List of all the filters defined by the user.

for (int i=0; i < numOfFilters; i++)

// Show the description of the default filters.

// Open dialog box in order to edit the filter.

int retDlg = DialogBoxParam(dllInstance, "LENGTH_FILTER",

// Delete the filter from the list.

// For length filter, check the length of the frame.

// Function for initializing the dialog window

// The name is not empty: edit an existing filter.

// Update the parameters of the filter in the dialog box.

itoa(filterPrms->fromLength, length, 10/*radix*/);

itoa(filterPrms->toLength, length, 10/*radix*/);

void _export _stdcall DecodeFrameSetup(char* /decodeName/,

strcpy(szFilter, "All Files (.)|.|Text Files (.txt)|.txt|");

itoa(filterPrms->fromLength, length, 10/radix/);

itoa(filterPrms->toLength, length, 10/radix/);

strcpy(szFilter, "All Files (.)|.|Text Files (.txt)|.txt|");

U32 /channel Num /,

U32 Chnl /channelNum /,