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 |
|---|---|
|
La tentative d’allocation de mémoire de l’infrastructure a échoué. |
|
Le paramètre PropertyDataRequiredSize contient la taille de la mémoire tampon requise. |
|
Si le pilote spécifie WdfPropertyStoreRootClassDeviceInterfaceKey, l’interface demandée doit être une interface que le pilote UMDF précédemment inscrit. |
|
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
IWDFUnifiedPropertyStoreFactory