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 device id (IDKIND_DEVICEID), e.g.:
TpDate_t dwNumber = LstDevGetCalibrationDate( IDKIND_DEVICEID , ID_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	LstGetDeviceCanOpen (uint32_t dwIdKind, uint32_t dwId, uint32_t dwDeviceType)
	Check whether the listed device can be opened. More...

uint32_t	LstGetDeviceProductId (uint32_t dwIdKind, uint32_t dwId)
	Get the product id of the listed device. More...

uint32_t	LstGetDeviceName (uint32_t dwIdKind, uint32_t dwId, char *pBuffer, uint32_t dwBufferLength)
	Get the full name of the listed device. More...

uint32_t	LstGetDeviceNameShort (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	LstGetDeviceSerialNumber (uint32_t dwIdKind, uint32_t dwId)
	Get the serial number of the listed device. More...

uint32_t	LstGetDeviceTypes (uint32_t dwIdKind, uint32_t dwId)
	Get the device types of the listed device. More...

Function Documentation

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

Check whether the listed device can be opened.

Parameters

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.
dwDeviceType	A device type.

Returns: BOOL8_TRUE if the device can be opened or BOOL8_FALSE if not.

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_DEVICE_ID	There is no device with the requested device ID.
INVALID_DEVICE_TYPE	The device type is invalid.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

Since: 0.4.0

uint32_t LstGetDeviceProductId	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Get the product id of the listed device.

Parameters

dwIdKind	An id kind.
dwId	A device index, Device 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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not support reading a product id.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

Since: 0.4.0

uint32_t LstGetDeviceName	(	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

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.
pBuffer	A pointer to a buffer for the name.
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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not support reading a name.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

See also: LstGetDeviceNameShort; LstDevGetNameShortest

Example: uint32_t dwLength = LstGetDeviceName( dwIdKind , dwId , NULL , 0 ) + 1; // Add one for the terminating zero

char* sName = malloc( sizeof( char ) * dwLength );

dwLength = LstGetDeviceName( dwIdKind , dwId , sName , dwLength );

printf( "LstGetDeviceName = %s\n" , sName );

free( sName );

Since: 0.4.0

uint32_t LstGetDeviceNameShort	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		char *	pBuffer,
		uint32_t	dwBufferLength
	)

Get the short name of the listed device.

E.g. HS5-530XMS

Parameters

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.
pBuffer	A pointer to a buffer for the name.
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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not support reading a name.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

See also: LstGetDeviceName; LstDevGetNameShortest

Example: uint32_t dwLength = LstGetDeviceNameShort( dwIdKind , dwId , NULL , 0 ) + 1; // Add one for the terminating zero

char* sNameShort = malloc( sizeof( char ) * dwLength );

dwLength = LstGetDeviceNameShort( dwIdKind , dwId , sNameShort , dwLength );

printf( "LstGetDeviceNameShort = %s\n" , sNameShort );

free( sNameShort );

Since: 0.4.0

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

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.
pBuffer	A pointer to a buffer for the name.
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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not support reading a name.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

See also: LstGetDeviceName; LstGetDeviceNameShort

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

dwIdKind	An id kind.
dwId	A device index, Device 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_DEVICE_ID	There is no device with the requested device 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.
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

dwIdKind	An id kind.
dwId	A device index, Device 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_DEVICE_ID	There is no device with the requested device 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.
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

dwIdKind	An id kind.
dwId	A device index, Device 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_DEVICE_ID	There is no device with the requested device 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.
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

dwIdKind	An id kind.
dwId	A device index, Device 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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not have a calibration date.
INVALID_VALUE	The value of dwIdKind is invalid.
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 LstGetDeviceSerialNumber	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Get the serial number of the listed device.

Parameters

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.

Returns: The serial 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_DEVICE_ID	There is no device with the requested device ID.
NOT_SUPPORTED	The indicated device does not support reading a serial number.
INVALID_VALUE	The value of dwIdKind is invalid.
SUCCESS	The function executed successfully.

Since: 0.4.0

uint32_t LstGetDeviceTypes	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Get the device types of the listed device.

Parameters

dwIdKind	An id kind.
dwId	A device index, Device ID or serial number identifying the device to check, as specified by `dwIdKind`.

Returns: OR-ed mask of device types.

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_DEVICE_ID	There is no device with the requested device ID.
INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
SUCCESS	The function executed successfully.

Example: uint32_t dwDeviceTypes = LstGetDeviceTypes( 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.4.0

Description

Methods to identify the required device

Modules

Functions

Function Documentation