diff options
Diffstat (limited to 'netwerk/base/nsITransport.idl')
| -rw-r--r-- | netwerk/base/nsITransport.idl | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/netwerk/base/nsITransport.idl b/netwerk/base/nsITransport.idl new file mode 100644 index 0000000000..c9aaa94083 --- /dev/null +++ b/netwerk/base/nsITransport.idl @@ -0,0 +1,163 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#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(2a8c6334-a5e6-4ec3-9865-1256541446fb)] +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 guaranteed 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). + * + * In C++, these constants have a type of uint32_t, so C++ callers must use + * the NS_NET_STATUS_* constants defined below, which have a type of + * nsresult. + */ + 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, -1 will be passed. + */ + void onTransportStatus(in nsITransport aTransport, + in nsresult aStatus, + in long long aProgress, + in long long aProgressMax); +}; |