Device enumeration

One of the key functionalities of the system is to discover and provide access to connected devices. In ItalaApi, devices are controlled through a dedicated interface or handle.

Warning

The maximum number of enumerated devices is 255. The maximum number of simultaneously created devices is 50.

The process involves two main steps:

  1. Enumerating to find available devices. This returns a list of DeviceInfo objects, which contain key details about each device found.

  2. Creating a device instance using the DeviceInfo of the desired device.

Warning

The user application is responsible for the lifetime of device instances. Users must create a device instance before using it and properly destroy it when it is no longer needed.

Enumerate All Available Devices

The quickest way to find devices is to perform a system-wide search across all available network interfaces.

The EnumerateDevices() method returns a list of DeviceInfo objects. Users can then select one and pass it to CreateDevice() to get an IDevice instance.

// Search for devices on all interfaces for 700ms
Itala::DeviceInfoList deviceInfos = pSystem->EnumerateDevices(700);

if (!deviceInfos.empty())
{
  Itala::DeviceInfo firstDeviceInfo = deviceInfos[0];
  std::cout << "First device found: " << firstDeviceInfo.SerialNumber() << std::endl;

  // Create and use the device
  Itala::IDevice* pDevice = pSystem->CreateDevice(firstDeviceInfo);
  // ... use the device ...
  pDevice->Dispose();
  pDevice = nullptr;
}

The SYS_EnumerateDevices() method performs the search. Users then get the count and retrieve the DeviceInfo for a specific device by its index. This info is then used to create a device handle.

// Search for devices on all interfaces for 700ms
error = SYS_EnumerateDevices(700);

size_t deviceCount = 0;
error = SYS_GetDeviceCount(&deviceCount);

if (deviceCount > 0)
{
  DeviceInfo deviceInfo;
  error = SYS_GetDeviceByIndex(0, &deviceInfo);

  // Create and use the device
  H_DEVICE hDevice = NULL;
  error = SYS_CreateDevice(deviceInfo, &hDevice);
  // ... use the device ...
  error = DEV_Dispose(hDevice);
  hDevice = NULL;
}

The EnumerateDevices() method returns a list of DeviceInfo objects. Users can then select one and pass it to CreateDevice() to get an IDevice instance.

// Search for devices on all interfaces for 700ms
var deviceInfos = system.EnumerateDevices(700);

if (deviceInfos.Any())
{
  DeviceInfo firstDeviceInfo = deviceInfos.First();
  Console.WriteLine($"First device found: {firstDeviceInfo.SerialNumber}");

  // Create and use the device
  using (IDevice device = system.CreateDevice(firstDeviceInfo))
  {
    // ... use the device ...
  }
}

The enumerate_devices() method returns a list of DeviceInfo objects. Users can then select one and pass it to create_device() to get an IDevice instance.

# Search for devices on all interfaces for 700ms
device_infos = system.enumerate_devices(700)

if device_infos:
  first_device_info = device_infos[0]
  print(f"First device found: {first_device_info.serial_number}")

  # Create and use the device
  with system.create_device(first_device_info) as device:
    # ... use the device ...
    pass

Enumerate devices on a specific network interface

For more control, users can perform a targeted enumeration on a single network interface. This requires first finding the available interfaces and then searching for devices on the desired one.

First, call EnumerateInterfaces() to get a list of InterfaceInfo objects. Then, pass the desired interface to the overloaded EnumerateDevices() method.

// 1. Find available network interfaces
Itala::InterfaceInfoList interfaceInfos = pSystem->EnumerateInterfaces();

if (!interfaceInfos.empty())
{
  Itala::InterfaceInfo firstInterface = interfaceInfos[0];
  std::cout << "Searching on interface: " << firstInterface.DisplayName() << std::endl;

  // 2. Search for devices on that specific interface
  Itala::DeviceInfoList deviceInfos = pSystem->EnumerateDevices(firstInterface, 700);

  if(!deviceInfos.empty())
  {
    // 3. Create and use the device
    Itala::IDevice* pDevice = pSystem->CreateDevice(deviceInfos[0]);
    // ... use the device ...
    pDevice->Dispose();
  }
}

First, enumerate interfaces with SYS_EnumerateInterfaces(), then get the InterfaceInfo by index. Pass this info to SYS_EnumerateDevicesByInterface() to perform the targeted search.

// 1. Find available network interfaces
error = SYS_EnumerateInterfaces();
size_t interfaceCount = 0;
error = SYS_GetInterfaceCount(&interfaceCount);

if (interfaceCount > 0)
{
  InterfaceInfo itfInfo;
  error = SYS_GetInterfaceByIndex(0, &itfInfo);

  // 2. Search for devices on that specific interface
  error = SYS_EnumerateDevicesByInterface(itfInfo, 700);

  size_t deviceCount = 0;
  error = SYS_GetDeviceCount(&deviceCount);

  if (deviceCount > 0)
  {
    // 3. Create and use the device
    DeviceInfo deviceInfo;
    error = SYS_GetDeviceByIndex(0, &deviceInfo);
    H_DEVICE hDevice = NULL;
    error = SYS_CreateDevice(deviceInfo, &hDevice);
    // ... use the device ...
    error = DEV_Dispose(hDevice);
  }
}

First, call EnumerateInterfaces() to get a list of InterfaceInfo objects. Then, pass the desired interface to the overloaded EnumerateDevices() method.

// 1. Find available network interfaces
var interfaceInfos = system.EnumerateInterfaces();

if (interfaceInfos.Any())
{
  var firstInterface = interfaceInfos.First();
  Console.WriteLine($"Searching on interface: {firstInterface.DisplayName}");

  // 2. Search for devices on that specific interface
  var deviceInfos = system.EnumerateDevices(firstInterface, 700);

  if (deviceInfos.Any())
  {
    // 3. Create and use the device
    using (var device = system.CreateDevice(deviceInfos.First()))
    {
      // ... use the device ...
    }
  }
}

First, call enumerate_interfaces() to get a list of InterfaceInfo objects. Then, pass the desired interface to the enumerate_devices() method.

# 1. Find available network interfaces
interface_infos = system.enumerate_interfaces()

if interface_infos:
  first_interface = interface_infos[0]
  print(f"Searching on interface: {first_interface.display_name}")

  # 2. Search for devices on that specific interface
  device_infos = system.enumerate_devices(first_interface, 700)

  if device_infos:
    # 3. Create and use the device
    with system.create_device(device_infos[0]) as device:
      # ... use the device ...
      pass