Méthode ISequentialStream ::Write (objidl.h)

Article
03/04/2024

La méthode Write écrit un nombre spécifié d’octets dans l’objet de flux en commençant par le pointeur de recherche actuel.

Syntaxe

HRESULT Write(
  [in]  const void *pv,
  [in]  ULONG      cb,
  [out] ULONG      *pcbWritten
);

Paramètres

[in] pv

Pointeur vers la mémoire tampon qui contient les données à écrire dans le flux. Un pointeur valide doit être fourni pour ce paramètre même lorsque cb est égal à zéro.

[in] cb

Nombre d’octets de données à tenter d’écrire dans le flux. Cette valeur peut être zéro.

[out] pcbWritten

Pointeur vers une variable ULONG où cette méthode écrit le nombre réel d’octets écrits dans l’objet de flux. L’appelant peut définir ce pointeur sur NULL, auquel cas cette méthode ne fournit pas le nombre réel d’octets écrits.

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Les données ont été correctement écrites dans l’objet stream.
E_PENDING	Stockage asynchrone uniquement : une partie ou la totalité des données à écrire ne sont actuellement pas disponibles.
STG_E_MEDIUMFULL	L’opération d’écriture a échoué, car il n’y a plus d’espace sur le périphérique de stockage.
STG_E_ACCESSDENIED	L’appelant ne dispose pas des autorisations requises pour écrire dans cet objet de flux.
STG_E_CANTSAVE	Les données ne peuvent pas être écrites pour des raisons autres qu’un accès incorrect ou un espace insuffisant.
STG_E_INVALIDPOINTER	L’une des valeurs de pointeur n’est pas valide. Le paramètre pv doit contenir un pointeur valide même si cb est égal à zéro.
STG_E_REVERTED	L’objet a été invalidé par une opération de rétablissement au-dessus de lui dans l’arborescence des transactions.
STG_E_WRITEFAULT	L’opération d’écriture a échoué en raison d’une erreur de disque. Cette valeur est également retournée lorsque cette méthode tente d’écrire dans un flux ouvert en mode simple (à l’aide de l’indicateur STGM_SIMPLE).

Remarques

ISequentialStream ::Write écrit les données spécifiées dans un objet de flux. Le pointeur de recherche est ajusté pour le nombre d’octets réellement écrits. Le nombre d’octets réellement écrits est retourné dans le paramètre pcbWritten . Si le nombre d’octets est égal à zéro octet, l’opération d’écriture n’a aucun effet.

Si le pointeur de recherche dépasse actuellement la fin du flux et que le nombre d’octets est différent de zéro, cette méthode augmente la taille du flux au pointeur de recherche et écrit les octets spécifiés en commençant par le pointeur de recherche. Les octets de remplissage écrits dans le flux ne sont pas initialisés à une valeur particulière. Il s’agit du même comportement que le comportement de fin de fichier dans le système de fichiers MS-DOS FAT.

Avec un nombre d’octets nul et un pointeur de recherche au-delà de la fin du flux, cette méthode ne crée pas les octets de remplissage pour augmenter le flux au pointeur de recherche. Dans ce cas, vous devez appeler la méthode IStream ::SetSize pour augmenter la taille du flux et écrire les octets de remplissage.

Le paramètre pcbWritten peut avoir une valeur même si une erreur se produit.

Dans l’implémentation fournie par COM, les objets de flux ne sont pas partiellement alloués. Tous les octets de remplissage sont finalement alloués sur le disque et affectés au flux.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	objidl.h
Bibliothèque	Uuid.lib
DLL	Ole32.dll