WdfPdoInitAddDeviceText, fonction (wdfpdo.h)

[S’applique à KMDF uniquement]

La méthode WdfPdoInitAddDeviceText ajoute une description de l’appareil et l’emplacement de l’appareil à un appareil, pour un paramètre régional spécifié.

Syntaxe

NTSTATUS WdfPdoInitAddDeviceText(
  [in] PWDFDEVICE_INIT  DeviceInit,
  [in] PCUNICODE_STRING DeviceDescription,
  [in] PCUNICODE_STRING DeviceLocation,
  [in] LCID             LocaleId
);

Paramètres

[in] DeviceInit

Pointeur vers une structure WDFDEVICE_INIT .

[in] DeviceDescription

Pointeur vers une structure UNICODE_STRING qui contient une description d’appareil, mise en forme pour les paramètres régionaux donnés. Le pilote peut allouer la mémoire tampon de la chaîne à partir d’un pool paginé.

[in] DeviceLocation

Pointeur vers une structure UNICODE_STRING qui contient une description de l’emplacement sur le bus où l’appareil parent a trouvé l’enfant. Le pilote peut allouer la mémoire tampon de la chaîne à partir d’un pool paginé.

[in] LocaleId

Identificateur de paramètres régionaux (LCID) qui représente les paramètres régionaux des chaînes Unicode. Pour plus d’informations, consultez Identificateurs de paramètres régionaux.

Valeur retournée

Si l’opération réussit, la méthode retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Le pilote initialise un FDO au lieu d’un PDO.
STATUS_INSUFFICIENT_RESOURCES	Le pilote n’a pas pu allouer d’espace pour stocker les chaînes.

 

La méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

L’infrastructure stocke le texte de l’appareil spécifié et le transmet au gestionnaire PnP en réponse à une demande de IRP_MN_QUERY_DEVICE_TEXT . Le texte que vous fournissez doit aider l’utilisateur à identifier l’appareil. Le gestionnaire PnP affiche parfois le texte lors de la tentative d’installation de pilotes supplémentaires pour l’appareil.

Vous pouvez appeler WdfPdoInitAddDeviceText plusieurs fois, en ajoutant du texte d’appareil pour plusieurs paramètres régionaux. Lorsque le système affiche le texte, il choisit le texte qui correspond aux paramètres régionaux actuels, s’il est disponible. Sinon, il utilisera la chaîne pour les paramètres régionaux par défaut. Le pilote peut spécifier les paramètres régionaux par défaut du pilote en appelant WdfPdoInitSetDefaultLocale.

Le pilote doit appeler WdfPdoInitAddDeviceText avant d’appeler WdfDeviceCreate. Pour plus d’informations sur l’appel de WdfDeviceCreate, consultez Création d’un objet d’appareil framework.

Exemples

L’exemple de code suivant fournit des chaînes Unicode pour l’emplacement et la description d’un appareil. La description inclut un nombre instance. Pour obtenir un exemple complet qui utilise WdfPdoInitAddDeviceText, consultez l’exemple de pilote KbFiltr .

DECLARE_CONST_UNICODE_STRING(deviceLocation,L"Keyboard Filter\0" );
DECLARE_UNICODE_STRING_SIZE(buffer, MAX_ID_LEN);

status = RtlUnicodeStringPrintf(
                                &buffer,
                                L"Keyboard_Filter_%02d",
                                InstanceNo
                                );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}
status = WdfPdoInitAddDeviceText(
                                 pDeviceInit,
                                 &buffer,
                                 &deviceLocation,
                                 0x409
                                 );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfpdo.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	ChildDeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)

Voir aussi

WdfPdoInitSetDefaultLocale