Fonction RtlUnicodeStringInitEx (ntstrsafe.h)

Article
02/07/2025

La fonction RtlUnicodeStringInitEx initialise une structure UNICODE_STRING.

Syntaxe

NTSTRSAFEDDI RtlUnicodeStringInitEx(
  [out]          PUNICODE_STRING  DestinationString,
  [in, optional] NTSTRSAFE_PCWSTR pszSrc,
  [in]           DWORD            dwFlags
);

Paramètres

[out] DestinationString

Optionnel. Pointeur vers une structure UNICODE_STRING à initialiser. Le pointeur pszSrc est copié dans la structure UNICODE_STRING du paramètre destination. Le nombre maximal de caractères dans la chaîne à laquelle points de pszSrc est NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString peut être NULL, mais uniquement si STRSAFE_IGNORE_NULLS est défini dans dwFlags .

[in, optional] pszSrc

Optionnel. Pointeur vers une constante de chaîne terminée par null. Ce pointeur de chaîne est copié dans le membre Buffer de la structure UNICODE_STRING pointée par le paramètre DestinationString. Ce pointeur de chaîne peut être NULL.

[in] dwFlags

L’indicateur suivant est défini :

STRSAFE_IGNORE_NULLS

Si cet indicateur est défini, le pointeur source peut être NULL. RtlUnicodeStringInitEx traite pointeurs de mémoire tampon source tels que des chaînes vides (TEXT(« »), qui peuvent être copiés.

Valeur de retour

RtlUnicodeStringInitEx retourne l’une des valeurs NTSTATUS suivantes.

Retourner le code	Description
STATUS_SUCCESS	Cette réussite état signifie que les données sources étaient présentes, que la chaîne a été copiée sans troncation et que la mémoire tampon de destination résultante est terminée par null.
STATUS_INVALID_PARAMETER	Cette erreur état signifie que la fonction a reçu un paramètre d’entrée non valide. Pour plus d’informations, consultez la liste suivante.

RtlUnicodeStringInitEx retourne la valeur STATUS_INVALID_PARAMETER lorsque l’une des opérations suivantes se produit :

La longueur de la chaîne à laquelle le paramètre pszSrc pointe est supérieure à NTSTRSAFE_UNICODE_STRING_MAX_CCH caractères.
Le pointeur DestinationString est NULL, mais le pointeur pszSrc n’est pas NULL.

Pour plus d’informations sur la façon de tester des valeurs NTSTATUS, consultez Using NTSTATUS Values.

Remarques

La fonction RtlUnicodeStringInitEx effectue les opérations suivantes :

Définit la longueur membre de la structure UNICODE_STRING sur la longueur, en octets, de la chaîne vers laquelle pointe le paramètre pszSrc.
Définit le membre MaximumLength de la structure UNICODE_STRING sur la longueur, en octets, de la chaîne que le paramètre pszSrc pointe vers plus de 2 octets.
Définit le membre tampon de la structure UNICODE_STRING à l’adresse spécifiée par le paramètre pszSrc.

Le pointeur DestinationString ne peut pas être NULL, sauf si l’indicateur STRSAFE_IGNORE_NULLS est défini.

Pour plus d’informations sur les fonctions de chaîne sécurisée, consultez Using Safe String Functions.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible à partir de Windows XP avec Service Pack 1 (SP1).
plateforme cible	Bureau
d’en-tête	ntstrsafe.h (include Ntstrsafe.h)
bibliothèque	Ntstrsafe.lib
IRQL	Si les chaînes manipulées résident toujours en mémoire, sinon PASSIVE_LEVEL

Voir aussi

RtlUnicodeStringInit

UNICODE_STRING

Partager via