Combined devices

Description

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

Methods to identify the required contained device in a combined device

To identify a contained device in a combined device, the combined device must be adressed and the also the contained device in it. Three different methods to identify a contained device in a combined are available:

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

  TpDate_t dwNumber = LstCbDevGetCalibrationDate( IDKIND_INDEX , 4, 27912 ); // Get the calibration date from the continaed device with serial number 27912 in the combined device at list index 4.

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

  TpDate_t dwNumber = LstCbDevGetCalibrationDate( IDKIND_SERIALNUMBER , 1, 27912 ); // Get the calibration date from the continaed device with serial number 27912 in the combined device with serial number 1.

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

  TpDate_t dwNumber = LstCbDevGetCalibrationDate( IDKIND_PRODUCTID , PID_COMBI, 27912 ); // Get the calibration date from the continaed device with serial number 27912 in the first combined device in the device list.

Functions
uint32_t	LstDevGetContainedSerialNumbers (uint32_t dwIdKind, uint32_t dwId, uint32_t *pBuffer, uint32_t dwBufferLength)
	Get the serial numbers of the individual devices contained in a combined device. More...
uint32_t	LstCbDevGetProductId (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber)
	Get the product id of a device contained in a combined device. More...
uint32_t	LstCbDevGetName (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber, char *pBuffer, uint32_t dwBufferLength)
	Get the full name of a device contained in a combined device. More...
uint32_t	LstCbDevGetNameShort (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber, char *pBuffer, uint32_t dwBufferLength)
	Get the short name of a device contained in a combined device. More...
uint32_t	LstCbDevGetNameShortest (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber, char *pBuffer, uint32_t dwBufferLength)
	Get the short name without model postfix of a device contained in a combined device. More...
TpVersion_t	LstCbDevGetDriverVersion (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber)
	Get the driver version of a device contained in a combined device. More...
TpVersion_t	LstCbDevGetFirmwareVersion (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber)
	Get the firmware version of a device contained in a combined device. More...
TpDate_t	LstCbDevGetCalibrationDate (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber)
	Get the calibration date of a device contained in a combined device. More...
uint16_t	LstCbScpGetChannelCount (uint32_t dwIdKind, uint32_t dwId, uint32_t dwContainedDeviceSerialNumber)
	Get the channel count of an oscilloscope contained in a combined oscilloscope. More...

Function Documentation

uint32_t LstDevGetContainedSerialNumbers	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t *	pBuffer,
		uint32_t	dwBufferLength
	)

Get the serial numbers of the individual devices contained in a combined device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[out]	pBuffer	A pointer to a buffer for the serial numbers.
[in]	dwBufferLength	The length of the buffer, in bytes.

Returns

The number of devices in the combined device, or zero if the device isn't a combined device.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Example

uint32_t dwLength = LstDevGetContainedSerialNumbers( dwIdKind , dwId , NULL , 0 );
uint32_t* pSerialNumbers = malloc( sizeof( uint32_t ) * dwLength );
dwLength = LstDevGetContainedSerialNumbers( dwIdKind , dwId , pSerialNumbers , dwLength );

for( i = 0 ; i < dwLength ; i++ )
{
  printf( "%u\n" , pSerialNumbers[ i ] );
}

free( pSerialNumbers );

Since

0.4.1

uint32_t LstCbDevGetProductId	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber
	)

Get the product id of a device contained in a combined device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.

Returns

The product id of the contained device.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a product id.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

uint32_t LstCbDevGetName	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber,
		char *	pBuffer,
		uint32_t	dwBufferLength
	)

Get the full name of a device contained in a combined device.

E.g. Handyscope HS5-530XMS

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.
[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_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a name.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

uint32_t LstCbDevGetNameShort	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber,
		char *	pBuffer,
		uint32_t	dwBufferLength
	)

Get the short name of a device contained in a combined device.

E.g. HS5-530XMS

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.
[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_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a name.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

uint32_t LstCbDevGetNameShortest	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber,
		char *	pBuffer,
		uint32_t	dwBufferLength
	)

Get the short name without model postfix of a device contained in a combined device.

E.g. HS5

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.
[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_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a name.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.4

TpVersion_t LstCbDevGetDriverVersion	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber
	)

Get the driver version of a device contained in a combined device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.

Returns

The driver version of the contained device, or zero if no driver version is available.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a driver version or does not require a driver.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

TpVersion_t LstCbDevGetFirmwareVersion	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber
	)

Get the firmware version of a device contained in a combined device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.

Returns

The firmware version of the contained device, or zero if no firmware version is available.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not support reading a firmware version or does not require firmware.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

TpDate_t LstCbDevGetCalibrationDate	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber
	)

Get the calibration date of a device contained in a combined device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined device to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained device inside the combined device.

Returns

The calibration date of the contained device, or zero if no calibration date is available.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined device with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined device or the contained device does not have a calibration date.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1

uint16_t LstCbScpGetChannelCount	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwContainedDeviceSerialNumber
	)

Get the channel count of an oscilloscope contained in a combined oscilloscope.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the combined oscilloscope to check, as specified by dwIdKind.
[in]	dwContainedDeviceSerialNumber	The serial number identifying the contained oscilloscope inside the combined oscilloscope.

Returns

The channel count of the contained oscilloscope.

Status values

INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no combined oscilloscope with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no combined oscilloscope with the requested serial number.
NOT_SUPPORTED	The indicated device is not a combined oscilloscope.
INVALID_CONTAINED_DEVICE_SERIALNUMBER	There is no contained device with the requested serial number in de combined device.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since

0.4.1