| /* ***** 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. |
| * |
| * The Initial Developer of the Original Code is |
| * Netscape Communications Corporation. |
| * Portions created by the Initial Developer are Copyright (C) 2002 |
| * the Initial Developer. All Rights Reserved. |
| * |
| * Contributor(s): |
| * Darin Fisher <darin@netscape.com> |
| * |
| * 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 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 "nsISupports.idl" |
| |
| interface nsIInputStream; |
| interface nsIOutputStream; |
| interface nsITransportEventSink; |
| interface nsIEventTarget; |
| |
| /** |
| * nsITransport |
| * |
| * This interface provides a common way of accessing i/o streams connected |
| * to some resource. This interface does not in any way specify the resource. |
| * It provides methods to open blocking or non-blocking, buffered or unbuffered |
| * streams to the resource. The name "transport" is meant to connote the |
| * inherent data transfer implied by this interface (i.e., data is being |
| * transfered in some fashion via the streams exposed by this interface). |
| * |
| * A transport can have an event sink associated with it. The event sink |
| * receives transport-specific events as the transfer is occuring. For a |
| * socket transport, these events can include status about the connection. |
| * See nsISocketTransport for more info about socket transport specifics. |
| */ |
| [scriptable, uuid(d8786c64-eb49-4a0b-b42c-0936a745fbe8)] |
| interface nsITransport : nsISupports |
| { |
| /** |
| * Open flags. |
| */ |
| const unsigned long OPEN_BLOCKING = 1<<0; |
| const unsigned long OPEN_UNBUFFERED = 1<<1; |
| |
| /** |
| * Open an input stream on this transport. |
| * |
| * Flags have the following meaning: |
| * |
| * OPEN_BLOCKING |
| * If specified, then the resulting stream will have blocking stream |
| * semantics. This means that if the stream has no data and is not |
| * closed, then reading from it will block the calling thread until |
| * at least one byte is available or until the stream is closed. |
| * If this flag is NOT specified, then the stream has non-blocking |
| * stream semantics. This means that if the stream has no data and is |
| * not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK. |
| * In addition, in non-blocking mode, the stream is guaranteed to |
| * support nsIAsyncInputStream. This interface allows the consumer of |
| * the stream to be notified when the stream can again be read. |
| * |
| * OPEN_UNBUFFERED |
| * If specified, the resulting stream may not support ReadSegments. |
| * ReadSegments is only gauranteed to be implemented when this flag is |
| * NOT specified. |
| * |
| * @param aFlags |
| * optional transport specific flags. |
| * @param aSegmentSize |
| * if OPEN_UNBUFFERED is not set, then this parameter specifies the |
| * size of each buffer segment (pass 0 to use default value). |
| * @param aSegmentCount |
| * if OPEN_UNBUFFERED is not set, then this parameter specifies the |
| * maximum number of buffer segments (pass 0 to use default value). |
| */ |
| nsIInputStream openInputStream(in unsigned long aFlags, |
| in unsigned long aSegmentSize, |
| in unsigned long aSegmentCount); |
| |
| /** |
| * Open an output stream on this transport. |
| * |
| * Flags have the following meaning: |
| * |
| * OPEN_BLOCKING |
| * If specified, then the resulting stream will have blocking stream |
| * semantics. This means that if the stream is full and is not closed, |
| * then writing to it will block the calling thread until ALL of the |
| * data can be written or until the stream is closed. If this flag is |
| * NOT specified, then the stream has non-blocking stream semantics. |
| * This means that if the stream is full and is not closed, then writing |
| * to it returns NS_BASE_STREAM_WOULD_BLOCK. In addition, in non- |
| * blocking mode, the stream is guaranteed to support |
| * nsIAsyncOutputStream. This interface allows the consumer of the |
| * stream to be notified when the stream can again accept more data. |
| * |
| * OPEN_UNBUFFERED |
| * If specified, the resulting stream may not support WriteSegments and |
| * WriteFrom. WriteSegments and WriteFrom are only gauranteed to be |
| * implemented when this flag is NOT specified. |
| * |
| * @param aFlags |
| * optional transport specific flags. |
| * @param aSegmentSize |
| * if OPEN_UNBUFFERED is not set, then this parameter specifies the |
| * size of each buffer segment (pass 0 to use default value). |
| * @param aSegmentCount |
| * if OPEN_UNBUFFERED is not set, then this parameter specifies the |
| * maximum number of buffer segments (pass 0 to use default value). |
| */ |
| nsIOutputStream openOutputStream(in unsigned long aFlags, |
| in unsigned long aSegmentSize, |
| in unsigned long aSegmentCount); |
| |
| /** |
| * Close the transport and any open streams. |
| * |
| * @param aReason |
| * the reason for closing the stream. |
| */ |
| void close(in nsresult aReason); |
| |
| /** |
| * Set the transport event sink. |
| * |
| * @param aSink |
| * receives transport layer notifications |
| * @param aEventTarget |
| * indicates the event target to which the notifications should |
| * be delivered. if NULL, then the notifications may occur on |
| * any thread. |
| */ |
| void setEventSink(in nsITransportEventSink aSink, |
| in nsIEventTarget aEventTarget); |
| |
| /** |
| * Generic nsITransportEventSink status codes. nsITransport |
| * implementations may override these status codes with their own more |
| * specific status codes (e.g., see nsISocketTransport). |
| */ |
| const unsigned long STATUS_READING = 0x804b0008; |
| const unsigned long STATUS_WRITING = 0x804b0009; |
| }; |
| |
| [scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)] |
| interface nsITransportEventSink : nsISupports |
| { |
| /** |
| * Transport status notification. |
| * |
| * @param aTransport |
| * the transport sending this status notification. |
| * @param aStatus |
| * the transport status (resolvable to a string using |
| * nsIErrorService). See nsISocketTransport for socket specific |
| * status codes and more comments. |
| * @param aProgress |
| * the amount of data either read or written depending on the value |
| * of the status code. this value is relative to aProgressMax. |
| * @param aProgressMax |
| * the maximum amount of data that will be read or written. if |
| * unknown, 0xFFFFFFFF will be passed. |
| */ |
| void onTransportStatus(in nsITransport aTransport, |
| in nsresult aStatus, |
| in unsigned long long aProgress, |
| in unsigned long long aProgressMax); |
| }; |
