ZNA Custom DLL SDK  Version1.0.0
Network Analyser Extensions
Data Structures | Macros | Enumerations | Functions
RsVnaCustomDllInterface.h File Reference

Go to the source code of this file.

Data Structures

struct  RsVnaVersion
 Contains a version number in major release, minor release and patch level. More...
 
struct  RsVnaTaskId
 Contains an ID, consisting of the following four parameters, to identify a specific task. More...
 
struct  RsVnaComplex
 Contains a complex value in real and imaginary part. More...
 
struct  RsVnaTraceData
 Contains an human name (same as in SCPI) with a corresponding complex value for a specific measurement point. More...
 

Macros

#define RS_VNA_API   __declspec(dllexport)
 Usage as Dll export.
 
#define RS_VNA_DLL_INTERFACE_MAJOR_RELEASE   1
 Interface version in major release, minor release and patch level. More...
 
#define RS_VNA_DLL_INTERFACE_MINOR_RELEASE   0
 Interface version in major release, minor release and patch level. More...
 
#define RS_VNA_DLL_INTERFACE_PATCH_LEVEL   0
 Interface version in major release, minor release and patch level. More...
 
#define RS_VNA_MAX_CHAR_SIZE   512
 Contains the maximal length for the here used char types.
 

Enumerations

enum  ERsVnaMeasUnit {
  RS_VNA_UNIT, RS_VNA_GRAD, RS_VNA_SECONDS, RS_VNA_DECIBEL,
  RS_VNA_OHM, RS_VNA_SIEMENS, RS_VNA_VOLT, RS_VNA_WATT,
  RS_VNA_DBM, RS_VNA_DB_MICRO_V, RS_VNA_SECONDS_HZ, RS_VNA_DBC,
  RS_VNA_DBM_HZ, RS_VNA_DB_HZ, RS_VNA_HENRY, RS_VNA_FARAD,
  RS_VNA_AMPERE
}
 Contains all available units for the task type. More...
 
enum  ERsVnaInputType { RS_VNA_SAME, RS_VNA_LIST }
 Contains the input type. More...
 
enum  ERsVnaInterruptType { RS_VNA_CHANNEL, RS_VNA_SEGMENT, RS_VNA_DRIVING_PORT, RS_VNA_MEAS_POINT }
 Contains the custom DLL interrupt type, which describes how often an interrupt should be occurred. More...
 
enum  ERsVnaInterruptPosition { RS_VNA_NONE, RS_VNA_PRE, RS_VNA_POST, RS_VNA_BOTH }
 Contains the interrupt position, which describes where the interrupt should be occurred. More...
 

Functions

RS_VNA_API int RsVnaOnLoadDll ()
 
RS_VNA_API int RsVnaOnUnloadDll ()
 
RS_VNA_API int RsVnaGetVersion (struct RsVnaVersion *dllVersion, struct RsVnaVersion *interfaceVersion)
 
RS_VNA_API int RsVnaGetNumberOfTaskTypes (unsigned int *numberOfTaskTypes)
 
RS_VNA_API int RsVnaGetTaskTypes (const unsigned int numberOfTaskTypes, char **taskTypesList, char **additionalDefaultInput)
 
RS_VNA_API int RsVnaGetUnit (const struct RsVnaTaskId taskId, enum ERsVnaMeasUnit *unit)
 
RS_VNA_API int RsVnaGetNumberOfHumanNames (const struct RsVnaTaskId taskId, unsigned int *numberOfHumanNames)
 
RS_VNA_API int RsVnaGetTraceRequirements (const struct RsVnaTaskId taskId, enum ERsVnaInputType *inputType, const unsigned int numberOfHumanNames, char **humanNamesList)
 
RS_VNA_API int RsVnaCalculateTrace (const struct RsVnaTaskId taskId, const unsigned int position, const unsigned int numberOfSweepPoints, const unsigned int numberOfTraceData, const struct RsVnaTraceData **traceDataList, struct RsVnaComplex *outputValue)
 
RS_VNA_API int RsVnaGetInterruptRequests (const struct RsVnaTaskId taskId, enum ERsVnaInterruptPosition *interruptPositionForChannel, enum ERsVnaInterruptPosition *interruptPositionForSegment, enum ERsVnaInterruptPosition *interruptPositionForDrivingPort, enum ERsVnaInterruptPosition *interruptPositionForMeasPoint)
 
RS_VNA_API int RsVnaInterruptCallback (const struct RsVnaTaskId taskId, const char *deviceAddress, const unsigned int position, const unsigned int numberOfSweepPoints, const enum ERsVnaInterruptType interruptType, const enum ERsVnaInterruptPosition interruptPosition, struct RsVnaComplex *outputValueList, unsigned int *positionOfLastOutputValue)
 
RS_VNA_API int RsVnaGetErrorInfo (const int errorCode, char **errorText)
 

Detailed Description

Macro Definition Documentation

◆ RS_VNA_DLL_INTERFACE_MAJOR_RELEASE

#define RS_VNA_DLL_INTERFACE_MAJOR_RELEASE   1

Interface version in major release, minor release and patch level.

Major Release Version of this interface

◆ RS_VNA_DLL_INTERFACE_MINOR_RELEASE

#define RS_VNA_DLL_INTERFACE_MINOR_RELEASE   0

Interface version in major release, minor release and patch level.

Minor Release Version of this interface

◆ RS_VNA_DLL_INTERFACE_PATCH_LEVEL

#define RS_VNA_DLL_INTERFACE_PATCH_LEVEL   0

Interface version in major release, minor release and patch level.

Path Level of this interface

Enumeration Type Documentation

◆ ERsVnaInputType

Contains the input type.

Enumerator
RS_VNA_SAME 

If the input should be equal to the output, so no trace calculation is required (no call to method "RsVnaCalculateTrace()").

RS_VNA_LIST 

If a list of human names (same as in SCPI) of a specific task type is returned, required for the trace calculation later.

◆ ERsVnaInterruptPosition

Contains the interrupt position, which describes where the interrupt should be occurred.

Enumerator
RS_VNA_NONE 

If no interrupt is requested.

RS_VNA_PRE 

If the interrupt is requested before the measurement of the specified interrupt type.

RS_VNA_POST 

If the interrupt is requested after the measurement of the specified interrupt type.

RS_VNA_BOTH 

If the interrupt is requested before and after the measurement of the specified interrupt type.

◆ ERsVnaInterruptType

Contains the custom DLL interrupt type, which describes how often an interrupt should be occurred.

Enumerator
RS_VNA_CHANNEL 

If the interrupt is requested per channel.

RS_VNA_SEGMENT 

If the interrupt is requested per segment.

RS_VNA_DRIVING_PORT 

If the interrupt is requested per drive port.

RS_VNA_MEAS_POINT 

If the interrupt is requested per measurement point.

◆ ERsVnaMeasUnit

Contains all available units for the task type.

Enumerator
RS_VNA_UNIT 

No Unit.

RS_VNA_GRAD 

Degree.

RS_VNA_SECONDS 

Seconds.

RS_VNA_DECIBEL 

dB

RS_VNA_OHM 

Ohm.

RS_VNA_SIEMENS 

Siemens.

RS_VNA_VOLT 

Volt.

RS_VNA_WATT 

Watt.

RS_VNA_DBM 

dBm

RS_VNA_DB_MICRO_V 

dB / μV

RS_VNA_SECONDS_HZ 

s / Hz

RS_VNA_DBC 

dBc

RS_VNA_DBM_HZ 

dBm / Hz

RS_VNA_DB_HZ 

dB / Hz

RS_VNA_HENRY 

Henry.

RS_VNA_FARAD 

Farad.

RS_VNA_AMPERE 

Ampere.

Function Documentation

◆ RsVnaCalculateTrace()

RS_VNA_API int RsVnaCalculateTrace ( const struct RsVnaTaskId  taskId,
const unsigned int  position,
const unsigned int  numberOfSweepPoints,
const unsigned int  numberOfTraceData,
const struct RsVnaTraceData **  traceDataList,
struct RsVnaComplex outputValue 
)

Calculates the trace.

This function should provide the data used for the trace identified by "RsVnaTaskId". The function is called for each sweep point of the trace. The input data is provided as requested by "RsVnaGetNumberOfHumanNames" and "RsVnaGetTraceRequirements". The output is the complex trace value for the specified point. (If real values are desired set the imaginary part to zero.)

This function is optional, but if it is implemented, also the functions "RsVnaGetUnit", "RsVnaGetNumberOfHumanNames" and "RsVnaGetTraceRequirements" are required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in]positionContains the current measurement point within the sweep (1-based).
[in]numberOfSweepPointsContains the number of measurement points.
[in]numberOfTraceDataContains the number of trace data.
[in]traceDataListContains a list of trace data for the current measurement point.
[in,out]outputValueContains the calculated complex value for the current measurement point.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetErrorInfo()

RS_VNA_API int RsVnaGetErrorInfo ( const int  errorCode,
char **  errorText 
)

Gets detailed information of a specific error code.

This function is called always if any of the other functions returns a non zero return value. The return value of this function is passed as parameter here. The function shall return an error text which describes the reason for the occurred error. The message is displayed in the firmware.

This function is optional, if it is not implemented only the error code instead of an error text is displayed.

Parameters
[in]errorCodeContains a specific error code of which the information is requested.
[in,out]errorTextContains the error text corresponding to the passed error code.
Returns
0 if no error occurred, else no detailed error information could be received. (Not zero return values do not trigger a call to this function).

◆ RsVnaGetInterruptRequests()

RS_VNA_API int RsVnaGetInterruptRequests ( const struct RsVnaTaskId  taskId,
enum ERsVnaInterruptPosition interruptPositionForChannel,
enum ERsVnaInterruptPosition interruptPositionForSegment,
enum ERsVnaInterruptPosition interruptPositionForDrivingPort,
enum ERsVnaInterruptPosition interruptPositionForMeasPoint 
)

Gets the interrupt requests.

For the given "RsVnaTaskId" here the preparations for the later calls to "RsVnaInterruptCallback" are done. The firmware must know at which point during the measurements a call of "RsVnaInterruptCallback" should occur. At the defined points the firmware stops the measurement sequence and calls "RsVnaInterruptCallback". After the function returned the sequence proceeds. There are four options. These are identical with the locations for Trigger Signals specified in the manual. Some examples for a channel with drive port 1 and drive port 2 and 7 sweep points:

Drive port: 1 1 1 1 1 1 1 2 2 2 2 2 2 2
Position: 1 2 3 4 5 6 7 1 2 3 4 5 6 7
Channel Both: x| | | |x
Drive Port Both: x| |x | | // for the selection of port 1 as driving
Drive Port Both: | | x| |x // for the selection of port 2 as driving
Drive Port Both: x| |x x| |x // for a permanent selection
Meas Point Both: x|x x x x x x x x x x x x|x | | // for the selection of port 1 as driving
Meas Point Both: | | x|x x x x x x x x x x x x|x // for the selection of port 2 as driving
Meas Point Both: x|x x x x x x x x x x x x|x x|x x x x x x x x x x x x|x // for a permanent selection

If no interrupt is specified the function "RsVnaInterruptCallback" is not called.

This function is optional, but if it is implemented and an interrupt is specified, also the function "RsVnaInterruptCallback" is required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in,out]interruptPositionForChannelContains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Channel".
[in,out]interruptPositionForSegmentContains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Segment".
[in,out]interruptPositionForDrivingPortContains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Driving Port".
[in,out]interruptPositionForMeasPointContains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Measurement Point".
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetNumberOfHumanNames()

RS_VNA_API int RsVnaGetNumberOfHumanNames ( const struct RsVnaTaskId  taskId,
unsigned int *  numberOfHumanNames 
)

Gets the number of human names.

For a given "RsVnaTaskId" a certain number of input traces can be requested from the firmware (e.g. if the DLL calculates the ratio of two waves this function should return "2" for the two waves). The human name is the same name used by the SCPI interface to request measurement. The value returned by this function is used as input for "RsVnaGetTraceRequirements".

This function is optional, but if it is implemented, also the functions "RsVnaGetUnit", "RsVnaGetTraceRequirements" and "RsVnaCalculateTrace" are required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in,out]numberOfHumanNamesContains the number of human names.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetNumberOfTaskTypes()

RS_VNA_API int RsVnaGetNumberOfTaskTypes ( unsigned int *  numberOfTaskTypes)

Gets the number of task type names.

The DLL can define a number of task types identified by a name (see "RsVnaGetTaskTypes"). This function returns the total number of these types. The returned value is used as input parameter for "RsVnaGetTaskTypes".

This function is mandatory and must be implemented.

Parameters
[in,out]numberOfTaskTypesContains the number of task type names.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetTaskTypes()

RS_VNA_API int RsVnaGetTaskTypes ( const unsigned int  numberOfTaskTypes,
char **  taskTypesList,
char **  additionalDefaultInput 
)

Gets the task type names.

This method defines the task types available by the DLL. A task to measure for the DLL is identified by the struct "RsVnaTaskId". The strings returned by this function define the entries in RsVnaTaskId::taskType passed later to the DLL. The concept for the task type is similar to the concept of a task type wave, ratio or S-Parameter in the firmware. Also for external devices task types are used. These allow to visualize data even if it is not the main use case. In task types and additional default input the characters "*<>?|/: are NOT allowed.

This function is mandatory and must be implemented.

Parameters
[in]numberOfTaskTypesContains the number of task type names as provided by the method "RsVnaGetNumberOfTaskTypes()".
[in,out]taskTypesListContains a list of names for the task types the DLL can handle with units. These task type names are available in the UI and will be provided to the DLL to identify the selection of the user.
[in,out]additionalDefaultInputContains the default text for the additional input text field in the UI (e.g. "Ch1" for channel identification).
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetTraceRequirements()

RS_VNA_API int RsVnaGetTraceRequirements ( const struct RsVnaTaskId  taskId,
enum ERsVnaInputType inputType,
const unsigned int  numberOfHumanNames,
char **  humanNamesList 
)

Gets the trace requirements.

This Function does the preparations for the calculation of a trace. The function is called for all traces used. THe trace is identified by the "RsVnaTaskId". The firmware must know which data it should be provided for this calculation (e.g. if the desired calculation is the ratio of two waves, these two waves must be specified here). This includes data which might originate from the DLL provided by RsVnaInterruptCallback. The specification is done by the
"ERsVnaInputType" and a list of human names:

  • If no calculation is required the "ERsVnaInputType" SAME shall be used (e.g. if the trace shall display data provided by RsVnaInterruptCallback)
  • Otherwise "ERsVnaInputType" LIST must be selected to provide the names. These names are the same as used for the traces in the SCPI interface of the firmware. Most trace names accepted via SCPI are also available here:
    • Not available are noise figure and 2D compression point measurements
    • Names from DLL packages are accepted. They are only forwarded to the "Device Control" (2.4) part. The "Trace Calculation" (2.3) is not done. This is useful to request and use data from external devices in addition to other quantities or do some calculation.

This function is optional, but if it is implemented, also the functions "RsVnaGetUnit", "RsVnaGetNumberOfHumanNames" and "RsVnaCalculateTrace" are required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in,out]inputTypeContains the input type.
[in]numberOfHumanNamesContains the number of human names as provided by the method "RsVnaGetNumberOfHumanNames()".
[in,out]humanNamesListContains a list of human names (same as in SCPI), required for the trace calculation later.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetUnit()

RS_VNA_API int RsVnaGetUnit ( const struct RsVnaTaskId  taskId,
enum ERsVnaMeasUnit unit 
)

Gets the corresponding unit for a specific task type.

Associated with each task type is a unit. This unit is used by the firmware to interpret the values returned by "RsVnaCalculateTrace". The calculation of derived quantities depends on this unit.

This function is optional, but it must be implemented if any Task shall be used as trace. In this case you also need the functions "RsVnaGetNumberOfHumanNames", "RsVnaGetTraceRequirements" and "RsVnaCalculateTrace" are required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in,out]unitContains the corresponding unit for the passed task ID.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaGetVersion()

RS_VNA_API int RsVnaGetVersion ( struct RsVnaVersion dllVersion,
struct RsVnaVersion interfaceVersion 
)

Gets the DLL version and the interface version in major release, minor release and patch level.

This function provides information about the versions to the firmware.

  • The DLL version is only informative. It is displayed in the GUI. Developers can use it to distinguish different versions of their DLL.
  • The interface version should be the version defined by RS_VNA_DLL_INTERFACE_XXX. It identifies the implemented interface to the firmware. Any other value returned might create undefined behavior and firmware crashes.

This function is mandatory and must be implemented.

Parameters
[in,out]dllVersionContains the internal version of the DLL.
[in,out]interfaceVersionContains the version of the RsVnaCustomDllInterface which was used to compile the DLL.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaInterruptCallback()

RS_VNA_API int RsVnaInterruptCallback ( const struct RsVnaTaskId  taskId,
const char *  deviceAddress,
const unsigned int  position,
const unsigned int  numberOfSweepPoints,
const enum ERsVnaInterruptType  interruptType,
const enum ERsVnaInterruptPosition  interruptPosition,
struct RsVnaComplex outputValueList,
unsigned int *  positionOfLastOutputValue 
)

Calculates the interrupt callback.

This function is called at the positions defined by "RsVnaGetInterruptRequests" for the given "RsVnaTaskId". The call is designed to control additional devices. This can be used to control the devices or read data. There are two types of callbacks:

  • for permanent usage: RsVnaTaskId::drivingPort is zero In this case no return values are expected. "outputValueList" and "positionOfLastOutputValue" cannot be accessed.
  • for usage when one port is driving: RsVnaTaskId::drivingPort is unequal zero In this case return values are expected. The parameter "positionOfLastOutputValue" allows the DLL to control the point up to which the data in "outputValueList" is inserted. The firmware will only use the values in "outputValueList" up to the position defined by "outputValueList". The "positionOfLastOutputValue" is assumed to be equal to the number of sweep points with the last call in the channel to avoid a blocking.

This function is optional, but if it is implemented, also the function "RsVnaGetInterruptRequests" is required.

Parameters
[in]taskIdContains the task ID to identify the corresponding task type.
[in]deviceAddressContains the device address of an external device.
[in]positionContains the current measurement point within the sweep (1-based). The position can also be 0 in case of: interrupt type "Channel" and interrupt "PRE" or "BOTH". The position can also be (numberOfSweepPoints + 1) in case of: interrupt type "Channel" and interrupt "POST" or "BOTH".
[in]numberOfSweepPointsContains the number of measurement points.
[in]interruptTypeContains the interrupt type, which describes how often an interrupt should be occurred.
[in]interruptPositionContains the interrupt position, which describes where the interrupt should be occurred.
[in,out]outputValueListContains a list of calculated complex values. The number of calculated complex values corresponds to the number of measurement points which are relevant for the current interrupt callback. This pointer has numberOfSweepPoints entries (In case of permanent usage this is zero - do not use).
[in,out]positionOfLastOutputValueContains the measurement point of the last calculated complex value.
Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaOnLoadDll()

RS_VNA_API int RsVnaOnLoadDll ( )

Is called when loading the DLL.

Calls to this function occur when starting the firmware or adding/removing DLLs.

This function is optional.

Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".

◆ RsVnaOnUnloadDll()

RS_VNA_API int RsVnaOnUnloadDll ( )

Is called when unloading the DLL.

Calls to this function occur when stopping the firmware or adding/removing DLLs.

This function is optional.

Returns
0 if no error occurred, else an error code to identify the occurred error. A detailed error information is provided by the method "RsVnaGetErrorInfo()".