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