GetDeviceUniqueID

Article
08/28/2006

This function returns an application-specific hash of the device identifier. The application can use this hash to uniquely identify the device.

HRESULT GetDeviceUniqueID(
  LPBYTE pbApplicationData,
  DWORD cbApplictionData,
  DWORD dwDeviceIDVersion,
  LPBYTE pbDeviceIDOutput,
  DWORD* pcbDeviceIDOutput
);

Parameters

pbApplicationData
[in] Application-provided data, which is hashed with the device identifier.

As long as the application provides the same data as this input, the same hash will always be returned on the same device, even if the device is re-flashed and/or cold-booted. This application data must have a minimum length of 8 bytes and should be unique to the application.
cbApplicationData
[in] Length of the application data, pbApplicationData.

This parameter must be at least 8 bytes or the function call will fail.
dwDeviceIDVersion
[in] Version number of the algorithm used to calculate the device identifier returned from GetDeviceUniqueID.

Currently, the only defined version number is 1. This parameter must use this value or the function call will fail.
pbDeviceIDOutput
[out] Application-provided output buffer for the device identifier.

This buffer should be at least equal to GETDEVICEUNIQUEID_VI_OUTPUT (20 bytes). If the provided buffer is smaller than the complete hash, the hash will be truncated and only the bytes that fit will be copied into the output buffer.

If the buffer is not large enough, GetDeviceUniqueID truncates the output data to fit the buffer, and then returns HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER).
pcbDeviceIDOutput
[in, out] Specifies the length of the device identifier.

The input parameter is the length of the application-supplied buffer. The output parameter is the number of bytes written into the output buffer.

If this pointer is equal to NULL, the call to GetDeviceUniqueID will fail.

Return Values

If pbApplicationData is set to NULL, this function returns E_POINTER.

If cbApplicationData is not at least 8 bytes, this function fails and returns E_INVALIDARG.

If dwDeviceIDversion is not equal to 1, this function fails and returns E_INVALIDARG.

If pbDeviceIDOutput is set to NULL, this function returns the maximum output hash length in pcbDeviceIDOutput.

If pcbDeviceIDOutput is set to NULL, this function fails and returns with E_INVALIDARG.

The following table shows the return values for GetDeviceUniqueID depending on the values of the pbDeviceIDOutput and pcbDeviceIDOutput parameters.

pbDeviceIDOutput value	pcbDeviceIDOutput value	*pcbDeviceIDOutput	Return value
NULL	Non-NULL	Ignored	S_OK is returned and GetDeviceUniqueID places the required buffer size in *pcbDeviceIDOutput.
Non-NULL	Non-NULL	Too small	HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) is returned and GetDeviceUniqueID truncates the output data to fit pbDeviceIDOutput, and puts the amount of data copied into *pcbDeviceIDOutput.
Non-NULL	Non-NULL	Large enough	S_OK is returned and GetDeviceUniqueID fills pbDeviceIDOutput with the output data and places the amount copied into *pcbDeviceIDOutput.

Remarks

GetDeviceUniqueID protects the privacy of a device. Multiple applications need to use a device's unique identifier to communicate with servers. To protect a device's privacy, multiple servers should not be able to correlate data from the same device. GetDeviceUniqueID does not use any additional information other than the data that is provided by the application, so any application that passes in the same application data buffer will obtain the same hash.

Example Code

The following code example shows how to use the GetDeviceUniqueID function.

#define DEVICE_ID_LENGTH            20
#define APPLICATION_DATA            "@^!MyAppName!^@"
#define APPLICATION_DATA_LENGTH     15

HRESULT         hr              = NOERROR;
BYTE            rgDeviceId[DEVICE_ID_LENGTH];
DWORD           cbDeviceId      = sizeof(rgDeviceId);

hr = GetDeviceUniqueID(reinterpret_cast<PBYTE>(APPLICATION_DATA),
                         APPLICATION_DATA_LENGTH,
                        GETDEVICEUNIQUEID_V1,
                        rgDeviceId,
                        &cbDeviceId);
CHR(hr);

hr = DoSomethingWithDeviceId(rgDeviceId, cbDeviceId);
        .
        .
        .

Requirements

Pocket PC: Windows Mobile 5.0 and later.
Smartphone: Windows Mobile 5.0 and later.
OS Versions: Windows CE 5.01 and later.
Header: GetDeviceUniqueId.h.
Link Library: Coredll.lib.