WdfRegistryQueryUnicodeString, fonction (wdfregistry.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfRegistryQueryUnicodeString récupère les données de chaîne actuellement affectées à une valeur de chaîne de Registre spécifiée et copie la chaîne dans une structure UNICODE_STRING spécifiée.

Syntaxe

NTSTATUS WdfRegistryQueryUnicodeString(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [out, optional] PUSHORT          ValueByteLength,
  [in, out]       PUNICODE_STRING  Value
);

Paramètres

[in] Key

Handle vers un objet de clé de Registre qui représente une clé de Registre ouverte.

[in] ValueName

Pointeur vers une structure UNICODE_STRING qui contient un nom pour la valeur de Registre.

[out, optional] ValueByteLength

Pointeur vers un emplacement qui reçoit le nombre d’octets contenus dans la chaîne Unicode vers laquelle Valeur pointe, y compris la fin NULL octet. Ce pointeur est facultatif et peut être NULL

[in, out] Value

Pointeur vers une structure UNICODE_STRING qui reçoit la chaîne de données de la clé qui clé spécifie. Si ce paramètre est NULL et ValueByteLength n’est pasNULL, WdfRegistryQueryUnicodeString retourne uniquement la taille de la chaîne.

Valeur de retour

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

Retourner le code	Description
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryUnicodeString n’a pas été appelée à IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Il n’y avait pas de mémoire suffisante pour terminer l’opération.
STATUS_ACCESS_DENIED	Le pilote n’a pas ouvert la clé de Registre avec KEY_QUERY_VALUE, KEY_READ ou un accès KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Le type de données de la valeur de Registre que le paramètre ValueName spécifié n’a pas été REG_SZ.
STATUS_BUFFER_OVERFLOW	Mémoire tampon vers laquelle la valeur points de paramètre était trop petite, et seules les données partielles ont été écrites dans la mémoire tampon.
STATUS_BUFFER_OVERFLOW	Mémoire tampon vers laquelle la valeur points de paramètre était trop petite et aucune donnée n’a été écrite dans la mémoire tampon.
STATUS_OBJECT_NAME_NOT_FOUND	La valeur du Registre n’a pas été disponible.

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

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Pour plus d’informations sur les objets de clé de Registre, consultez Utilisation du Registre dans Framework-Based Drivers.

Exemples

L’exemple de code suivant, qui provient de l’exemple de pilote série, récupère la chaîne Unicode qui représente les données de chaîne affectées à la valeur PortName sous la clé matérielle d’un appareil.

NTSTATUS
SerialReadSymName(
    IN WDFDEVICE Device,
    __out PWCHAR RegName,
    IN OUT PUSHORT LengthOfRegName // In characters
    )
{
    NTSTATUS status;
    WDFKEY hKey;
    UNICODE_STRING value;
    UNICODE_STRING valueName;
    USHORT requiredLength;

    value.Buffer = RegName;
    value.MaximumLength = *LengthOfRegName;
    value.Length = 0;

    status = WdfDeviceOpenRegistryKey(
                                      Device,
                                      PLUGPLAY_REGKEY_DEVICE,
                                      STANDARD_RIGHTS_ALL,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &hKey
                                      );

    if (NT_SUCCESS (status)) {
        RtlInitUnicodeString(
                             &valueName,
                             L"PortName"
                             );
        status = WdfRegistryQueryUnicodeString (
                                      hKey,
                                      &valueName,
                                      &requiredLength,
                                      &value
                                      );
        WdfRegistryClose(hKey);
    }
    return status;
}

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfregistry.h (include 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)