mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-05 08:35:26 +00:00
212 lines
8.6 KiB
Plaintext
212 lines
8.6 KiB
Plaintext
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
*
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
* http://www.mozilla.org/MPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
* for the specific language governing rights and limitations under the
|
|
* License.
|
|
*
|
|
* The Original Code is mozilla.org code.
|
|
*
|
|
* The Initial Developer of the Original Code is
|
|
* Netscape Communications Corporation.
|
|
* Portions created by the Initial Developer are Copyright (C) 1998
|
|
* the Initial Developer. All Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
*
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
* either of the GNU General Public License Version 2 or later (the "GPL"),
|
|
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
* the provisions above, a recipient may use your version of this file under
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
*
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
#include "nsIAsyncInputStream.idl"
|
|
#include "nsIAsyncOutputStream.idl"
|
|
|
|
interface nsIMemory;
|
|
|
|
/**
|
|
* nsIPipe represents an in-process buffer that can be read using nsIInputStream
|
|
* and written using nsIOutputStream. The reader and writer of a pipe do not
|
|
* have to be on the same thread. As a result, the pipe is an ideal mechanism
|
|
* to bridge data exchange between two threads. For example, a worker thread
|
|
* might write data to a pipe from which the main thread will read.
|
|
*
|
|
* Each end of the pipe can be either blocking or non-blocking. Recall that a
|
|
* non-blocking stream will return NS_BASE_STREAM_WOULD_BLOCK if it cannot be
|
|
* read or written to without blocking the calling thread. For example, if you
|
|
* try to read from an empty pipe that has not yet been closed, then if that
|
|
* pipe's input end is non-blocking, then the read call will fail immediately
|
|
* with NS_BASE_STREAM_WOULD_BLOCK as the error condition. However, if that
|
|
* pipe's input end is blocking, then the read call will not return until the
|
|
* pipe has data or until the pipe is closed. This example presumes that the
|
|
* pipe is being filled asynchronously on some background thread.
|
|
*
|
|
* The pipe supports nsIAsyncInputStream and nsIAsyncOutputStream, which give
|
|
* the user of a non-blocking pipe the ability to wait for the pipe to become
|
|
* ready again. For example, in the case of an empty non-blocking pipe, the
|
|
* user can call AsyncWait on the input end of the pipe to be notified when
|
|
* the pipe has data to read (or when the pipe becomes closed).
|
|
*
|
|
* NS_NewPipe2 and NS_NewPipe provide convenient pipe constructors. In most
|
|
* cases nsIPipe is not actually used. It is usually enough to just get
|
|
* references to the pipe's input and output end. In which case, the pipe is
|
|
* automatically closed when the respective pipe ends are released.
|
|
*/
|
|
[scriptable, uuid(f4211abc-61b3-11d4-9877-00c04fa0cf4a)]
|
|
interface nsIPipe : nsISupports
|
|
{
|
|
/**
|
|
* initialize this pipe
|
|
*/
|
|
void init(in boolean nonBlockingInput,
|
|
in boolean nonBlockingOutput,
|
|
in unsigned long segmentSize,
|
|
in unsigned long segmentCount,
|
|
in nsIMemory segmentAllocator);
|
|
|
|
/**
|
|
* The pipe's input end, which also implements nsISearchableInputStream.
|
|
*/
|
|
readonly attribute nsIAsyncInputStream inputStream;
|
|
|
|
/**
|
|
* The pipe's output end.
|
|
*/
|
|
readonly attribute nsIAsyncOutputStream outputStream;
|
|
};
|
|
|
|
/**
|
|
* XXX this interface doesn't really belong in here. It is here because
|
|
* currently nsPipeInputStream is the only implementation of this interface.
|
|
*/
|
|
[scriptable, uuid(8C39EF62-F7C9-11d4-98F5-001083010E9B)]
|
|
interface nsISearchableInputStream : nsISupports
|
|
{
|
|
/**
|
|
* Searches for a string in the input stream. Since the stream has a notion
|
|
* of EOF, it is possible that the string may at some time be in the
|
|
* buffer, but is is not currently found up to some offset. Consequently,
|
|
* both the found and not found cases return an offset:
|
|
* if found, return offset where it was found
|
|
* if not found, return offset of the first byte not searched
|
|
* In the case the stream is at EOF and the string is not found, the first
|
|
* byte not searched will correspond to the length of the buffer.
|
|
*/
|
|
void search(in string forString,
|
|
in boolean ignoreCase,
|
|
out boolean found,
|
|
out unsigned long offsetSearchedTo);
|
|
};
|
|
|
|
%{C++
|
|
|
|
/**
|
|
* NS_NewPipe2
|
|
*
|
|
* This function supercedes NS_NewPipe. It differs from NS_NewPipe in two
|
|
* major ways:
|
|
* (1) returns nsIAsyncInputStream and nsIAsyncOutputStream, so it is
|
|
* not necessary to QI in order to access these interfaces.
|
|
* (2) the size of the pipe is determined by the number of segments
|
|
* times the size of each segment.
|
|
*
|
|
* @param pipeIn
|
|
* resulting input end of the pipe
|
|
* @param pipeOut
|
|
* resulting output end of the pipe
|
|
* @param nonBlockingInput
|
|
* true specifies non-blocking input stream behavior
|
|
* @param nonBlockingOutput
|
|
* true specifies non-blocking output stream behavior
|
|
* @param segmentSize
|
|
* specifies the segment size in bytes (pass 0 to use default value)
|
|
* @param segmentCount
|
|
* specifies the max number of segments (pass 0 to use default value)
|
|
* passing PR_UINT32_MAX here causes the pipe to have "infinite" space.
|
|
* this mode can be useful in some cases, but should always be used with
|
|
* caution. the default value for this parameter is a finite value.
|
|
* @param segmentAlloc
|
|
* pass reference to nsIMemory to have all pipe allocations use this
|
|
* allocator (pass null to use the default allocator)
|
|
*/
|
|
extern NS_COM nsresult
|
|
NS_NewPipe2(nsIAsyncInputStream **pipeIn,
|
|
nsIAsyncOutputStream **pipeOut,
|
|
PRBool nonBlockingInput = PR_FALSE,
|
|
PRBool nonBlockingOutput = PR_FALSE,
|
|
PRUint32 segmentSize = 0,
|
|
PRUint32 segmentCount = 0,
|
|
nsIMemory *segmentAlloc = nsnull);
|
|
|
|
/**
|
|
* NS_NewPipe
|
|
*
|
|
* Preserved for backwards compatibility. Plus, this interface is more
|
|
* amiable in certain contexts (e.g., when you don't need the pipe's async
|
|
* capabilities).
|
|
*
|
|
* @param pipeIn
|
|
* resulting input end of the pipe
|
|
* @param pipeOut
|
|
* resulting output end of the pipe
|
|
* @param segmentSize
|
|
* specifies the segment size in bytes (pass 0 to use default value)
|
|
* @param maxSize
|
|
* specifies the max size of the pipe (pass 0 to use default value)
|
|
* number of segments is maxSize / segmentSize, and maxSize must be a
|
|
* multiple of segmentSize. passing PR_UINT32_MAX here causes the
|
|
* pipe to have "infinite" space. this mode can be useful in some
|
|
* cases, but should always be used with caution. the default value
|
|
* for this parameter is a finite value.
|
|
* @param nonBlockingInput
|
|
* true specifies non-blocking input stream behavior
|
|
* @param nonBlockingOutput
|
|
* true specifies non-blocking output stream behavior
|
|
* @param segmentAlloc
|
|
* pass reference to nsIMemory to have all pipe allocations use this
|
|
* allocator (pass null to use the default allocator)
|
|
*/
|
|
inline nsresult
|
|
NS_NewPipe(nsIInputStream **pipeIn,
|
|
nsIOutputStream **pipeOut,
|
|
PRUint32 segmentSize = 0,
|
|
PRUint32 maxSize = 0,
|
|
PRBool nonBlockingInput = PR_FALSE,
|
|
PRBool nonBlockingOutput = PR_FALSE,
|
|
nsIMemory *segmentAlloc = nsnull)
|
|
{
|
|
PRUint32 segmentCount;
|
|
if (segmentSize == 0)
|
|
segmentCount = 0; // use default
|
|
else
|
|
segmentCount = maxSize / segmentSize;
|
|
|
|
nsIAsyncInputStream *in;
|
|
nsIAsyncOutputStream *out;
|
|
nsresult rv = NS_NewPipe2(&in, &out, nonBlockingInput, nonBlockingOutput,
|
|
segmentSize, segmentCount, segmentAlloc);
|
|
if (NS_FAILED(rv)) return rv;
|
|
|
|
*pipeIn = in;
|
|
*pipeOut = out;
|
|
return NS_OK;
|
|
}
|
|
|
|
%}
|