Fonction WindowsPreallocateStringBuffer (winstring.h)

  • Article

Alloue une mémoire tampon de caractères mutables à utiliser dans la création de HSTRING .

Syntaxe

HRESULT WindowsPreallocateStringBuffer(
  UINT32         length,
  WCHAR          **charBuffer,
  HSTRING_BUFFER *bufferHandle
);

Paramètres

length

Type : [in] UINT32

Taille de la mémoire tampon à allouer. La valeur zéro correspond à la chaîne vide.

charBuffer

Type : [out] WCHAR**

Mémoire tampon mutable qui contient les caractères. Notez que la mémoire tampon contient déjà un caractère NULL de fin.

bufferHandle

Type : [out] HSTRING_BUFFER*

Mémoire tampon de chaîne préallouée, ou NULL si la longueur est 0.

Valeur retournée

Type : HRESULT

Cette fonction peut retourner l’une de ces valeurs.

Code de retour Description
S_OK
 Le HSTRING a été créé avec succès.
E_POINTER
 mutableBuffer ou bufferHandle a lavaleur NULL.
MEM_E_INVALID_SIZE
 La taille d’allocation HSTRING demandée est trop grande.
E_OUTOFMEMORY
 Impossible d’allouer le HSTRING.

Remarques

Utilisez la fonction WindowsPreallocateStringBuffer pour créer une mémoire tampon de caractères mutables que vous pouvez manipuler avant de la valider dans un HSTRING immuable. Une fois que vous avez terminé de remplir le mutableBuffer avec votre chaîne, appelez la fonction WindowsPromoteStringBuffer avec le paramètre bufferHandle pour créer le HSTRING. Vous devez écrire exactement des caractères de longueur dans la mémoire tampon. Windows 10 version 1803, Windows Server version 1803 et versions ultérieures : vous êtes autorisé à écrire une terminaison null après des caractères de longueur.

Appelez la fonction WindowsDeleteStringBuffer pour ignorer la mémoire tampon mutable avant la promotion. Si la mémoire tampon a déjà été promue par un appel à WindowsPromoteStringBuffer, appelez la fonction WindowsDeleteString pour ignorer la chaîne. Si l’appel WindowsPromoteStringBuffer échoue, vous pouvez appeler la fonction WindowsDeleteStringBuffer pour ignorer la mémoire tampon mutable.

Exemples

L’exemple de code suivant montre comment utiliser la fonction WindowsPreallocateStringBuffer .

#include <winstring.h>

int main()
{
    HSTRING hString = NULL;
    HSTRING_BUFFER hStringBuffer = NULL;
    PWSTR strBuffer = NULL;

    HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer);

    if (SUCCEEDED(hr))
    {
        CopyMemory(strBuffer, L"1234567890", 10 * sizeof(wchar_t));
        hr = WindowsPromoteStringBuffer(hStringBuffer, &hString);
    }

    WindowsDeleteString(hString);  
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 8 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête winstring.h
Bibliothèque RuntimeObject.lib
DLL ComBase.dll

Voir aussi

HSTRING

HSTRING_BUFFER

WindowsDeleteStringBuffer

WindowsPromoteStringBuffer