Método IWDFUnifiedPropertyStore::GetPropertyData (wudfddi.h)
[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.
El método GetPropertyData recupera la configuración actual de una propiedad de dispositivo.
Sintaxis
HRESULT GetPropertyData(
[in] const DEVPROPKEY *PropertyKey,
[in] LCID Lcid,
[in] ULONG Flags,
[in] ULONG PropertyDataSize,
[out, optional] PVOID PropertyData,
[out] ULONG *PropertyDataRequiredSize,
[out] DEVPROPTYPE *PropertyType
);
Parámetros
[in] PropertyKey
Puntero a una estructura DEVPROPKEY que especifica la clave de propiedad del dispositivo.
[in] Lcid
Especifica un identificador de configuración regional. Establezca este parámetro en un valor LCID específico del lenguaje o en LOCALE_NEUTRAL. La LOCALE_NEUTRAL LCID especifica que la propiedad es independiente del idioma (es decir, no específica de ningún idioma). No establezca este parámetro en LOCALE_SYSTEM_DEFAULT o LOCALE_USER_DEFAULT. Para obtener más información sobre los valores lcID específicos del lenguaje, vea LCID Structure.
[in] Flags
Reservado para uso del sistema. Los controladores deben establecer este valor en 0.
[in] PropertyDataSize
Tamaño, en bytes, del búfer al que apunta PropertyData .
[out, optional] PropertyData
Puntero a los datos de la propiedad del dispositivo.
[out] PropertyDataRequiredSize
Puntero a un ULONG para recibir el tamaño de la información de propiedad que se devuelve en PropertyData.
[out] PropertyType
Puntero a un valor DEVPROPTYPE . Si GetPropertyData se completa correctamente, el método usa PropertyType para proporcionar el tipo de datos que se devuelven en el búfer PropertyData .
Valor devuelto
GetPropertyData devuelve S_OK si la operación se realiza correctamente. De lo contrario, el método podría devolver los valores siguientes.
| Código devuelto | Descripción |
|---|---|
|
Error en el intento del marco de trabajo de asignar memoria. |
|
El parámetro PropertyDataRequiredSize contiene el tamaño del búfer necesario. |
|
Si el controlador especifica WdfPropertyStoreRootClassDeviceInterfaceKey, la interfaz solicitada debe ser la que el controlador UMDF registró anteriormente. |
|
El controlador solo puede solicitar datos de propiedad de interfaz de dispositivo a partir de Windows 8. |
Este método podría devolver uno de los otros valores que contiene Winerror.h .
Comentarios
Los controladores basados en marcos usan el método GetPropertyData para recuperar las propiedades del dispositivo que se definen como parte del modelo de propiedades de dispositivo unificado.
En concreto, puede usar este método para recuperar la clave de hardware de un dispositivo o una instancia de una clase de interfaz de dispositivo. Al llamar a IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, establezca el miembro RootClass del parámetro RootSpecifier en WdfPropertyStoreRootClassHardwareKey o WdfPropertyStoreRootClassDeviceInterfaceKey.
Si especifica WdfPropertyStoreRootClassHardwareKey, al llamar a GetPropertyData, debe proporcionar un valor DEVPROPKEY personalizado en el parámetro PropertyKey y no una clave definida por PnP. El valor se debe haber establecido previamente llamando a SetPropertyData, una función de propiedad de dispositivo SetupDI o mediante la directiva AddProperty inf.
Para obtener más información sobre las propiedades del dispositivo, consulte Propiedades del dispositivo.
Para obtener más información sobre el acceso al registro, consulte Uso del Registro en controladores basados en UMDF.
Ejemplos
En el caso de las propiedades de tamaño variable, el controlador debe realizar dos pasos para recuperar los datos de propiedad. En primer lugar, el controlador debe pasar un búfer NULL en el parámetro PropertyData y establecer PropertyDataSize en 0. A continuación, el controlador debe asignar un búfer basado en propertyDataRequiredSize devuelto y llamar a GetPropertyData de nuevo, pasando el búfer asignado.
El ejemplo siguiente demuestra este patrón.
HRESULT
GetFriendlyName(
_In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
)
{
HRESULT hr = S_OK;
DEVPROPTYPE type;
ULONG requiredSize;
BYTE * friendlyNameBuffer = NULL;
ULONG friendlyNameBufferSize;
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
0, //BufferSize
NULL, //Buffer
&requiredSize,
&type
);
if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
friendlyNameBufferSize = requiredSize;
friendlyNameBuffer = new BYTE[requiredSize];
if (NULL == friendlyNameBuffer)
{
hr = E_OUTOFMEMORY;
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Out of memory while allocating property data buffer returning:”
“ %!HRESULT!",
hr
);
goto exit;
}
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
friendlyNameBufferSize,
friendlyNameBuffer,
&requiredSize,
&type
);
if (FAILED(hr))
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
if (type != DEVPROP_TYPE_STRING)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Expected type %d, actual type: %d",
DEVPROP_TYPE_STRING,
type
);
hr = E_UNEXPECTED;
goto exit;
}
exit:
delete [] friendlyNameBuffer;
friendlyNameBuffer = NULL;
return hr;
}
Requisitos
| Requisito | Value |
|---|---|
| Finalización del soporte técnico | No disponible en UMDF 2.0 y versiones posteriores. |
| Plataforma de destino | Escritorio |
| Versión mínima de UMDF | 1.11 |
| Encabezado | wudfddi.h |
| Archivo DLL | WUDFx.dll |
Consulte también
IWDFUnifiedPropertyStoreFactory