GetDeviceUniqueID (Compact 2013)
3/28/2014
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, 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 Value
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.
Code Example
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
Header |
getdeviceuniqueid.h |
Library |
coredll.lib |