nsIOutputStream

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

An interface describing a writable stream of data.
Inherits from: nsISupports Last changed in Gecko 1.0

Un flux de sortie peut être «bloquant» ou «non-bloquant" (voir le IsNonBlocking() méthode). Un flux de sortie bloquant peut suspendre le thread appelant afin de satisfaire un appel à Close(), Flush(), write(), writeFrom(), ou writeSegments(). Un flux de sortie non-bloquant, d'autre part, ne bloque pas l'exécution du thread appelant .

Note : Le blocage des flux de sortie est souvent écrits dans un thread arrière pour éviter de bloquer le fil principal de l'application. Pour cette raison, généralement dans le cas où un flux de sortie de blocage doit être implémentée on utilise thread-safe AddRef et Release.

Méthode

void close();
void flush();
boolean isNonBlocking();
unsigned long write(in string aBuf, in unsigned long aCount);
unsigned long writeFrom(in nsIInputStream aFromStream, in unsigned long aCount);
unsigned long writeSegments(in nsReadSegmentFun aReader, in voidPtr aClosure, in unsigned long aCount); Native code only!

Methods

close()

Close the stream. Forces the output stream to flush() any buffered data.

Note : This method may be called more than once, but subsequent calls are ignored.

void close();
Parameters

None.

Exceptions thrown
NS_BASE_STREAM_WOULD_BLOCK
Indicates that closing the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if isNonBlocking() returns true.

flush()

Cette méthode peut être appelée pour demander le flux de sortie pour écrire le contenu de tous les tampons internes à un collecteur de données de bas niveau, comme un fichier sur le disque. Cependant, la méthode flush peut tout simplement ne rien faire en fonction de la mise en œuvre du flux de sortie.

void flush();
Parameters

None.

Exceptions thrown
NS_BASE_STREAM_WOULD_BLOCK
Indicates that flushing the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if isNonBlocking() returns true.

isNonBlocking()

Note : Writing to a blocking output stream will block the calling thread until all given data can be consumed by the stream.

Note : A non-blocking output stream may implement nsIAsyncOutputStream to provide consumers with a way to wait for the stream to accept more data once its write() method is unable to accept any data without blocking.

boolean isNonBlocking();
Parameters

None.

Return value

true if stream is non-blocking.

Exceptions thrown
NS_BASE_STREAM_WOULD_BLOCK
A non-blocking stream may throw this exception when written to if space for the data is not immediately available.

write()

Cette méthode copies des données à partir d'un tampon dans le flux.

Note : Though this method is scriptable, JavaScript code must only pass an ASCII character string as the aBuf parameter. C++ code may however pass any arbitrary binary data, including data with embedded null bytes.

unsigned long write(
  in string aBuf,
  in unsigned long aCount
);
Parameters
aBuf
The buffer containing the data to be written.
aCount
The size of the buffer, or the maximum number of bytes to copy from the buffer.
Return value

This method returns the number of bytes copied from the buffer (may be less than aCount).

Exceptions thrown
NS_BASE_STREAM_WOULD_BLOCK
If writing to the output stream would block the calling thread (non-blocking mode only)

writeFrom()

Cette méthode copies des données à partir d'une nsIInputStream à notre nsIOutputStream.

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

Note : This method is defined by this interface in order to allow the output stream to efficiently copy the data from the input stream into its internal buffer (if any). If this method was provided as an external facility, a separate char* buffer would need to be used in order to call the output stream's other Write() method.

unsigned long writeFrom(
  in nsIInputStream aFromStream,
  in unsigned long aCount
);
Parameters
aFromStream
An nsIInputStream containing the data to be written.
aCount
The maximum number of bytes to write to the stream.
Return value

This method returns the number of bytes written to the stream (may be less than aCount).

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 implement this method. Typically, output streams that do not have an internal buffer will not implement this method since such an implementation would require an intermediate buffer unless aFromStream supported nsIInputStream.readSegments(), but that is not guaranteed.

Native code only!

writeSegments

Méthode d'écriture de bas niveau qui a accès à un tampon sous-jacente du flux. La fonction de lecteur peut être appelée plusieurs fois pour les tampons segmentés. Cette méthode devrait continuer à appeler le lecteur jusqu'à ce qu'il n'y a plus rien à écrire ou le lecteur renvoie une erreur. Cette méthode ne devrait pas appeler le lecteur avec zéro octets à fournir.

Note : 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.

unsigned long writeSegments(
  in nsReadSegmentFun aReader,
  in voidPtr aClosure,
  in unsigned long aCount
);
Parameters
aReader
A callback function that may be called multiple times. See nsReadSegmentFun for more details on this function.
aClosure
A parameter that is passed to aReader each time it is called.
aCount
The maximum number of bytes to write to the stream.
Return value

This method returns the number of bytes written to the stream (may be less than aCount).

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.

Example

writeSegments() example
 // 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);
 }

Remarks

This interface was frozen for Gecko 1.0. See bug 124465 for details. From Gecko 2.0 interfaces are no longer frozen.

See also

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : jmh
 Dernière mise à jour par : jmh,