IOCTL_HAL_GET_DEVICEID (Windows Embedded CE 6.0)

  • Article

1/5/2010

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

  1. Allocate a DEVICE_ID structure and then set the dwSize value to zero

  2. 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

  1. 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

Device Information IOCTLs
DEVICE_ID

Concepts

Device Information IOCTL Unification
Identifying Devices Uniquely

Other Resources

KernelIoControl