| Using VISA.NET > API Structure > The Native Access API |
The VISA.NET Native Access API is designed to give calling programs limited access to the underlying VISA C API. The underlying API for Keysight VISA.NET is typically Keysight VISA, but it is possible to use a different vendor's VISA under Keysight VISA.NET by installing that vendor's VISA as the primary VISA. Refer to the Keysight IO Libraries Suite Help for information on primary and secondary VISA.
The primary use for the Native Access API is to get access to VISA error information. Exceptions that reflect failures in the underlying VISA C are reported using the NativeVisaException exception class. You can cross-reference error status codes reported by this exception (refer to the NativeVisaException.ErrorCode property) to values defined in the NativeErrorCode class to identify the VISA error. Your program will need to use the Native Access API whenever VISA.NET throws a NativeVisaException.
Other than the NativeVisaException class, there is no real reason to use the Native Access API in Keysight VISA.NET, and Keysight recommends against it. However, it is provided on session classes for completeness. It is not provided on the ResourceManager class (for resource manager attributes) because the resource manager handle is not usually exposed to the calling program.
There are several uses for the Native Access API:
It allows calling programs to access session-related attributes that are specific to the underlying implementation. Note that Keysight has exposed all of the customer relevant attributes that are specific to Keysight VISA in the Keysight VISA.NET API, and so calling programs should not need to use the Native Access API for this unless Keysight VISA.NET is using another vendor's VISA (i.e., Keysight VISA is secondary).
It allows calling programs to access a session-related attribute that may have a different value from the corresponding VISA.NET property. For example, the session-related attribute VI_ATTR_RSRC_IMPL_VERSION returns the version of the Keysight VISA C DLL, while the corresponding VISA.NET property ResourceImplementationVersion returns the version of the Keysight VISA.NET assembly. Since these will usually be the same, calling programs should not need to use the Native Access API for this. There are several similar attributes.
It allows calling programs to try to access session-related attributes that are not implemented as properties in the VISA.NET API, but are implemented in methods instead. In general, there are good reasons for associating these attributes with .NET methods rather than properties, usually related to making sure that the right things happen in the right order, and for this reason, calling programs will be safer if they do not use the Native Access API for this.
It allows calling programs to try to access session-related attributes that are not meaningful in VISA.NET because it is structured differently. For example, the TCPIP Connect event attributes are not implemented because VISA.NET does not define a TCPIP Connect event. The same goes for attributes to SERVANT sessions.
It allows calling programs to access custom events that are vendor-specific. Since Keysight VISA does not define any custom events, this scenario only applies when Keysight VISA.NET is using another vendor's VISA (i.e., Keysight VISA is secondary).
The Ivi.Visa namespace defines several Native Access features:
NativeVisaException - Use this together with NativeErrorCode to determine the cause of the underlying VISA C exception.
NativeErrorCode – Use this together with NativeVisaException to determine the cause of the underlying VISA C exception.
INativeVisaSession - Cast any class that derives from VisaSession to INativeVisaSession to use this interface. When using this interface, use only the Get/SetAttribute methods and avoid the event methods (disable, discard, enable, and wait on event).
NativeVisaAttribute - Use this together with INativeVisaSession. NativeVisaAttribute is an enumeration whose members correspond to VISA C attributes. Use this enumeration to make code written with INativeVisaSession more readable.
INativeVisaEventArgs - This interface is only returned from INativeVisaSession.WaitOnEvent. It is not used anywhere else in the Keysight VISA.NET API.
The Keysight.Visa namespace defines several Native Access features:
IKeysightNativeVisaSession - Cast any class that derives from VisaSession to IKeysightNativeVisaSession to use this interface. Use this interface together with Keysight attribute enumerations to get and set VISA attribute values. There is one Keysight attribute enumeration for each type of attribute (string; Boolean; 8, 16, 32, and 64-bit integers; and reals), so that use of the get attribute and set attribute methods is safer with regard to basic types. The methods defined in this interface may succeed or fail, but they will not create memory access problems.
KeysightAttribute<type>, where type is String, Boolean, Byte, Int16, Int32, or Int64 - These attribute enumerations are similar to those defined in Ivi.Visa.NativeVisaAttribute, but are separated by type and include all of the Keysight-specific attributes. These enumerations are only used in the IKeysightNativeVisaSession interface.
KeysightVisaEventArgs - When using INativeVisaSession.WaitOnEvent, you can cast the INativeVisaEventArgs reference returned by WaitOnEvent to KeysightVisaEventArgs to access methods that get and set event properties for that event. This class is never used directly in the VISA.NET API.
Aside from the VISA functions used to access native VISA C events and attributes, as defined in the VISA.NET Native Access API, there is no direct access to VISA C methods in the Keysight VISA.NET API. Some significant VISA C functions are never called directly by VISA.NET, including functions that read and write to files and Formatted I/O functions like viPrintf and viScanf.
VISA.NET replaces the Formatted I/O features of VISA with a completely new and standard Formatted I/O interface and implementation, which is installed with the IVI Foundation VISA.NET Shared Components as a part of the Keysight IO Libraries Suite. Keysight VISA.NET uses the IVI implementation.
The following VISA attributes may only be accessed using the Native Access features of Keysight VISA.NET:
VISA attributes that are not available when using the Native Access features of Keysight VISA.NET: