WdfStringCreate, fonction (wdfstring.h)

Article
03/05/2024

[S’applique à KMDF et UMDF]

La méthode WdfStringCreate crée un objet de chaîne d’infrastructure et affecte éventuellement une chaîne Unicode spécifiée à l’objet .

Syntaxe

NTSTATUS WdfStringCreate(
  [in, optional] PCUNICODE_STRING       UnicodeString,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringAttributes,
  [out]          WDFSTRING              *String
);

Paramètres

[in, optional] UnicodeString

Pointeur vers une structure UNICODE_STRING qui contient une constante de chaîne Unicode. L’infrastructure copie la chaîne dans le nouvel objet de chaîne de framework. Ce pointeur est facultatif et peut être NULL.

[in, optional] StringAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs fournis par le pilote pour le nouvel objet string. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] String

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet de chaîne.

Valeur retournée

WdfStringCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	WdfStringCreate n’a pas été appelé dans IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet string.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfStringCreate peut retourner, consultez Erreurs de création d’objets framework.

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

Remarques

Le parent par défaut pour les objets de chaîne d’infrastructure est l’objet pilote d’infrastructure du pilote. Toutefois, à moins que la chaîne ne soit associée au pilote, votre pilote doit définir le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES sur un objet qui représente l’étendue de la chaîne. En règle générale, les chaînes sont spécifiques à l’appareil et leur objet parent doit être un objet d’appareil framework.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet de chaîne d’infrastructure, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Pour plus d’informations sur les objets de chaîne d’infrastructure, consultez Utilisation d’objets de chaîne.

Exemples

L’exemple de code suivant initialise une structure WDF_OBJECT_ATTRIBUTES , puis crée un objet de chaîne de framework.

NTSTATUS  status;
WDFSTRING  stringHandle = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = pDeviceContext->Device;
status = WdfStringCreate(
                         NULL,
                         &attributes,
                         &stringHandle
                         );
if (!NT_SUCCESS(status)){
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfstring.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfStringGetUnicodeString

Partager via