/gecko_sdk/idl/nsIOutputStream.idl
IDL | 183 lines | 25 code | 10 blank | 148 comment | 0 complexity | df854b9e13a96583584d57c3e8388456 MD5 | raw file
1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is mozilla.org code. 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 1998 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * Warren Harris <warren@netscape.com> 24 * Darin Fisher <darin@netscape.com> 25 * 26 * Alternatively, the contents of this file may be used under the terms of 27 * either of the GNU General Public License Version 2 or later (the "GPL"), 28 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 29 * in which case the provisions of the GPL or the LGPL are applicable instead 30 * of those above. If you wish to allow use of your version of this file only 31 * under the terms of either the GPL or the LGPL, and not to allow others to 32 * use your version of this file under the terms of the MPL, indicate your 33 * decision by deleting the provisions above and replace them with the notice 34 * and other provisions required by the GPL or the LGPL. If you do not delete 35 * the provisions above, a recipient may use your version of this file under 36 * the terms of any one of the MPL, the GPL or the LGPL. 37 * 38 * ***** END LICENSE BLOCK ***** */ 39 40#include "nsISupports.idl" 41 42interface nsIOutputStream; 43interface nsIInputStream; 44 45%{C++ 46/** 47 * The signature for the reader function passed to WriteSegments. This 48 * is the "provider" of data that gets written into the stream's buffer. 49 * 50 * @param aOutStream stream being written to 51 * @param aClosure opaque parameter passed to WriteSegments 52 * @param aToSegment pointer to memory owned by the output stream 53 * @param aFromOffset amount already written (since WriteSegments was called) 54 * @param aCount length of toSegment 55 * @param aReadCount number of bytes written 56 * 57 * Implementers should return the following: 58 * 59 * @return NS_OK and (*aReadCount > 0) if successfully provided some data 60 * @return NS_OK and (*aReadCount = 0) or 61 * @return <any-error> if not interested in providing any data 62 * 63 * Errors are never passed to the caller of WriteSegments. 64 * 65 * @status FROZEN 66 */ 67typedef NS_CALLBACK(nsReadSegmentFun)(nsIOutputStream *aOutStream, 68 void *aClosure, 69 char *aToSegment, 70 PRUint32 aFromOffset, 71 PRUint32 aCount, 72 PRUint32 *aReadCount); 73%} 74 75native nsReadSegmentFun(nsReadSegmentFun); 76 77/** 78 * nsIOutputStream 79 * 80 * An interface describing a writable stream of data. An output stream may be 81 * "blocking" or "non-blocking" (see the IsNonBlocking method). A blocking 82 * output stream may suspend the calling thread in order to satisfy a call to 83 * Close, Flush, Write, WriteFrom, or WriteSegments. A non-blocking output 84 * stream, on the other hand, must not block the calling thread of execution. 85 * 86 * NOTE: blocking output streams are often written to on a background thread to 87 * avoid locking up the main application thread. For this reason, it is 88 * generally the case that a blocking output stream should be implemented using 89 * thread- safe AddRef and Release. 90 * 91 * @status FROZEN 92 */ 93[scriptable, uuid(0d0acd2a-61b4-11d4-9877-00c04fa0cf4a)] 94interface nsIOutputStream : nsISupports 95{ 96 /** 97 * Close the stream. Forces the output stream to flush any buffered data. 98 * 99 * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking 100 * the calling thread (non-blocking mode only) 101 */ 102 void close(); 103 104 /** 105 * Flush the stream. 106 * 107 * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking 108 * the calling thread (non-blocking mode only) 109 */ 110 void flush(); 111 112 /** 113 * Write data into the stream. 114 * 115 * @param aBuf the buffer containing the data to be written 116 * @param aCount the maximum number of bytes to be written 117 * 118 * @return number of bytes written (may be less than aCount) 119 * 120 * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would 121 * block the calling thread (non-blocking mode only) 122 * @throws <other-error> on failure 123 */ 124 unsigned long write(in string aBuf, in unsigned long aCount); 125 126 /** 127 * Writes data into the stream from an input stream. 128 * 129 * @param aFromStream the stream containing the data to be written 130 * @param aCount the maximum number of bytes to be written 131 * 132 * @return number of bytes written (may be less than aCount) 133 * 134 * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would 135 * block the calling thread (non-blocking mode only) 136 * @throws <other-error> on failure 137 * 138 * NOTE: This method is defined by this interface in order to allow the 139 * output stream to efficiently copy the data from the input stream into 140 * its internal buffer (if any). If this method was provided as an external 141 * facility, a separate char* buffer would need to be used in order to call 142 * the output stream's other Write method. 143 */ 144 unsigned long writeFrom(in nsIInputStream aFromStream, 145 in unsigned long aCount); 146 147 /** 148 * Low-level write method that has access to the stream's underlying buffer. 149 * The reader function may be called multiple times for segmented buffers. 150 * WriteSegments is expected to keep calling the reader until either there 151 * is nothing left to write or the reader returns an error. WriteSegments 152 * should not call the reader with zero bytes to provide. 153 * 154 * @param aReader the "provider" of the data to be written 155 * @param aClosure opaque parameter passed to reader 156 * @param aCount the maximum number of bytes to be written 157 * 158 * @return number of bytes written (may be less than aCount) 159 * 160 * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would 161 * block the calling thread (non-blocking mode only) 162 * @throws NS_ERROR_NOT_IMPLEMENTED if the stream has no underlying buffer 163 * @throws <other-error> on failure 164 * 165 * NOTE: this function may be unimplemented if a stream has no underlying 166 * buffer (e.g., socket output stream). 167 */ 168 [noscript] unsigned long writeSegments(in nsReadSegmentFun aReader, 169 in voidPtr aClosure, 170 in unsigned long aCount); 171 172 /** 173 * @return true if stream is non-blocking 174 * 175 * NOTE: writing to a blocking output stream will block the calling thread 176 * until all given data can be consumed by the stream. 177 * 178 * NOTE: a non-blocking output stream may implement nsIAsyncOutputStream to 179 * provide consumers with a way to wait for the stream to accept more data 180 * once its write method is unable to accept any data without blocking. 181 */ 182 boolean isNonBlocking(); 183};