Back to index

lightning-sunbird  0.9+nobinonly
Classes | Typedefs | Enumerations | Functions
nsStreamUtils.h File Reference
#include "nsStringFwd.h"
#include "nsIInputStream.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  nsWriteSegmentThunk

Typedefs

typedef void(* nsAsyncCopyCallbackFun )(void *closure, nsresult status)
 This function is called when the async copy process completes.

Enumerations

enum  nsAsyncCopyMode { NS_ASYNCCOPY_VIA_READSEGMENTS, NS_ASYNCCOPY_VIA_WRITESEGMENTS }

Functions

NS_COM nsresult NS_NewInputStreamReadyEvent (nsIInputStreamCallback **aEvent, nsIInputStreamCallback *aNotify, nsIEventTarget *aEventTarget)
 A "one-shot" proxy of the OnInputStreamReady callback.
NS_COM nsresult NS_NewOutputStreamReadyEvent (nsIOutputStreamCallback **aEvent, nsIOutputStreamCallback *aNotify, nsIEventTarget *aEventTarget)
 A "one-shot" proxy of the OnOutputStreamReady callback.
NS_COM nsresult NS_AsyncCopy (nsIInputStream *aSource, nsIOutputStream *aSink, nsIEventTarget *aEventTarget, nsAsyncCopyMode aMode=NS_ASYNCCOPY_VIA_READSEGMENTS, PRUint32 aChunkSize=4096, nsAsyncCopyCallbackFun aCallbackFun=nsnull, void *aCallbackClosure=nsnull)
 This function asynchronously copies data from the source to the sink.
NS_COM nsresult NS_ConsumeStream (nsIInputStream *aSource, PRUint32 aMaxCount, nsACString &aBuffer)
 This function copies all of the available data from the stream (up to at most aMaxCount bytes) into the given buffer.
NS_COM PRBool NS_InputStreamIsBuffered (nsIInputStream *aInputStream)
 This function tests whether or not the input stream is buffered.
NS_COM PRBool NS_OutputStreamIsBuffered (nsIOutputStream *aOutputStream)
 This function tests whether or not the output stream is buffered.
NS_COM NS_METHOD NS_CopySegmentToStream (nsIInputStream *aInputStream, void *aClosure, const char *aFromSegment, PRUint32 aToOffset, PRUint32 aCount, PRUint32 *aWriteCount)
 This function is intended to be passed to nsIInputStream::ReadSegments to copy data from the nsIInputStream into a nsIOutputStream passed as the aClosure parameter to the ReadSegments function.
NS_COM NS_METHOD NS_CopySegmentToBuffer (nsIInputStream *aInputStream, void *aClosure, const char *aFromSegment, PRUint32 aToOffset, PRUint32 aCount, PRUint32 *aWriteCount)
 This function is intended to be passed to nsIInputStream::ReadSegments to copy data from the nsIInputStream into a character buffer passed as the aClosure parameter to the ReadSegments function.
NS_COM NS_METHOD NS_DiscardSegment (nsIInputStream *aInputStream, void *aClosure, const char *aFromSegment, PRUint32 aToOffset, PRUint32 aCount, PRUint32 *aWriteCount)
 This function is intended to be passed to nsIInputStream::ReadSegments to discard data from the nsIInputStream.
NS_COM NS_METHOD NS_WriteSegmentThunk (nsIInputStream *aInputStream, void *aClosure, const char *aFromSegment, PRUint32 aToOffset, PRUint32 aCount, PRUint32 *aWriteCount)
 This function is intended to be passed to nsIInputStream::ReadSegments to adjust the aInputStream parameter passed to a consumer's WriteSegmentFun.

Class Documentation

struct nsWriteSegmentThunk

Definition at line 223 of file nsStreamUtils.h.

Collaboration diagram for nsWriteSegmentThunk:
Class Members
void * mClosure
nsWriteSegmentFun mFun
nsIInputStream * mStream

Typedef Documentation

This function is called when the async copy process completes.

The reported status is NS_OK on success and some error code on failure.

Definition at line 90 of file nsStreamUtils.h.


Enumeration Type Documentation

Enumerator:
NS_ASYNCCOPY_VIA_READSEGMENTS 
NS_ASYNCCOPY_VIA_WRITESEGMENTS 

Definition at line 81 of file nsStreamUtils.h.


Function Documentation

NS_COM nsresult NS_AsyncCopy ( nsIInputStream aSource,
nsIOutputStream aSink,
nsIEventTarget aEventTarget,
nsAsyncCopyMode  aMode = NS_ASYNCCOPY_VIA_READSEGMENTS,
PRUint32  aChunkSize = 4096,
nsAsyncCopyCallbackFun  aCallbackFun = nsnull,
void aCallbackClosure = nsnull 
)

This function asynchronously copies data from the source to the sink.

All data transfer occurs on the thread corresponding to the given event target. A null event target is not permitted.

The copier handles blocking or non-blocking streams transparently. If a stream operation returns NS_BASE_STREAM_WOULD_BLOCK, then the stream will be QI'd to nsIAsync{In,Out}putStream and its AsyncWait method will be used to determine when to resume copying.

Definition at line 558 of file nsStreamUtils.cpp.

{
    NS_ASSERTION(target, "non-null target required");

    nsresult rv;
    nsAStreamCopier *copier;

    if (mode == NS_ASYNCCOPY_VIA_READSEGMENTS)
        copier = new nsStreamCopierIB();
    else
        copier = new nsStreamCopierOB();

    if (!copier)
        return NS_ERROR_OUT_OF_MEMORY;

    // Start() takes an owning ref to the copier...
    NS_ADDREF(copier);
    rv = copier->Start(source, sink, target, callback, closure, chunkSize);
    NS_RELEASE(copier);

    return rv;
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_COM nsresult NS_ConsumeStream ( nsIInputStream aSource,
PRUint32  aMaxCount,
nsACString &  aBuffer 
)

This function copies all of the available data from the stream (up to at most aMaxCount bytes) into the given buffer.

The buffer is truncated at the start of the function.

If an error occurs while reading from the stream or while attempting to resize the buffer, then the corresponding error code is returned from this function, and any data that has already been read will be returned in the output buffer. This allows one to use this function with a non-blocking input stream that may return NS_BASE_STREAM_WOULD_BLOCK if it only has partial data available.

Parameters:
aSourceThe input stream to read.
aMaxCountThe maximum number of bytes to consume from the stream. Pass the value PR_UINT32_MAX to consume the entire stream. The number of bytes actually read is given by the length of aBuffer upon return.
aBufferThe string object that will contain the stream data upon return. Note: The data copied to the string may contain null bytes and may contain non-ASCII values.

Definition at line 590 of file nsStreamUtils.cpp.

{
    nsresult rv = NS_OK;
    result.Truncate();

    while (maxCount) {
        PRUint32 avail;
        rv = stream->Available(&avail);
        if (NS_FAILED(rv)) {
            if (rv == NS_BASE_STREAM_CLOSED)
                rv = NS_OK;
            break;
        }
        if (avail == 0)
            break;
        if (avail > maxCount)
            avail = maxCount;

        // resize result buffer
        PRUint32 length = result.Length();
        result.SetLength(length + avail);
        if (result.Length() != (length + avail))
            return NS_ERROR_OUT_OF_MEMORY;
        char *buf = result.BeginWriting() + length;
        
        PRUint32 n;
        rv = stream->Read(buf, avail, &n);
        if (NS_FAILED(rv))
            break;
        if (n != avail)
            result.SetLength(length + n);
        if (n == 0)
            break;
        maxCount -= n;
    }

    return rv;
}

Here is the caller graph for this function:

NS_COM NS_METHOD NS_CopySegmentToBuffer ( nsIInputStream aInputStream,
void aClosure,
const char *  aFromSegment,
PRUint32  aToOffset,
PRUint32  aCount,
PRUint32 aWriteCount 
)

This function is intended to be passed to nsIInputStream::ReadSegments to copy data from the nsIInputStream into a character buffer passed as the aClosure parameter to the ReadSegments function.

The character buffer must be at least as large as the aCount parameter passed to ReadSegments.

See also:
nsIInputStream.idl for a description of this function's parameters.

Definition at line 700 of file nsStreamUtils.cpp.

{
    char *toBuf = NS_STATIC_CAST(char *, closure);
    memcpy(&toBuf[offset], buffer, count);
    *countWritten = count;
    return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_COM NS_METHOD NS_CopySegmentToStream ( nsIInputStream aInputStream,
void aClosure,
const char *  aFromSegment,
PRUint32  aToOffset,
PRUint32  aCount,
PRUint32 aWriteCount 
)

This function is intended to be passed to nsIInputStream::ReadSegments to copy data from the nsIInputStream into a nsIOutputStream passed as the aClosure parameter to the ReadSegments function.

See also:
nsIInputStream.idl for a description of this function's parameters.

Definition at line 678 of file nsStreamUtils.cpp.

{
    nsIOutputStream *outStr = NS_STATIC_CAST(nsIOutputStream *, closure);
    *countWritten = 0;
    while (count) {
        PRUint32 n;
        nsresult rv = outStr->Write(buffer, count, &n);
        if (NS_FAILED(rv))
            return rv;
        buffer += n;
        count -= n;
        *countWritten += n;
    }
    return NS_OK;
}

Here is the caller graph for this function:

NS_COM NS_METHOD NS_DiscardSegment ( nsIInputStream aInputStream,
void aClosure,
const char *  aFromSegment,
PRUint32  aToOffset,
PRUint32  aCount,
PRUint32 aWriteCount 
)

This function is intended to be passed to nsIInputStream::ReadSegments to discard data from the nsIInputStream.

This can be used to efficiently read data from the stream without actually copying any bytes.

See also:
nsIInputStream.idl for a description of this function's parameters.

Definition at line 714 of file nsStreamUtils.cpp.

{
    *countWritten = count;
    return NS_OK;
}

Here is the caller graph for this function:

This function tests whether or not the input stream is buffered.

A buffered input stream is one that implements readSegments. The test for this is to simply call readSegments, without actually consuming any data from the stream, to verify that it functions.

NOTE: If the stream is non-blocking and has no data available yet, then this test will fail. In that case, we return false even though the test is not really conclusive.

Parameters:
aInputStreamThe input stream to test.

Definition at line 645 of file nsStreamUtils.cpp.

{
    PRBool result = PR_FALSE;
    PRUint32 n;
    stream->ReadSegments(TestInputStream, &result, 1, &n);
    return result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

A "one-shot" proxy of the OnInputStreamReady callback.

The resulting proxy object's OnInputStreamReady function may only be called once! The proxy object ensures that the real notify object will be free'd on the thread corresponding to the given event target regardless of what thread the proxy object is destroyed on.

This function is designed to be used to implement AsyncWait when the aEventTarget parameter is non-null.

Here is the caller graph for this function:

A "one-shot" proxy of the OnOutputStreamReady callback.

The resulting proxy object's OnOutputStreamReady function may only be called once! The proxy object ensures that the real notify object will be free'd on the thread corresponding to the given event target regardless of what thread the proxy object is destroyed on.

This function is designed to be used to implement AsyncWait when the aEventTarget parameter is non-null.

Definition at line 246 of file nsStreamUtils.cpp.

{
    nsOutputStreamReadyEvent *ev = new nsOutputStreamReadyEvent(callback, target);
    if (!ev)
        return NS_ERROR_OUT_OF_MEMORY;
    NS_ADDREF(*event = ev);
    return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

This function tests whether or not the output stream is buffered.

A buffered output stream is one that implements writeSegments. The test for this is to simply call writeSegments, without actually writing any data into the stream, to verify that it functions.

NOTE: If the stream is non-blocking and has no available space yet, then this test will fail. In that case, we return false even though the test is not really conclusive.

Parameters:
aOutputStreamThe output stream to test.

Definition at line 667 of file nsStreamUtils.cpp.

{
    PRBool result = PR_FALSE;
    PRUint32 n;
    stream->WriteSegments(TestOutputStream, &result, 1, &n);
    return result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

NS_COM NS_METHOD NS_WriteSegmentThunk ( nsIInputStream aInputStream,
void aClosure,
const char *  aFromSegment,
PRUint32  aToOffset,
PRUint32  aCount,
PRUint32 aWriteCount 
)

This function is intended to be passed to nsIInputStream::ReadSegments to adjust the aInputStream parameter passed to a consumer's WriteSegmentFun.

The aClosure parameter must be a pointer to a nsWriteSegmentThunk object. The mStream and mClosure members of that object will be passed to the mFun function, with the remainder of the parameters being what are passed to NS_WriteSegmentThunk.

This function comes in handy when implementing ReadSegments in terms of an inner stream's ReadSegments.

Definition at line 728 of file nsStreamUtils.cpp.

{
    nsWriteSegmentThunk *thunk = NS_STATIC_CAST(nsWriteSegmentThunk *, closure);
    return thunk->mFun(thunk->mStream, thunk->mClosure, buffer, offset, count,
                       countWritten);
}

Here is the caller graph for this function: