ZNA Custom DLL SDK
Version1.0.0
Network Analyser Extensions
|
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) |
#define RS_VNA_DLL_INTERFACE_MAJOR_RELEASE 1 |
Interface version in major release, minor release and patch level.
Major Release Version of this interface
#define RS_VNA_DLL_INTERFACE_MINOR_RELEASE 0 |
Interface version in major release, minor release and patch level.
Minor Release Version of this interface
#define RS_VNA_DLL_INTERFACE_PATCH_LEVEL 0 |
Interface version in major release, minor release and patch level.
Path Level of this interface
enum ERsVnaInputType |
Contains the input type.
Contains the interrupt position, which describes where the interrupt should be occurred.
enum ERsVnaInterruptType |
Contains the custom DLL interrupt type, which describes how often an interrupt should be occurred.
enum ERsVnaMeasUnit |
Contains all available units for the task type.
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.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in] | position | Contains the current measurement point within the sweep (1-based). |
[in] | numberOfSweepPoints | Contains the number of measurement points. |
[in] | numberOfTraceData | Contains the number of trace data. |
[in] | traceDataList | Contains a list of trace data for the current measurement point. |
[in,out] | outputValue | Contains the calculated complex value for the current measurement point. |
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.
[in] | errorCode | Contains a specific error code of which the information is requested. |
[in,out] | errorText | Contains the error text corresponding to the passed error code. |
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:
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.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in,out] | interruptPositionForChannel | Contains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Channel". |
[in,out] | interruptPositionForSegment | Contains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Segment". |
[in,out] | interruptPositionForDrivingPort | Contains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Driving Port". |
[in,out] | interruptPositionForMeasPoint | Contains the interrupt position, which describes where the interrupt should be occurred, for the interrupt type "Measurement Point". |
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.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in,out] | numberOfHumanNames | Contains the number of human names. |
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.
[in,out] | numberOfTaskTypes | Contains the number of task type names. |
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.
[in] | numberOfTaskTypes | Contains the number of task type names as provided by the method "RsVnaGetNumberOfTaskTypes()". |
[in,out] | taskTypesList | Contains 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] | additionalDefaultInput | Contains the default text for the additional input text field in the UI (e.g. "Ch1" for channel identification). |
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:
This function is optional, but if it is implemented, also the functions "RsVnaGetUnit", "RsVnaGetNumberOfHumanNames" and "RsVnaCalculateTrace" are required.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in,out] | inputType | Contains the input type. |
[in] | numberOfHumanNames | Contains the number of human names as provided by the method "RsVnaGetNumberOfHumanNames()". |
[in,out] | humanNamesList | Contains a list of human names (same as in SCPI), required for the trace calculation later. |
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.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in,out] | unit | Contains the corresponding unit for the passed task ID. |
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.
This function is mandatory and must be implemented.
[in,out] | dllVersion | Contains the internal version of the DLL. |
[in,out] | interfaceVersion | Contains the version of the RsVnaCustomDllInterface which was used to compile the DLL. |
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:
This function is optional, but if it is implemented, also the function "RsVnaGetInterruptRequests" is required.
[in] | taskId | Contains the task ID to identify the corresponding task type. |
[in] | deviceAddress | Contains the device address of an external device. |
[in] | position | Contains 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] | numberOfSweepPoints | Contains the number of measurement points. |
[in] | interruptType | Contains the interrupt type, which describes how often an interrupt should be occurred. |
[in] | interruptPosition | Contains the interrupt position, which describes where the interrupt should be occurred. |
[in,out] | outputValueList | Contains 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] | positionOfLastOutputValue | Contains the measurement point of the last calculated complex value. |
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.
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.