LibTiePie  0.9.8
Library for interfacing TiePie engineering instruments
Listed devices

Description

Functions to retrieve information from the listed devices.

Before opening a device, device specific information can be retrieved. This information can help opening the required device, when multiple devices are available in the list.

Methods to identify the required device

Three different methods to identify a device are available:

Modules

 Combined devices
 Functions to retrieve information from the individual devices in combined devices.
 

Functions

bool8_t LstDevCanOpen (uint32_t dwIdKind, uint32_t dwId, uint32_t dwDeviceType)
 Check whether the listed device can be opened. More...
 
uint32_t LstDevGetProductId (uint32_t dwIdKind, uint32_t dwId)
 Get the product id of the listed device. More...
 
uint32_t LstDevGetName (uint32_t dwIdKind, uint32_t dwId, char *pBuffer, uint32_t dwBufferLength)
 Get the full name of the listed device. More...
 
uint32_t LstDevGetNameShort (uint32_t dwIdKind, uint32_t dwId, char *pBuffer, uint32_t dwBufferLength)
 Get the short name of the listed device. More...
 
uint32_t LstDevGetNameShortest (uint32_t dwIdKind, uint32_t dwId, char *pBuffer, uint32_t dwBufferLength)
 Get the short name of the listed device wihout model postfix. More...
 
TpVersion_t LstDevGetDriverVersion (uint32_t dwIdKind, uint32_t dwId)
 Get the version number of the driver currently used by the listed device. More...
 
TpVersion_t LstDevGetRecommendedDriverVersion (uint32_t dwIdKind, uint32_t dwId)
 Get the version number of the recommended driver for the listed device. More...
 
TpVersion_t LstDevGetFirmwareVersion (uint32_t dwIdKind, uint32_t dwId)
 Get the version number of the firmware currently used by the listed device. More...
 
TpDate_t LstDevGetCalibrationDate (uint32_t dwIdKind, uint32_t dwId)
 Get the calibration date of the listed device. More...
 
uint32_t LstDevGetSerialNumber (uint32_t dwIdKind, uint32_t dwId)
 Get the serial number of the listed device. More...
 
uint32_t LstDevGetIPv4Address (uint32_t dwIdKind, uint32_t dwId)
 Get the IPv4 address of the listed device. More...
 
uint16_t LstDevGetIPPort (uint32_t dwIdKind, uint32_t dwId)
 Get the IP port number of the listed device. More...
 
bool8_t LstDevHasServer (uint32_t dwIdKind, uint32_t dwId)
 Check whether the listed device is connected to a server. More...
 
LibTiePieHandle_t LstDevGetServer (uint32_t dwIdKind, uint32_t dwId)
 Get the server handle of the server the listed device is connected to. More...
 
uint32_t LstDevGetTypes (uint32_t dwIdKind, uint32_t dwId)
 Get the device types of the listed device. More...
 

Function Documentation

bool8_t LstDevCanOpen ( uint32_t  dwIdKind,
uint32_t  dwId,
uint32_t  dwDeviceType 
)

Check whether the listed device can be opened.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[in]dwDeviceTypeA device type.
Returns
BOOL8_TRUE if the device can be opened or BOOL8_FALSE if not.
Status values
INITIALIZATION_FAILED The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE The currently used firmware is not supported .
INVALID_DRIVER The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
INVALID_DEVICE_TYPE The device type is invalid.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.5
uint32_t LstDevGetProductId ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the product id of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The product id of the listed device.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a product id.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.5
uint32_t LstDevGetName ( uint32_t  dwIdKind,
uint32_t  dwId,
char *  pBuffer,
uint32_t  dwBufferLength 
)

Get the full name of the listed device.

E.g. Handyscope HS5-530XMS

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]pBufferA pointer to a buffer for the name.
[in]dwBufferLengthThe length of the buffer, in bytes.
Returns
The length of the name in bytes, excluding terminating zero.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a name.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
LstDevGetNameShort
LstDevGetNameShortest
Example
uint32_t dwLength = LstDevGetName( dwIdKind , dwId , NULL , 0 ) + 1; // Add one for the terminating zero
char* sName = malloc( sizeof( char ) * dwLength );
dwLength = LstDevGetName( dwIdKind , dwId , sName , dwLength );
printf( "LstDevGetName = %s\n" , sName );
free( sName );
Since
0.5
uint32_t LstDevGetNameShort ( uint32_t  dwIdKind,
uint32_t  dwId,
char *  pBuffer,
uint32_t  dwBufferLength 
)

Get the short name of the listed device.

E.g. HS5-530XMS

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]pBufferA pointer to a buffer for the name.
[in]dwBufferLengthThe length of the buffer, in bytes.
Returns
The length of the name in bytes, excluding terminating zero.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a name.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
LstDevGetName
LstDevGetNameShortest
Example
uint32_t dwLength = LstDevGetNameShort( dwIdKind , dwId , NULL , 0 ) + 1; // Add one for the terminating zero
char* sNameShort = malloc( sizeof( char ) * dwLength );
dwLength = LstDevGetNameShort( dwIdKind , dwId , sNameShort , dwLength );
printf( "LstDevGetNameShort = %s\n" , sNameShort );
free( sNameShort );
Since
0.5
uint32_t LstDevGetNameShortest ( uint32_t  dwIdKind,
uint32_t  dwId,
char *  pBuffer,
uint32_t  dwBufferLength 
)

Get the short name of the listed device wihout model postfix.

E.g. HS5

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]pBufferA pointer to a buffer for the name.
[in]dwBufferLengthThe length of the buffer, in bytes.
Returns
The length of the name in bytes, excluding terminating zero.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a name.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
LstDevGetName
LstDevGetNameShort
Example
uint32_t dwLength = LstDevGetNameShortest( dwIdKind , dwId , NULL , 0 ) + 1; // Add one for the terminating zero
char* sNameShortest = malloc( sizeof( char ) * dwLength );
dwLength = LstDevGetNameShortest( dwIdKind , dwId , sNameShortest , dwLength );
printf( "LstDevGetNameShortest = %s\n" , sNameShortest );
free( sNameShortest );
Since
0.4.4
TpVersion_t LstDevGetDriverVersion ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the version number of the driver currently used by the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The version number of the driver currently used by the listed device, or zero if no driver version is available.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a driver version or does not require a driver.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.4.1
TpVersion_t LstDevGetRecommendedDriverVersion ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the version number of the recommended driver for the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The version number of the recommended driver for the listed device, or zero if no driver version is available.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a recommended driver version or does not require a driver.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.4.3
TpVersion_t LstDevGetFirmwareVersion ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the version number of the firmware currently used by the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The version number of the firmware currently used firmware by the listed device, or zero if no firmware version is available.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a firmware version or does not require firmware.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.4.1
TpDate_t LstDevGetCalibrationDate ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the calibration date of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The calibration date of the listed device, or zero if no calibration date is available.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not have a calibration date.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Example
uint16_t wYear = TPDATE_YEAR( Date );
uint8_t byMonth = TPDATE_MONTH( Date );
uint8_t byDay = TPDATE_DAY( Date );
printf( "LstDevGetCalibrationDate = %u-%u-%u\n" , wYear , byMonth , byDay );
Since
0.4.1
uint32_t LstDevGetSerialNumber ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the serial number of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The serial number of the listed device.
Status values
INITIALIZATION_FAILED The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE The currently used firmware is not supported .
INVALID_DRIVER The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device does not support reading a serial number.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.5
uint32_t LstDevGetIPv4Address ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the IPv4 address of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The IPv4 address of the listed device.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device is not a network device.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.9
uint16_t LstDevGetIPPort ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the IP port number of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
The IP port number of the listed device.
Status values
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
NOT_SUPPORTED The indicated device is not a network device.
INVALID_VALUE The value of dwIdKind is invalid.
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.9
bool8_t LstDevHasServer ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Check whether the listed device is connected to a server.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
BOOL8_TRUE if the device isconnected to a server, BOOL8_FALSE otherwise.
Since
0.9
LibTiePieHandle_t LstDevGetServer ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the server handle of the server the listed device is connected to.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
A server handle, or LIBTIEPIE_HANDLE_INVALID on error.
Since
0.9
uint32_t LstDevGetTypes ( uint32_t  dwIdKind,
uint32_t  dwId 
)

Get the device types of the listed device.

Parameters
[in]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
Returns
OR-ed mask of device types.
Status values
INITIALIZATION_FAILED The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE The currently used firmware is not supported .
INVALID_DRIVER The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_DEVICE_INDEX The device index is invalid, must be < LstGetCount().
INVALID_DEVICE_SERIALNUMBERThere is no device with the requested serial number.
INVALID_PRODUCT_ID There is no device with the requested product ID.
INVALID_VALUE The value of dwIdKind is invalid.
INVALID_DRIVER The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
LIBRARY_NOT_INITIALIZED The library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Example
uint32_t dwDeviceTypes = LstDevGetTypes( dwIdKind , dwId );
// Test all device types:
if( dwDeviceTypes & DEVICETYPE_OSCILLOSCOPE )
printf( "DEVICETYPE_OSCILLOSCOPE\n" );
if( dwDeviceTypes & DEVICETYPE_GENERATOR )
printf( "DEVICETYPE_GENERATOR\n" );
if( dwDeviceTypes & DEVICETYPE_I2CHOST )
printf( "DEVICETYPE_I2CHOST\n" );
Since
0.5