writeSegments

Summary

This method provides direct access to the stream's internal buffer for writing.

 [noscript] unsigned long writeSegments(
   in nsReadSegmentFun aReader,
   in voidPtr aClosure,
   in unsigned long aCount
 );

Parameters

aReader

[in] A callback function that may be called multiple times. See nsReadSegmentFun for more details on this function.

aClosure

[in] A parameter that is passed to aReader each time it is called.

aCount

[in] The maximum number of bytes to write to the stream.

Return Values

This method returns the number of bytes written to the stream.

Exceptions Thrown

NS_BASE_STREAM_WOULD_BLOCK

Indicates that writing to the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if isNonBlocking returns true.

NS_ERROR_NOT_IMPLEMENTED

Indicates that the stream does not have an internal buffer that can be written to directly.

Remarks

A nsIOutputStream is not required to implement this method. In some contexts, writeSegments may be guaranteed to be implemented, but in general it is not. This method serves as an optimization.

Example Code

 // Copy data from a string to a stream

 static NS_METHOD CopySegment(nsIInputStream* aStream,
                              void* aClosure,
                              char* aToSegment,
                              PRUint32 aFromOffset,
                              PRUint32 aCount,
                              PRUint32* aReadCount)
 {
   // aFromSegment now contains aCount bytes of data.

   nsACString* pBuf = (nsACString*) aClosure;

   const char* data;
   PRUint32 len = NS_CStringGetData(&data);

   data += aFromOffset;
   len -= aFromOffset;

   if (len > aCount)
     len = aCount;
   memcpy(aToSegment, data, len);

   // Indicate that we have copied len bytes to the segment
   *aReadCount = len;
   return NS_OK;
 }

 // Write the contents of aSource into aStream, using WriteSegments
 // to avoid intermediate buffer copies.
 nsresult WriteStream(const nsACString& aSource, nsIInputStream* aStream)
 {
   PRUint32 num;
   return aStream->WriteSegments(CopySegment, (void*) &aSource,
                                 aSource.Length(), &num);
 }

See Also

isNonBlocking, nsIOutputStream, nsReadSegmentFun