/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: NPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Netscape 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/NPL/ * * 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 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 NPL, 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 NPL, 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; } %}