IStream::Write
Writes a
specified number from bytes into the stream object starting at the current seek
pointer.
HRESULT Write(
|
void const* pv, |
//Pointer
to buffer from which stream is written |
|
ULONG cb, |
//Specifies
the number of bytes to write |
|
ULONG * pcbWritten |
//Specifies
the actual number of bytes written |
|
); |
|
Parameters
pv
[in] Points
to the buffer from which the stream should be written.
cb
[in] The
number of bytes of data to attempt to write into the stream.
pcbWritten
[out] Pointer
to a location where this method writes the actual number of bytes written to
the stream object. The caller can set this pointer to NULL, in which case, this
method does not provide the actual number of bytes written.
Return Values
S_OK
The data was
successfully written into the stream object.
E_PENDING
Asynchronous
Storage only: Part or all of the data to be written is currently unavailable.
For more information see IFillLockBytes and Asynchronous Storage.
STG_E_MEDIUMFULL
The write
operation was not completed because there is no space left on the storage
device.
STG_E_ACCESSDENIED
The caller
does not have sufficient permissions for writing this stream object.
STG_E_CANTSAVE
Data cannot
be written for reasons other than no access or space.
STG_E_INVALIDPOINTER
One of the
pointer values is invalid.
STG_E_REVERTED
The object
has been invalidated by a revert operation above it in the transaction tree.
STG_E_WRITEFAULT
The write
operation was not completed due to a disk error.
Remarks
IStream::Write writes the specified data to a stream object. The
seek pointer is adjusted for the number of bytes actually written. The number
of bytes actually written is returned in the pcbWrite parameter. If the
byte count is zero bytes, the write operation has no effect.
If the seek
pointer is currently past the end of the stream and the byte count is non-zero,
this method increases the size of the stream to the seek pointer and writes the
specified bytes starting at the seek pointer. The fill bytes written to the stream
are not initialized to any particular value. This is the same as the
end-of-file behavior in the MS-DOS FAT file system.
With a zero
byte count and a seek pointer past the end of the stream, this method does not
create the fill bytes to increase the stream to the seek pointer. In this case,
you must call the IStream::SetSize method to increase the size of the stream and
write the fill bytes.
The pcbWrite
parameter can have a value even if an error occurs.
In the
OLE-provided implementation, stream objects are not sparse. Any fill bytes are
eventually allocated on the disk and assigned to the stream.
See Also