SetupApi (JNA API)
Description: declaration: package: com.sun.jna.platform.win32, interface: SetupApi

Package com.sun.jna.platform.win32

# Interface SetupApi

All Superinterfaces:
  `AltCallingConvention`, `Library`, `StdCall`, `StdCallLibrary`

public interface SetupApi extends StdCallLibrary
The interface for the w32 setup API.

Author:
  Christian Schwarz

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `SetupApi.SP_DEVICE_INTERFACE_DATA`
  An SP_DEVICE_INTERFACE_DATA structure defines a device interface in a device information set.
  `static class`
  `SetupApi.SP_DEVINFO_DATA`
  An SP_DEVINFO_DATA structure defines a device instance that is a member of a device information set.

  ## Nested classes/interfaces inherited from interface com.sun.jna.Library

  `Library.Handler`

  ## Nested classes/interfaces inherited from interface com.sun.jna.win32.StdCallLibrary

  `StdCallLibrary.StdCallCallback`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `CM_DEVCAP_REMOVABLE`
  Removable.
  `static final int`
  `DICS_FLAG_CONFIGGENERAL`
  1 or more hardware profile-specific changes to follow.
  `static final int`
  `DICS_FLAG_CONFIGSPECIFIC`
  make change in specified profile only
  `static final int`
  `DICS_FLAG_GLOBAL`
  make change in all hardware profiles
  `static final int`
  `DIGCF_ALLCLASSES`
  Return a list of installed devices for all device setup classes or all device interface classes.
  `static final int`
  `DIGCF_DEFAULT`
  Return only the device that is associated with the system default device interface, if one is set, for the specified device interface classes.
  `static final int`
  `DIGCF_DEVICEINTERFACE`
  Return devices that support device interfaces for the specified device interface classes.
  `static final int`
  `DIGCF_PRESENT`
  Return only devices that are currently present in a system.
  `static final int`
  `DIGCF_PROFILE`
  Return only devices that are a part of the current hardware profile.
  `static final int`
  `DIREG_BOTH`
  Delete both driver and Device key
  `static final int`
  `DIREG_DEV`
  Open/Create/Delete device key.
  `static final int`
  `DIREG_DRV`
  Open/Create/Delete driver key
  `static final Guid.GUID`
  `GUID_DEVINTERFACE_COMPORT`
  Drivers for serial ports register instances of this device interface class to notify the operating system and applications of the presence of COM ports.
  `static final Guid.GUID`
  `GUID_DEVINTERFACE_DISK`
  The GUID_DEVINTERFACE_DISK device interface class is defined for hard disk storage devices.
  `static final SetupApi`
  `INSTANCE`
  `static final int`
  `SPDRP_DEVICEDESC`
  DeviceDesc (R/W)
  `static final int`
  `SPDRP_REMOVAL_POLICY`
  (Windows XP and later) The function retrieves the device's current removal policy as a DWORD that contains one of the CM_REMOVAL_POLICY_Xxx values that are defined in Cfgmgr32.h.

  ### Fields inherited from interface com.sun.jna.Library

  `OPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_SYMBOL_PROVIDER, OPTION_TYPE_MAPPER`

  ### Fields inherited from interface com.sun.jna.win32.StdCallLibrary

  `FUNCTION_MAPPER, STDCALL_CONVENTION`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `SetupDiDestroyDeviceInfoList(WinNT.HANDLE hDevInfo)`
  The SetupDiDestroyDeviceInfoList function deletes a device information set and frees all associated memory.
  `boolean`
  `SetupDiEnumDeviceInfo(WinNT.HANDLE deviceInfoSet, int memberIndex, SetupApi.SP_DEVINFO_DATA deviceInfoData)`
  The SetupDiEnumDeviceInfo function returns a `SetupApi.SP_DEVINFO_DATA` structure that specifies a device information element in a device information set.
  `boolean`
  `SetupDiEnumDeviceInterfaces(WinNT.HANDLE hDevInfo, Pointer devInfo, Guid.GUID interfaceClassGuid, int memberIndex, SetupApi.SP_DEVICE_INTERFACE_DATA deviceInterfaceData)`
  The SetupDiEnumDeviceInterfaces function enumerates the device interfaces that are contained in a device information set.
  `WinNT.HANDLE`
  `SetupDiGetClassDevs(Guid.GUID classGuid, Pointer enumerator, Pointer hwndParent, int flags)`
  The SetupDiGetClassDevs function returns a handle to a device information set that contains requested device information elements for a local computer.
  `boolean`
  `SetupDiGetDeviceInterfaceDetail(WinNT.HANDLE hDevInfo, SetupApi.SP_DEVICE_INTERFACE_DATA deviceInterfaceData, Pointer deviceInterfaceDetailData, int deviceInterfaceDetailDataSize, IntByReference requiredSize, SetupApi.SP_DEVINFO_DATA deviceInfoData)`
  The SetupDiGetDeviceInterfaceDetail function returns details about a device interface.
  `boolean`
  `SetupDiGetDeviceRegistryProperty(WinNT.HANDLE DeviceInfoSet, SetupApi.SP_DEVINFO_DATA DeviceInfoData, int Property, IntByReference PropertyRegDataType, Pointer PropertyBuffer, int PropertyBufferSize, IntByReference RequiredSize)`
  The SetupDiGetDeviceRegistryProperty function retrieves a specified Plug and Play device property.
  `WinReg.HKEY`
  `SetupDiOpenDevRegKey(WinNT.HANDLE deviceInfoSet, SetupApi.SP_DEVINFO_DATA deviceInfoData, int scope, int hwProfile, int keyType, int samDesired)`
  The SetupDiOpenDevRegKey function opens a registry key for device-specific configuration information.

- ## Field Details

  - ### INSTANCE

    static final SetupApi INSTANCE

  - ### GUID_DEVINTERFACE_DISK

    static final Guid.GUID GUID_DEVINTERFACE_DISK
    The GUID_DEVINTERFACE_DISK device interface class is defined for hard disk storage devices.

  - ### GUID_DEVINTERFACE_COMPORT

    static final Guid.GUID GUID_DEVINTERFACE_COMPORT
    Drivers for serial ports register instances of this device interface class to notify the operating system and applications of the presence of COM ports.

  - ### DIGCF_DEFAULT

    static final int DIGCF_DEFAULT
    Return only the device that is associated with the system default device interface, if one is set, for the specified device interface classes.
    See Also:
      - Constant Field Values

  - ### DIGCF_PRESENT

    static final int DIGCF_PRESENT
    Return only devices that are currently present in a system.
    See Also:
      - Constant Field Values

  - ### DIGCF_ALLCLASSES

    static final int DIGCF_ALLCLASSES
    Return a list of installed devices for all device setup classes or all device interface classes.
    See Also:
      - Constant Field Values

  - ### DIGCF_PROFILE

    static final int DIGCF_PROFILE
    Return only devices that are a part of the current hardware profile.
    See Also:
      - Constant Field Values

  - ### DIGCF_DEVICEINTERFACE

    static final int DIGCF_DEVICEINTERFACE
    Return devices that support device interfaces for the specified device interface classes. This flag must be set in the Flags parameter if the Enumerator parameter specifies a device instance ID.
    See Also:
      - Constant Field Values

  - ### SPDRP_REMOVAL_POLICY

    static final int SPDRP_REMOVAL_POLICY
    (Windows XP and later) The function retrieves the device's current removal policy as a DWORD that contains one of the CM_REMOVAL_POLICY_Xxx values that are defined in Cfgmgr32.h.
    See Also:
      - Constant Field Values

  - ### CM_DEVCAP_REMOVABLE

    static final int CM_DEVCAP_REMOVABLE
    Removable.
    See Also:
      - Constant Field Values

  - ### DICS_FLAG_GLOBAL

    static final int DICS_FLAG_GLOBAL
    make change in all hardware profiles
    See Also:
      - Constant Field Values

  - ### DICS_FLAG_CONFIGSPECIFIC

    static final int DICS_FLAG_CONFIGSPECIFIC
    make change in specified profile only
    See Also:
      - Constant Field Values

  - ### DICS_FLAG_CONFIGGENERAL

    static final int DICS_FLAG_CONFIGGENERAL
    1 or more hardware profile-specific changes to follow.
    See Also:
      - Constant Field Values

  - ### DIREG_DEV

    static final int DIREG_DEV
    Open/Create/Delete device key.
    See Also:
      - `SetupDiOpenDevRegKey(com.sun.jna.platform.win32.WinNT.HANDLE, com.sun.jna.platform.win32.SetupApi.SP_DEVINFO_DATA, int, int, int, int)`
      - Constant Field Values

  - ### DIREG_DRV

    static final int DIREG_DRV
    Open/Create/Delete driver key
    See Also:
      - `SetupDiOpenDevRegKey(com.sun.jna.platform.win32.WinNT.HANDLE, com.sun.jna.platform.win32.SetupApi.SP_DEVINFO_DATA, int, int, int, int)`
      - Constant Field Values

  - ### DIREG_BOTH

    static final int DIREG_BOTH
    Delete both driver and Device key
    See Also:
      - `SetupDiOpenDevRegKey(com.sun.jna.platform.win32.WinNT.HANDLE, com.sun.jna.platform.win32.SetupApi.SP_DEVINFO_DATA, int, int, int, int)`
      - Constant Field Values

  - ### SPDRP_DEVICEDESC

    static final int SPDRP_DEVICEDESC
    DeviceDesc (R/W)

    Device registry property codes (Codes marked as read-only (R) may only be used for SetupDiGetDeviceRegistryProperty)

    These values should cover the same set of registry properties as defined by the CM_DRP codes in cfgmgr32.h.

    See Also:
      - Constant Field Values

- ## Method Details

  - ### SetupDiGetClassDevs

    WinNT.HANDLE SetupDiGetClassDevs(Guid.GUID classGuid, Pointer enumerator, Pointer hwndParent, int flags)
    The SetupDiGetClassDevs function returns a handle to a device information set that contains requested device information elements for a local computer.
    Parameters:
      `classGuid` - A pointer to the GUID for a device setup class or a device interface class. This pointer is optional and can be NULL. For more information about how to set ClassGuid, see the following Remarks section.
      `enumerator` - A pointer to a NULL-terminated string that specifies: An identifier (ID) of a Plug and Play (PnP) enumerator. This ID can either be the value's globally unique identifier (GUID) or symbolic name. For example, "PCI" can be used to specify the PCI PnP value. Other examples of symbolic names for PnP values include "USB," "PCMCIA," and "SCSI". A PnP device instance ID. When specifying a PnP device instance ID, DIGCF_DEVICEINTERFACE must be set in the Flags parameter. This pointer is optional and can be NULL. If an enumeration value is not used to select devices, set Enumerator to NULL.
      `hwndParent` - A handle to the top-level window to be used for a user interface that is associated with installing a device instance in the device information set. This handle is optional and can be NULL.
      `flags` - A variable of type DWORD that specifies control options that filter the device information elements that are added to the device information set.
    Returns:
      If the operation succeeds, SetupDiGetClassDevs returns a handle to a device information set that contains all installed devices that matched the supplied parameters. If the operation fails, the function returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

  - ### SetupDiDestroyDeviceInfoList

    boolean SetupDiDestroyDeviceInfoList(WinNT.HANDLE hDevInfo)
    The SetupDiDestroyDeviceInfoList function deletes a device information set and frees all associated memory.
    Parameters:
      `hDevInfo` - A handle to the device information set to delete.
    Returns:
      The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError.

  - ### SetupDiEnumDeviceInterfaces

    boolean SetupDiEnumDeviceInterfaces(WinNT.HANDLE hDevInfo, Pointer devInfo, Guid.GUID interfaceClassGuid, int memberIndex, SetupApi.SP_DEVICE_INTERFACE_DATA deviceInterfaceData)
    The SetupDiEnumDeviceInterfaces function enumerates the device interfaces that are contained in a device information set.
    Parameters:
      `hDevInfo` - A pointer to a device information set that contains the device interfaces for which to return information. This handle is typically returned by SetupDiGetClassDevs.
      `devInfo` - A pointer to an SP_DEVINFO_DATA structure that specifies a device information element in DeviceInfoSet. This parameter is optional and can be NULL. If this parameter is specified, SetupDiEnumDeviceInterfaces constrains the enumeration to the interfaces that are supported by the specified device. If this parameter is NULL, repeated calls to SetupDiEnumDeviceInterfaces return information about the interfaces that are associated with all the device information elements in DeviceInfoSet. This pointer is typically returned by SetupDiEnumDeviceInfo.
      `interfaceClassGuid` - A pointer to a GUID that specifies the device interface class for the requested interface.
      `memberIndex` - A zero-based index into the list of interfaces in the device information set. The caller should call this function first with MemberIndex set to zero to obtain the first interface. Then, repeatedly increment MemberIndex and retrieve an interface until this function fails and GetLastError returns ERROR_NO_MORE_ITEMS. If DeviceInfoData specifies a particular device, the MemberIndex is relative to only the interfaces exposed by that device.
      `deviceInterfaceData` - A pointer to a caller-allocated buffer that contains, on successful return, a completed SP_DEVICE_INTERFACE_DATA structure that identifies an interface that meets the search parameters. The caller must set DeviceInterfaceData.cbSize to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.
    Returns:
      SetupDiEnumDeviceInterfaces returns TRUE if the function completed without error. If the function completed with an error, FALSE is returned and the error code for the failure can be retrieved by calling GetLastError.

  - ### SetupDiGetDeviceInterfaceDetail

    boolean SetupDiGetDeviceInterfaceDetail(WinNT.HANDLE hDevInfo, SetupApi.SP_DEVICE_INTERFACE_DATA deviceInterfaceData, Pointer deviceInterfaceDetailData, int deviceInterfaceDetailDataSize, IntByReference requiredSize, SetupApi.SP_DEVINFO_DATA deviceInfoData)
    The SetupDiGetDeviceInterfaceDetail function returns details about a device interface.
    Parameters:
      `hDevInfo` - A pointer to the device information set that contains the interface for which to retrieve details. This handle is typically returned by SetupDiGetClassDevs.
      `deviceInterfaceData` - A pointer to an SP_DEVICE_INTERFACE_DATA structure that specifies the interface in DeviceInfoSet for which to retrieve details. A pointer of this type is typically returned by SetupDiEnumDeviceInterfaces.
      `deviceInterfaceDetailData` - A pointer to an SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. This parameter is optional and can be NULL. This parameter must be NULL if DeviceInterfaceDetailSize is zero. If this parameter is specified, the caller must set DeviceInterfaceDetailData.cbSize to sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) before calling this function. The cbSize member always contains the size of the fixed part of the data structure, not a size reflecting the variable-length string at the end.
      `deviceInterfaceDetailDataSize` - The size of the DeviceInterfaceDetailData buffer. The buffer must be at least (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) bytes, to contain the fixed part of the structure and a single NULL to terminate an empty MULTI_SZ string. This parameter must be zero if DeviceInterfaceDetailData is NULL.
      `requiredSize` - A pointer to a variable of type DWORD that receives the required size of the DeviceInterfaceDetailData buffer. This size includes the size of the fixed part of the structure plus the number of bytes required for the variable-length device path string. This parameter is optional and can be NULL.
      `deviceInfoData` - A pointer to a buffer that receives information about the device that supports the requested interface. The caller must set DeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). This parameter is optional and can be NULL.
    Returns:
      SetupDiGetDeviceInterfaceDetail returns TRUE if the function completed without error. If the function completed with an error, FALSE is returned and the error code for the failure can be retrieved by calling GetLastError.

  - ### SetupDiGetDeviceRegistryProperty

    boolean SetupDiGetDeviceRegistryProperty(WinNT.HANDLE DeviceInfoSet, SetupApi.SP_DEVINFO_DATA DeviceInfoData, int Property, IntByReference PropertyRegDataType, Pointer PropertyBuffer, int PropertyBufferSize, IntByReference RequiredSize)
    The SetupDiGetDeviceRegistryProperty function retrieves a specified Plug and Play device property.
    Parameters:
      `DeviceInfoSet` - A handle to a device information set that contains a device information element that represents the device for which to retrieve a Plug and Play property.
      `DeviceInfoData` - A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.
      `Property` - Specifies the property to be retrieved.
      `PropertyRegDataType` - A pointer to a variable that receives the data type of the property that is being retrieved. This is one of the standard registry data types. This parameter is optional and can be NULL.
      `PropertyBuffer` - A pointer to a buffer that receives the property that is being retrieved. If this parameter is set to NULL, and PropertyBufferSize is also set to zero, the function returns the required size for the buffer in RequiredSize.
      `PropertyBufferSize` - The size, in bytes, of the PropertyBuffer buffer.
      `RequiredSize` - A pointer to a variable of type DWORD that receives the required size, in bytes, of the PropertyBuffer buffer that is required to hold the data for the requested property. This parameter is optional and can be NULL.
    Returns:
      SetupDiGetDeviceRegistryProperty returns TRUE if the call was successful. Otherwise, it returns FALSE and the logged error can be retrieved by making a call to GetLastError. SetupDiGetDeviceRegistryProperty returns the ERROR_INVALID_DATA error code if the requested property does not exist for a device or if the property data is not valid.

  - ### SetupDiOpenDevRegKey

    WinReg.HKEY SetupDiOpenDevRegKey(WinNT.HANDLE deviceInfoSet, SetupApi.SP_DEVINFO_DATA deviceInfoData, int scope, int hwProfile, int keyType, int samDesired)
    The SetupDiOpenDevRegKey function opens a registry key for device-specific configuration information.

    Depending on the value that is passed in the samDesired parameter, it might be necessary for the caller of this function to be a member of the Administrators group.

    Close the handle returned from this function by calling RegCloseKey.

    The specified device instance must be registered before this function is called. However, be aware that the operating system automatically registers PnP device instances. For information about how to register non-PnP device instances, see SetupDiRegisterDeviceInfo.

    Parameters:
      `deviceInfoSet` - A handle to the device information set that contains a device information element that represents the device for which to open a registry key.
      `deviceInfoData` - A pointer to an `SetupApi.SP_DEVINFO_DATA` structure that specifies the device information element in DeviceInfoSet.
      `scope` - he scope of the registry key to open. The scope determines where the information is stored. The scope can be global or specific to a hardware profile. The scope is specified by one of the following values:
      - DICS_FLAG_GLOBAL Open a key to store global configuration information. This information is not specific to a particular hardware profile. This opens a key that is rooted at HKEY_LOCAL_MACHINE. The exact key opened depends on the value of the KeyType parameter.
      - DICS_FLAG_CONFIGSPECIFIC Open a key to store hardware profile-specific configuration information. This key is rooted at one of the hardware-profile specific branches, instead of HKEY_LOCAL_MACHINE. The exact key opened depends on the value of the KeyType parameter.
      `hwProfile` - A hardware profile value, which is set as follows:
      - If Scope is set to DICS_FLAG_CONFIGSPECIFIC, HwProfile specifies the hardware profile of the key that is to be opened.
      - If HwProfile is 0, the key for the current hardware profile is opened.
      - If Scope is DICS_FLAG_GLOBAL, HwProfile is ignored.
      `keyType` - The type of registry storage key to open, which can be one of the following values:
      - `DIREG_DEV` Open a hardware key for the device.
      - `DIREG_DRV` Open a software key for the device. For more information about a device's hardware and software keys, see Registry Trees and Keys for Devices and Drivers.
      `samDesired` - The registry security access that is required for the requested key. For information about registry security access values of type REGSAM, see the Microsoft Windows SDK documentation.
    Returns:
      If the function is successful, it returns a handle to an opened registry key where private configuration data about this device instance can be stored/retrieved.

      If the function fails, it returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

  - ### SetupDiEnumDeviceInfo

    boolean SetupDiEnumDeviceInfo(WinNT.HANDLE deviceInfoSet, int memberIndex, SetupApi.SP_DEVINFO_DATA deviceInfoData)
    The SetupDiEnumDeviceInfo function returns a `SetupApi.SP_DEVINFO_DATA` structure that specifies a device information element in a device information set.

    Remarks
    Repeated calls to this function return a device information element for a different device. This function can be called repeatedly to get information about all devices in the device information set.

    To enumerate device information elements, an installer should initially call SetupDiEnumDeviceInfo with the MemberIndex parameter set to 0. The installer should then increment MemberIndex and call SetupDiEnumDeviceInfo until there are no more values (the function fails and a call to GetLastError returns ERROR_NO_MORE_ITEMS).

    Call SetupDiEnumDeviceInterfaces to get a context structure for a device interface element (versus a device information element).

    Parameters:
      `deviceInfoSet` - A handle to the device information set for which to return an `SetupApi.SP_DEVINFO_DATA` structure that represents a device information element.
      `memberIndex` - A zero-based index of the device information element to retrieve.
      `deviceInfoData` - A pointer to an SP_DEVINFO_DATA structure to receive information about an enumerated device information element.
    Returns:
      The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError.