Fonction RtlUnicodeStringInitEx (ntstrsafe.h)

Article
05/03/2024

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

Facultatif. Pointeur vers une structure UNICODE_STRING à initialiser. Le pointeur pszSrc est copié dans la structure UNICODE_STRING du paramètre DestinationString. Le nombre maximal de caractères dans la chaîne vers laquelle pointe 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

facultatif. Pointeur vers une constante de chaîne terminée par null. Ce pointeur de chaîne sera copié vers 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 les pointeurs de mémoire tampon source NULL comme les chaînes vides (TEXT(« »)), qui peuvent être copiées.

Valeur retournée

RtlUnicodeStringInitEx retourne l’une des valeurs NTSTATUS suivantes.

Code de retour	Description
STATUS_SUCCESS	Cette réussite status 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 un caractère Null.
STATUS_INVALID_PARAMETER	Cette erreur status 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’un des éléments suivants se produit :

La longueur de la chaîne vers laquelle pointe le paramètre pszSrc 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 les valeurs NTSTATUS, consultez Utilisation de valeurs NTSTATUS.

Remarques

La fonction RtlUnicodeStringInitEx effectue les opérations suivantes :

Définit le membre Length 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 vers laquelle pointe le paramètre pszSrc plus 2 octets.
Définit le membre Buffer de la structure UNICODE_STRING sur 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 Utilisation de fonctions de chaîne sécurisée.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows XP avec Service Pack 1 (SP1).
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ntstrsafe.h (include Ntstrsafe.h)
Bibliothèque	Ntstrsafe.lib
IRQL	Toutes les chaînes si manipulées résident toujours en mémoire, sinon PASSIVE_LEVEL

Voir aussi

RtlUnicodeStringInit

UNICODE_STRING

Partager via