1 /* 2 * The contents of this file is dual-licensed under 2 3 * alternative Open Source/Free licenses: LGPL 2.1 or later and 4 * Apache License 2.0. (starting with JNA version 4.0.0). 5 * 6 * You can freely decide which license you want to apply to 7 * the project. 8 * 9 * You may obtain a copy of the LGPL License at: 10 * 11 * http://www.gnu.org/licenses/licenses.html 12 * 13 * A copy is also included in the downloadable source code package 14 * containing JNA, in file "LGPL2.1". 15 * 16 * You may obtain a copy of the Apache License at: 17 * 18 * http://www.apache.org/licenses/ 19 * 20 * A copy is also included in the downloadable source code package 21 * containing JNA, in file "AL2.0". 22 */ 23 package com.sun.jna.platform.win32; 24 25 import java.util.List; 26 27 import com.sun.jna.Native; 28 import com.sun.jna.Pointer; 29 import com.sun.jna.Structure; 30 import com.sun.jna.Structure.FieldOrder; 31 import com.sun.jna.platform.win32.Guid.GUID; 32 import com.sun.jna.platform.win32.WinNT.HANDLE; 33 import com.sun.jna.platform.win32.WinReg.HKEY; 34 import com.sun.jna.ptr.IntByReference; 35 import com.sun.jna.win32.StdCallLibrary; 36 import com.sun.jna.win32.W32APIOptions; 37 38 /** 39 * The interface for the w32 setup API. 40 * @author Christian Schwarz 41 */ 42 public interface SetupApi extends StdCallLibrary { 43 44 SetupApi INSTANCE = Native.load("setupapi", SetupApi.class, W32APIOptions.DEFAULT_OPTIONS); 45 46 /** 47 * The GUID_DEVINTERFACE_DISK device interface class is defined for hard disk storage devices. 48 */ 49 GUID GUID_DEVINTERFACE_DISK = new GUID("53F56307-B6BF-11D0-94F2-00A0C91EFB8B"); 50 51 52 /** 53 * Drivers for serial ports register instances of this device interface 54 * class to notify the operating system and applications of the presence of 55 * COM ports. 56 */ 57 GUID GUID_DEVINTERFACE_COMPORT = new GUID("86E0D1E0-8089-11D0-9CE4-08003E301F73"); 58 59 /** 60 * Return only the device that is associated with the system default device interface, if one is set, for the 61 * specified device interface classes. 62 */ 63 int DIGCF_DEFAULT = 0x1; 64 65 /** 66 * Return only devices that are currently present in a system. 67 */ 68 int DIGCF_PRESENT = 0x2; 69 70 /** 71 * Return a list of installed devices for all device setup classes or all device interface classes. 72 */ 73 int DIGCF_ALLCLASSES = 0x4; 74 75 /** 76 * Return only devices that are a part of the current hardware profile. 77 */ 78 int DIGCF_PROFILE = 0x8; 79 80 /** 81 * Return devices that support device interfaces for the specified device interface classes. This flag must be set 82 * in the Flags parameter if the Enumerator parameter specifies a device instance ID. 83 */ 84 int DIGCF_DEVICEINTERFACE = 0x10; 85 86 /** 87 * (Windows XP and later) The function retrieves the device's current removal policy as a DWORD that contains one of 88 * the CM_REMOVAL_POLICY_Xxx values that are defined in Cfgmgr32.h. 89 */ 90 int SPDRP_REMOVAL_POLICY = 0x0000001F; 91 92 /** 93 * Removable. 94 */ 95 int CM_DEVCAP_REMOVABLE = 0x00000004; 96 97 /** make change in all hardware profiles */ 98 int DICS_FLAG_GLOBAL = 0x00000001; 99 /** make change in specified profile only */ 100 int DICS_FLAG_CONFIGSPECIFIC = 0x00000002; 101 /** 1 or more hardware profile-specific changes to follow. */ 102 int DICS_FLAG_CONFIGGENERAL = 0x00000004; 103 104 /** 105 * Open/Create/Delete device key. 106 * 107 * @see #SetupDiOpenDevRegKey 108 */ 109 int DIREG_DEV = 0x00000001; 110 111 /** 112 * Open/Create/Delete driver key 113 * 114 * @see #SetupDiOpenDevRegKey 115 */ 116 int DIREG_DRV = 0x00000002; 117 118 /** 119 * Delete both driver and Device key 120 * 121 * @see #SetupDiOpenDevRegKey 122 */ 123 int DIREG_BOTH = 0x00000004; 124 125 /** 126 * DeviceDesc (R/W) 127 * <p> 128 * Device registry property codes (Codes marked as read-only (R) may only be 129 * used for SetupDiGetDeviceRegistryProperty) 130 * <p> 131 * These values should cover the same set of registry properties as defined 132 * by the CM_DRP codes in cfgmgr32.h. 133 */ 134 int SPDRP_DEVICEDESC = 0x00000000; 135 136 /** 137 * The SetupDiGetClassDevs function returns a handle to a device information set that contains requested device 138 * information elements for a local computer. 139 * 140 * @param classGuid 141 * A pointer to the GUID for a device setup class or a device interface class. This pointer is optional and can be 142 * NULL. For more information about how to set ClassGuid, see the following Remarks section. 143 * 144 * @param enumerator 145 * A pointer to a NULL-terminated string that specifies: 146 * 147 * An identifier (ID) of a Plug and Play (PnP) enumerator. This ID can either be the value's globally unique 148 * identifier (GUID) or symbolic name. For example, "PCI" can be used to specify the PCI PnP value. Other examples 149 * of symbolic names for PnP values include "USB," "PCMCIA," and "SCSI". 150 * 151 * A PnP device instance ID. When specifying a PnP device instance ID, DIGCF_DEVICEINTERFACE must be set in the 152 * Flags parameter. 153 * 154 * This pointer is optional and can be NULL. If an enumeration value is not used to select devices, set Enumerator 155 * to NULL. 156 * 157 * @param hwndParent 158 * A handle to the top-level window to be used for a user interface that is associated with installing a device 159 * instance in the device information set. This handle is optional and can be NULL. 160 * 161 * @param flags 162 * A variable of type DWORD that specifies control options that filter the device information elements that are 163 * added to the device information set. 164 * 165 * @return 166 * If the operation succeeds, SetupDiGetClassDevs returns a handle to a device information set that contains all 167 * installed devices that matched the supplied parameters. If the operation fails, the function returns 168 * INVALID_HANDLE_VALUE. To get extended error information, call GetLastError. 169 */ SetupDiGetClassDevs(Guid.GUID classGuid, Pointer enumerator, Pointer hwndParent, int flags)170 WinNT.HANDLE SetupDiGetClassDevs(Guid.GUID classGuid, Pointer enumerator, Pointer hwndParent, int flags); 171 172 /** 173 * The SetupDiDestroyDeviceInfoList function deletes a device information set and frees all associated memory. 174 * 175 * @param hDevInfo A handle to the device information set to delete. 176 * @return The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be 177 * retrieved with a call to GetLastError. 178 */ SetupDiDestroyDeviceInfoList(WinNT.HANDLE hDevInfo)179 boolean SetupDiDestroyDeviceInfoList(WinNT.HANDLE hDevInfo); 180 181 /** 182 * The SetupDiEnumDeviceInterfaces function enumerates the device interfaces that are contained in a device 183 * information set. 184 * 185 * @param hDevInfo 186 * A pointer to a device information set that contains the device interfaces for which to return information. This 187 * handle is typically returned by SetupDiGetClassDevs. 188 * 189 * @param devInfo 190 * A pointer to an SP_DEVINFO_DATA structure that specifies a device information element in DeviceInfoSet. This 191 * parameter is optional and can be NULL. If this parameter is specified, SetupDiEnumDeviceInterfaces constrains 192 * the enumeration to the interfaces that are supported by the specified device. If this parameter is NULL, 193 * repeated calls to SetupDiEnumDeviceInterfaces return information about the interfaces that are associated with 194 * all the device information elements in DeviceInfoSet. This pointer is typically returned by 195 * SetupDiEnumDeviceInfo. 196 * 197 * @param interfaceClassGuid 198 * A pointer to a GUID that specifies the device interface class for the requested interface. 199 * 200 * @param memberIndex 201 * A zero-based index into the list of interfaces in the device information set. The caller should call this 202 * function first with MemberIndex set to zero to obtain the first interface. Then, repeatedly increment 203 * MemberIndex and retrieve an interface until this function fails and GetLastError returns ERROR_NO_MORE_ITEMS. 204 * 205 * If DeviceInfoData specifies a particular device, the MemberIndex is relative to only the interfaces exposed by 206 * that device. 207 * 208 * @param deviceInterfaceData 209 * A pointer to a caller-allocated buffer that contains, on successful return, a completed 210 * SP_DEVICE_INTERFACE_DATA structure that identifies an interface that meets the search parameters. The caller 211 * must set DeviceInterfaceData.cbSize to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function. 212 * 213 * @return 214 * SetupDiEnumDeviceInterfaces returns TRUE if the function completed without error. If the function completed 215 * with an error, FALSE is returned and the error code for the failure can be retrieved by calling GetLastError. 216 */ SetupDiEnumDeviceInterfaces(WinNT.HANDLE hDevInfo, Pointer devInfo, Guid.GUID interfaceClassGuid, int memberIndex, SP_DEVICE_INTERFACE_DATA deviceInterfaceData)217 boolean SetupDiEnumDeviceInterfaces(WinNT.HANDLE hDevInfo, Pointer devInfo, 218 Guid.GUID interfaceClassGuid, int memberIndex, 219 SP_DEVICE_INTERFACE_DATA deviceInterfaceData); 220 221 /** 222 * The SetupDiGetDeviceInterfaceDetail function returns details about a device interface. 223 * 224 * @param hDevInfo 225 * A pointer to the device information set that contains the interface for which to retrieve details. This handle 226 * is typically returned by SetupDiGetClassDevs. 227 * 228 * @param deviceInterfaceData 229 * A pointer to an SP_DEVICE_INTERFACE_DATA structure that specifies the interface in DeviceInfoSet for which to 230 * retrieve details. A pointer of this type is typically returned by SetupDiEnumDeviceInterfaces. 231 * 232 * @param deviceInterfaceDetailData 233 * A pointer to an SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. 234 * This parameter is optional and can be NULL. This parameter must be NULL if DeviceInterfaceDetailSize is zero. 235 * If this parameter is specified, the caller must set DeviceInterfaceDetailData.cbSize to 236 * sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) before calling this function. The cbSize member always contains the 237 * size of the fixed part of the data structure, not a size reflecting the variable-length string at the end. 238 * 239 * @param deviceInterfaceDetailDataSize 240 * The size of the DeviceInterfaceDetailData buffer. The buffer must be at least 241 * (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) bytes, to contain the fixed part of the 242 * structure and a single NULL to terminate an empty MULTI_SZ string. 243 * 244 * This parameter must be zero if DeviceInterfaceDetailData is NULL. 245 * 246 * @param requiredSize 247 * A pointer to a variable of type DWORD that receives the required size of the DeviceInterfaceDetailData buffer. 248 * This size includes the size of the fixed part of the structure plus the number of bytes required for the 249 * variable-length device path string. This parameter is optional and can be NULL. 250 * 251 * @param deviceInfoData 252 * A pointer to a buffer that receives information about the device that supports the requested interface. The 253 * caller must set DeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). This parameter is optional and can be NULL. 254 * 255 * @return 256 * SetupDiGetDeviceInterfaceDetail returns TRUE if the function completed without error. If the function completed 257 * with an error, FALSE is returned and the error code for the failure can be retrieved by calling GetLastError. 258 */ SetupDiGetDeviceInterfaceDetail(WinNT.HANDLE hDevInfo, SP_DEVICE_INTERFACE_DATA deviceInterfaceData, Pointer deviceInterfaceDetailData, int deviceInterfaceDetailDataSize, IntByReference requiredSize, SP_DEVINFO_DATA deviceInfoData)259 boolean SetupDiGetDeviceInterfaceDetail(WinNT.HANDLE hDevInfo, 260 SP_DEVICE_INTERFACE_DATA deviceInterfaceData, Pointer deviceInterfaceDetailData, 261 int deviceInterfaceDetailDataSize, IntByReference requiredSize, SP_DEVINFO_DATA deviceInfoData); 262 263 /** 264 * The SetupDiGetDeviceRegistryProperty function retrieves a specified Plug and Play device property. 265 * 266 * @param DeviceInfoSet 267 * A handle to a device information set that contains a device information element that represents the device for 268 * which to retrieve a Plug and Play property. 269 * 270 * @param DeviceInfoData 271 * A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet. 272 * 273 * @param Property 274 * Specifies the property to be retrieved. 275 * 276 * @param PropertyRegDataType 277 * A pointer to a variable that receives the data type of the property that is being retrieved. This is one of the 278 * standard registry data types. This parameter is optional and can be NULL. 279 * 280 * @param PropertyBuffer 281 * A pointer to a buffer that receives the property that is being retrieved. If this parameter is set to NULL, and 282 * PropertyBufferSize is also set to zero, the function returns the required size for the buffer in RequiredSize. 283 * 284 * @param PropertyBufferSize 285 * The size, in bytes, of the PropertyBuffer buffer. 286 * 287 * @param RequiredSize 288 * A pointer to a variable of type DWORD that receives the required size, in bytes, of the PropertyBuffer buffer 289 * that is required to hold the data for the requested property. This parameter is optional and can be NULL. 290 * 291 * @return 292 * SetupDiGetDeviceRegistryProperty returns TRUE if the call was successful. Otherwise, it returns FALSE and the 293 * logged error can be retrieved by making a call to GetLastError. SetupDiGetDeviceRegistryProperty returns the 294 * ERROR_INVALID_DATA error code if the requested property does not exist for a device or if the property data is 295 * not valid. 296 */ SetupDiGetDeviceRegistryProperty(HANDLE DeviceInfoSet, SP_DEVINFO_DATA DeviceInfoData, int Property, IntByReference PropertyRegDataType, Pointer PropertyBuffer, int PropertyBufferSize, IntByReference RequiredSize)297 boolean SetupDiGetDeviceRegistryProperty(HANDLE DeviceInfoSet, SP_DEVINFO_DATA DeviceInfoData, 298 int Property, IntByReference PropertyRegDataType, Pointer PropertyBuffer, int PropertyBufferSize, 299 IntByReference RequiredSize); 300 301 /** 302 * The SetupDiOpenDevRegKey function opens a registry key for device-specific configuration information. 303 * <p> 304 * Depending on the value that is passed in the samDesired parameter, it might be necessary for the caller of this 305 * function to be a member of the Administrators group. 306 * <p> 307 * Close the handle returned from this function by calling RegCloseKey. 308 * <p> 309 * The specified device instance must be registered before this function is called. However, be aware that the 310 * operating system automatically registers PnP device instances. For information about how to register non-PnP 311 * device instances, see SetupDiRegisterDeviceInfo. 312 * 313 * @param deviceInfoSet 314 * A handle to the device information set that contains a device information element that represents the 315 * device for which to open a registry key. 316 * @param deviceInfoData 317 * A pointer to an {@link SP_DEVINFO_DATA} structure that specifies the device information element in 318 * DeviceInfoSet. 319 * @param scope 320 * he scope of the registry key to open. The scope determines where the information is stored. The scope 321 * can be global or specific to a hardware profile. The scope is specified by one of the following 322 * values: 323 * <ul> 324 * <li>DICS_FLAG_GLOBAL Open a key to store global configuration information. This information is not 325 * specific to a particular hardware profile. This opens a key that is rooted at HKEY_LOCAL_MACHINE. The 326 * exact key opened depends on the value of the KeyType parameter. <li>DICS_FLAG_CONFIGSPECIFIC Open a 327 * key to store hardware profile-specific configuration information. This key is rooted at one of the 328 * hardware-profile specific branches, instead of HKEY_LOCAL_MACHINE. The exact key opened depends on the 329 * value of the KeyType parameter. 330 * </ul> 331 * @param hwProfile 332 * A hardware profile value, which is set as follows: 333 * <ul> 334 * <li>If Scope is set to DICS_FLAG_CONFIGSPECIFIC, HwProfile specifies the hardware profile of the key 335 * that is to be opened. <li>If HwProfile is 0, the key for the current hardware profile is opened. <li> 336 * If Scope is DICS_FLAG_GLOBAL, HwProfile is ignored. 337 * </ul> 338 * @param keyType 339 * The type of registry storage key to open, which can be one of the following values: 340 * <ul> 341 * <li> {@link #DIREG_DEV} Open a hardware key for the device. <li>{@link #DIREG_DRV} Open a software key 342 * for the device. For more information about a device's hardware and software keys, see Registry Trees 343 * and Keys for Devices and Drivers. 344 * </ul> 345 * @param samDesired 346 * The registry security access that is required for the requested key. For information about registry 347 * security access values of type REGSAM, see the Microsoft Windows SDK documentation. 348 * @return If the function is successful, it returns a handle to an opened registry key where private configuration 349 * data about this device instance can be stored/retrieved. 350 * <p> 351 * If the function fails, it returns INVALID_HANDLE_VALUE. To get extended error information, call 352 * GetLastError. 353 */ SetupDiOpenDevRegKey(HANDLE deviceInfoSet, SP_DEVINFO_DATA deviceInfoData, int scope, int hwProfile, int keyType, int samDesired)354 HKEY SetupDiOpenDevRegKey(HANDLE deviceInfoSet, SP_DEVINFO_DATA deviceInfoData, int scope, int hwProfile, int keyType, int samDesired); 355 356 /** 357 * The SetupDiEnumDeviceInfo function returns a {@link SP_DEVINFO_DATA} structure that specifies a device 358 * information element in a device information set. 359 * <p> 360 * <b>Remarks</b><br> 361 * Repeated calls to this function return a device information element for a different device. This function can be 362 * called repeatedly to get information about all devices in the device information set. 363 * <p> 364 * To enumerate device information elements, an installer should initially call SetupDiEnumDeviceInfo with the 365 * MemberIndex parameter set to 0. The installer should then increment MemberIndex and call SetupDiEnumDeviceInfo 366 * until there are no more values (the function fails and a call to GetLastError returns ERROR_NO_MORE_ITEMS). 367 * <p> 368 * Call SetupDiEnumDeviceInterfaces to get a context structure for a device interface element (versus a device 369 * information element). 370 * 371 * 372 * @param deviceInfoSet 373 * A handle to the device information set for which to return an {@link SP_DEVINFO_DATA} structure that 374 * represents a device information element. 375 * @param memberIndex 376 * A zero-based index of the device information element to retrieve. 377 * @param deviceInfoData 378 * A pointer to an SP_DEVINFO_DATA structure to receive information about an enumerated device 379 * information element. 380 * @return The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be 381 * retrieved with a call to GetLastError. 382 */ SetupDiEnumDeviceInfo(HANDLE deviceInfoSet, int memberIndex, SP_DEVINFO_DATA deviceInfoData)383 boolean SetupDiEnumDeviceInfo(HANDLE deviceInfoSet, int memberIndex, SP_DEVINFO_DATA deviceInfoData); 384 385 /** 386 * An SP_DEVICE_INTERFACE_DATA structure defines a device interface in a device information set. 387 */ 388 @FieldOrder({"cbSize", "InterfaceClassGuid", "Flags", "Reserved"}) 389 public static class SP_DEVICE_INTERFACE_DATA extends Structure { 390 391 public static class ByReference extends SP_DEVINFO_DATA implements Structure.ByReference { ByReference()392 public ByReference() { 393 } 394 ByReference(Pointer memory)395 public ByReference(Pointer memory) { 396 super(memory); 397 } 398 } 399 400 /** 401 * The size, in bytes, of the SP_DEVICE_INTERFACE_DATA structure. 402 */ 403 public int cbSize; 404 405 /** 406 * The GUID for the class to which the device interface belongs. 407 */ 408 public Guid.GUID InterfaceClassGuid; 409 410 /** 411 * Can be one or more of the following: 412 * SPINT_ACTIVE - The interface is active (enabled). 413 * SPINT_DEFAULT - The interface is the default interface for the device class. 414 * SPINT_REMOVED - The interface is removed. 415 */ 416 public int Flags; 417 418 /** 419 * Reserved. Do not use. 420 */ 421 public Pointer Reserved; 422 SP_DEVICE_INTERFACE_DATA()423 public SP_DEVICE_INTERFACE_DATA() { 424 cbSize = size(); 425 } 426 SP_DEVICE_INTERFACE_DATA(Pointer memory)427 public SP_DEVICE_INTERFACE_DATA(Pointer memory) { 428 super(memory); 429 read(); 430 } 431 } 432 433 /** 434 * An SP_DEVINFO_DATA structure defines a device instance that is a member of a device information set. 435 */ 436 @FieldOrder({"cbSize", "InterfaceClassGuid", "DevInst", "Reserved"}) 437 public static class SP_DEVINFO_DATA extends Structure { 438 439 public static class ByReference extends SP_DEVINFO_DATA implements Structure.ByReference { ByReference()440 public ByReference() { 441 } 442 ByReference(Pointer memory)443 public ByReference(Pointer memory) { 444 super(memory); 445 } 446 } 447 448 /** 449 * The size, in bytes, of the SP_DEVINFO_DATA structure. 450 */ 451 public int cbSize; 452 453 /** 454 * The GUID of the device's setup class. 455 */ 456 public Guid.GUID InterfaceClassGuid; 457 458 /** 459 * An opaque handle to the device instance (also known as a handle to the devnode). 460 * 461 * Some functions, such as SetupDiXxx functions, take the whole SP_DEVINFO_DATA structure as input to identify a 462 * device in a device information set. Other functions, such as CM_Xxx functions like CM_Get_DevNode_Status, 463 * take this DevInst handle as input. 464 */ 465 public int DevInst; 466 467 /** 468 * Reserved. For internal use only. 469 */ 470 public Pointer Reserved; 471 SP_DEVINFO_DATA()472 public SP_DEVINFO_DATA() { 473 cbSize = size(); 474 } 475 SP_DEVINFO_DATA(Pointer memory)476 public SP_DEVINFO_DATA(Pointer memory) { 477 super(memory); 478 read(); 479 } 480 } 481 } 482