Device discovery#

group Discovery

Functions for working with device Discovery.

Enums

enum ZIDeviceStatus_enum

Defines the values of the Discovery property ‘statusflags’ retrieved by ziAPIDiscoveryGetValueI.

Values:

enumerator ZI_DEVICE_STATUS_NOT_YET_READY = 0x0001
enumerator ZI_DEVICE_STATUS_FREE = 0x0002
enumerator ZI_DEVICE_STATUS_IN_USE_BY = 0x0004
enumerator ZI_DEVICE_STATUS_FW_UPGRADE_USB = 0x0008
enumerator ZI_DEVICE_STATUS_FW_UPGRADE_REQUIRED = 0x0010
enumerator ZI_DEVICE_STATUS_FW_UPGRADE_AVAILABLE = 0x0020
enumerator ZI_DEVICE_STATUS_FW_DOWNGRADE_REQUIRED = 0x0040
enumerator ZI_DEVICE_STATUS_FW_DOWNGRADE_AVAILABLE = 0x0080
enumerator ZI_DEVICE_STATUS_FW_UPDATE_IN_PROGRESS = 0x0100
enumerator ZI_DEVICE_STATUS_DEVICE_UNKNOWN = 0x0200

Functions

ZIResult_enum ziAPIDiscoveryFindAll(ZIConnection conn, char *deviceIds, uint32_t bufferSize)

Perform a Discovery property look-up for the specified deviceAddress and return its device ID. Attention! This invalidates all pointers previously returned by ziAPIDiscovery* calls. The deviceId need not be deallocated by the user.

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • deviceIds[out] Pointer to a buffer that is to contain the list of newline-separated IDs of the devices found, e.g. “DEV2006\nDEV2007\n”.

  • bufferSize[in] The size of the buffer pointed to by deviceIds. If the buffer is too small to hold the complete list of device IDs, its contents remain unchanged.

Returns:

  • ZI_INFO_SUCCESS

  • ZI_ERROR_LENGTH The provided buffer is too small to hold the list.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIDiscoveryFind(ZIConnection conn, const char *deviceAddress, const char **deviceId)

Perform a Discovery property look-up for the specified deviceAddress and return its device ID. Attention! This invalidates all pointers previously returned by ziAPIDiscovery* calls. The deviceId need not be deallocated by the user.

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • deviceAddress[in] The address or ID of the device to find, e.g., ‘uhf-dev2006’ or ‘dev2006’.

  • deviceId[out] The ID of the device that was found, e.g. ‘DEV2006’.

Returns:

  • ZI_INFO_SUCCESS

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIDiscoveryGet(ZIConnection conn, const char *deviceId, const char **propsJSON)

Returns the device Discovery properties for a given device ID in JSON format. The function ziAPIDiscoveryFind must be called before ziAPIDiscoveryGet can be used. The propsJSON need not be deallocated by the user.

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • deviceId[in] The ID of the device to get Discovery information for, as returned by ziAPIDiscoveryFind, e.g., ‘dev2006’.

  • propsJSON[out] The Discovery properites in JSON format of the specified device.

Returns:

  • ZI_INFO_SUCCESS

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIDiscoveryGetValueI(ZIConnection conn, const char *deviceId, const char *propName, ZIIntegerData *value)

Returns the specified integer Discovery property value for a given device ID. The function ziAPIDiscoveryFind must be called with the required device ID before using ziAPIDiscoveryGetValueI.

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • deviceId[in] The ID of the device to get Discovery information for, as returned by ziAPIDiscoveryFind, e.g., ‘dev2006’.

  • propName[in] The name of the desired integer Discovery property.

  • value[out] Pointer to the value of the specified Discovery property.

Returns:

  • ZI_INFO_SUCCESS

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIDiscoveryGetValueS(ZIConnection conn, const char *deviceId, const char *propName, const char **value)

Returns the specified string Discovery property value for a given device ID. The function ziAPIDiscoveryFind must be called with the required device ID before using ziAPIDiscoveryGetValueS. The value must not be deallocated by the user.

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • deviceId[in] The ID of the device to get Discovery information for, as returned by ziAPIDiscoveryFind, e.g., ‘dev2006’.

  • propName[in] The name of the desired integer Discovery property.

  • value[out] Pointer to the value of the specified Discovery property.

Returns:

  • ZI_INFO_SUCCESS

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.