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

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée 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 au langage ou sur LOCALE_NEUTRAL. L’LOCALE_NEUTRAL LCID spécifie que la propriété n’est pas linguistique (c’est-à-dire qu’elle n’est spécifique à aucune 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ées dans la mémoire tampon PropertyData .

Valeur retournée

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 celle que le pilote UMDF a précédemment inscrite.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	Le pilote peut demander des données de propriété d’interface d’appareil 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 RootSpecifier 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 basés sur UMDF.

Exemples

Pour les propriétés de taille variable, le pilote doit effectuer 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 le PropertyDataRequiredSize retourné et appeler à nouveau GetPropertyData , en passant 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

Condition requise	Valeur
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