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:

• Identify by device list index (IDKIND_INDEX), e.g.:

  TpDate_t dwNumber = LstDevGetCalibrationDate( IDKIND_INDEX , 4 ); // Get the calibration date from the device at list index 4.

• Identify by serial number (IDKIND_SERIALNUMBER), e.g.:

  TpDate_t dwNumber = LstDevGetCalibrationDate( IDKIND_SERIALNUMBER , 22110 ); // Get the calibration date from the device with serial number 22110.

• Identify by product id (IDKIND_PRODUCTID), e.g.:

  TpDate_t dwNumber = LstDevGetCalibrationDate( IDKIND_PRODUCTID , PID_HS5 ); // Get the calibration date from the first Handyscope HS5 in the device list.

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]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[in]	dwDeviceType	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]	pBuffer	A pointer to a buffer for the name.
[in]	dwBufferLength	The 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]	pBuffer	A pointer to a buffer for the name.
[in]	dwBufferLength	The 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the device to check, as specified by dwIdKind.
[out]	pBuffer	A pointer to a buffer for the name.
[in]	dwBufferLength	The 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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

TpDate_t Date    = LstDevGetCalibrationDate( hDevice );
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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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]	dwIdKind	An id kind.
[in]	dwId	A 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]	dwIdKind	An id kind.
[in]	dwId	A 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]	dwIdKind	An id kind.
[in]	dwId	A 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_SERIALNUMBER	There 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