IWDFUnifiedPropertyStore::GetPropertyData, méthode (wudfddi.h)

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide de UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et il existe une prise en charge limitée de UMDF 1 sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode GetPropertyData récupère le paramètre actuel d’une propriété d’appareil.

Syntaxe

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

Paramètres

[in] PropertyKey

Pointeur vers une structure DEVPROPKEY qui spécifie la clé de propriété de l’appareil.

[in] Lcid

Spécifie un identificateur de paramètres régionaux. Définissez ce paramètre sur une valeur LCID spécifique à la langue ou sur LOCALE_NEUTRAL. Le LOCALE_NEUTRAL LCID spécifie que la propriété est indépendante de la langue (c’est-à-dire qu’elle n’est pas spécifique à une langue). Ne définissez pas ce paramètre sur LOCALE_SYSTEM_DEFAULT ou LOCALE_USER_DEFAULT. Pour plus d’informations sur les valeurs LCID spécifiques à la langue, consultez structure LCID.

[in] Flags

Réservé pour le système. Les pilotes doivent définir cette valeur sur 0.

[in] PropertyDataSize

Taille, en octets, de la mémoire tampon vers laquelle PropertyData pointe.

[out, optional] PropertyData

Pointeur vers les données de propriété de l’appareil.

[out] PropertyDataRequiredSize

Pointeur vers un ULONG pour recevoir la taille des informations de propriété retournées dans PropertyData.

[out] PropertyType

Pointeur vers une valeur DEVPROPTYPE . Si GetPropertyData se termine correctement, la méthode utilise PropertyType pour fournir le type de données retourné dans la mémoire tampon PropertyData .

Valeur de retour

GetPropertyData retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner les valeurs suivantes.

Code de retour Description
E_OUTOFMEMORY
La tentative d’allocation de mémoire de l’infrastructure a échoué.
HRESULT_FROM_NT(STATUS_BUFFER_TOO_SMALL)
Le paramètre PropertyDataRequiredSize contient la taille de la mémoire tampon requise.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)
Si le pilote spécifie WdfPropertyStoreRootClassDeviceInterfaceKey, l’interface demandée doit être une interface que le pilote UMDF précédemment inscrit.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)
Le pilote peut demander des données de propriété d’interface de périphérique uniquement à partir de Windows 8.
 

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.

Remarques

Les pilotes basés sur l’infrastructure utilisent la méthode GetPropertyData pour récupérer les propriétés d’appareil définies dans le cadre du modèle de propriété d’appareil unifié.

En particulier, vous pouvez utiliser cette méthode pour récupérer la clé matérielle d’un appareil ou une instance d’une classe d’interface d’appareil. Lorsque vous appelez IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, définissez le membre RootClass du paramètre RootClass sur WdfPropertyStoreRootClassHardwareKey ou WdfPropertyStoreRootClassDeviceInterfaceKey.

Si vous spécifiez WdfPropertyStoreRootClassHardwareKey, lorsque vous appelez GetPropertyData, vous devez fournir une valeur DEVPROPKEY personnalisée dans le paramètre PropertyKey et non une clé Définie par PnP. La valeur doit avoir été définie précédemment en appelant SetPropertyData, une fonction de propriété d’appareil SetupDI ou à l’aide de la directive INF AddProperty.

Pour plus d’informations sur les propriétés de l’appareil, consultez Propriétés de l’appareil.

Pour plus d’informations sur l’accès au Registre, consultez Utilisation du Registre dans les pilotes UMDF.

Exemples

Pour les propriétés de taille variable, le pilote doit passer deux passes pour récupérer les données de propriété. Tout d’abord, le pilote doit passer une mémoire tampon NULL dans le paramètre PropertyData et définir PropertyDataSize sur 0. Ensuite, le pilote doit allouer une mémoire tampon basée sur PropertyDataRequiredSize retournée et appeler à nouveau GetPropertyData , en transmettant la mémoire tampon allouée.

L'exemple ci-dessous illustre ce modèle.

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;
}

Configuration requise

   
Fin de la prise en charge Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible Desktop (Expérience utilisateur)
Version UMDF minimale 1.11
En-tête wudfddi.h
DLL WUDFx.dll

Voir aussi

IWDFUnifiedPropertyStore

IWDFUnifiedPropertyStoreFactory

RetrieveUnifiedDevicePropertyStore

SetPropertyData

WDF_PROPERTY_STORE_ROOT

WDF_PROPERTY_STORE_ROOT_CLASS