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. |
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); |
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 |