Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

A version of this page is also available for

4/8/2010

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

Syntax


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, GetDeviceUniqueIDtruncates 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 GetDeviceUniqueIDwill fail.

Return Value

If pbApplicationDatais set to NULL, this function returns E_POINTER.

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

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

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

If pcbDeviceIDOutputis 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 pbDeviceIDOutputand pcbDeviceIDOutputparameters.

pbDeviceIDOutput value	pcbDeviceIDOutput value	*pcbDeviceIDOutput	Return value
NULL	Non-NULL	Ignored	S_OK is returned and GetDeviceUniqueIDplaces the required buffer size in *pcbDeviceIDOutput.
Non-NULL	Non-NULL	Too small	HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) is returned and GetDeviceUniqueIDtruncates 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 GetDeviceUniqueIDfills pbDeviceIDOutputwith the output data and places the amount copied into *pcbDeviceIDOutput.

Remarks

GetDeviceUniqueIDprotects 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. GetDeviceUniqueIDdoes 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.

Code Example

The following code example shows how to use the GetDeviceUniqueIDfunction.

	Copy Code
#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);

Copy Code

#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

Header	getdeviceuniqueid.h
Library	coredll.lib
Windows Embedded CE	Windows Embedded CE 6.0 and later
Windows Mobile	Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

Syntax

Parameters

Return Value

Remarks

Code Example

Requirements

See Also

Reference

Other Resources