IOCTL_HAL_GET_DEVICEID
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/27/2008
This IOCTL returns the current DEVICE_ID structure assigned to the device. A request to retrieve the DEVICE_ID is made by calling the KernelIoControl function with IOCTL_HAL_GET_DEVICEID.
This IOCTL is being deprecated, starting with Windows Embedded CE 6.0. Its functionality has been integrated into IOCTL_HAL_GET_DEVICE_INFO. For more information, see Device Information IOCTL Unification.
Parameters
- dwIoControlCode
[in] Set to IOCTL_HAL_GET_DEVICEID to retrieve the DEVICE_ID structure.
- lpInBuf
[in] Unused. Must be set to NULL.
- nInBufSize
[in] Unused. Must be set to 0.
- lpOutBuf
[in] Set to the address of an allocated DEVICE_ID structure.
- nOutBufSize
[in] Set to the size of the DEVICE_ID structure.
lpBytesReturned
[in] Address of a DWORD that receives the size, in bytes, of the data structure that contains the device identification information.This parameter is optional. If you do not need this value, set this parameter to NULL.
Return Values
If the system supports IOCTL_HAL_GET_DEVICEID and the parameters are correct, this returns TRUE for success. If support is not provided for IOCTL_HAL_GET_DEVICEID or the request fails, this returns FALSE. FALSE is also returned when querying the IOCTL for the correct data structure size. See the Remarks section for more information.
Remarks
This IOCTL allows the caller to obtain the DEVICE_ID structure associated with the device and to determine the size of the structure. It is recommended that you query the system for the structure size so that you can allocate the right buffer size, and then get the actual device DEVICE_ID data structure.
To query the structure size
Allocate a DEVICE_ID structure and then set the dwSize value to zero
Pass the DEVICE_ID structure to KernelIoControl using IOCTL_HAL_GET_DEVICEID.
The KernelIoControl call will return FALSE and GetLastError will return ERROR_INSUFFICIENT_BUFFER. The dwSize member in the DEVICE_ID structure will contain the number of bytes needed for the device identification information. In this case, the lpBytesReturned value is not set.
To get the device identification information
Allocate a large enough buffer and then call KernelIoControl using IOCTL_HAL_GET_DEVICEID.
The data will be copied into lpOutBuf. If lpBytesReturned is not NULL, then this address will contain the size of the data copied to the buffer. This should be equal to the dwSize parameter in the DEVICE_ID data structure.
If this process is successful, the function returns TRUE. If an error occurs, this function returns FALSE and sets GetLastError. If GetLastError equals ERROR_INSUFFICIENT_BUFFER, the dwSize parameter will not be set to the size needed for the data structure.
Requirements
| Header | pkfuncs.h |
| Windows Embedded CE | Windows CE 2.10 and later |
See Also
Reference
Concepts
Device Information IOCTL Unification
Identifying Devices Uniquely