Método IWDFUnifiedPropertyStore::GetPropertyData (wudfddi.h)

Artículo
08/08/2023

[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
E_OUTOFMEMORY	Error en el intento del marco de trabajo de asignar memoria.
HRESULT_FROM_NT(STATUS_BUFFER_TOO_SMALL)	El parámetro PropertyDataRequiredSize contiene el tamaño del búfer necesario.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Si el controlador especifica WdfPropertyStoreRootClassDeviceInterfaceKey, la interfaz solicitada debe ser la que el controlador UMDF registró anteriormente.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	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