Méthode IWDFUnifiedPropertyStore ::GetPropertyData (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 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 |
|---|---|
|
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 celle que le pilote UMDF a précédemment inscrite. |
|
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 |
Voir aussi
IWDFUnifiedPropertyStoreFactory