1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsITransport.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,163 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIInputStream;
1.11 +interface nsIOutputStream;
1.12 +interface nsITransportEventSink;
1.13 +interface nsIEventTarget;
1.14 +
1.15 +/**
1.16 + * nsITransport
1.17 + *
1.18 + * This interface provides a common way of accessing i/o streams connected
1.19 + * to some resource. This interface does not in any way specify the resource.
1.20 + * It provides methods to open blocking or non-blocking, buffered or unbuffered
1.21 + * streams to the resource. The name "transport" is meant to connote the
1.22 + * inherent data transfer implied by this interface (i.e., data is being
1.23 + * transfered in some fashion via the streams exposed by this interface).
1.24 + *
1.25 + * A transport can have an event sink associated with it. The event sink
1.26 + * receives transport-specific events as the transfer is occuring. For a
1.27 + * socket transport, these events can include status about the connection.
1.28 + * See nsISocketTransport for more info about socket transport specifics.
1.29 + */
1.30 +[scriptable, uuid(d8786c64-eb49-4a0b-b42c-0936a745fbe8)]
1.31 +interface nsITransport : nsISupports
1.32 +{
1.33 + /**
1.34 + * Open flags.
1.35 + */
1.36 + const unsigned long OPEN_BLOCKING = 1<<0;
1.37 + const unsigned long OPEN_UNBUFFERED = 1<<1;
1.38 +
1.39 + /**
1.40 + * Open an input stream on this transport.
1.41 + *
1.42 + * Flags have the following meaning:
1.43 + *
1.44 + * OPEN_BLOCKING
1.45 + * If specified, then the resulting stream will have blocking stream
1.46 + * semantics. This means that if the stream has no data and is not
1.47 + * closed, then reading from it will block the calling thread until
1.48 + * at least one byte is available or until the stream is closed.
1.49 + * If this flag is NOT specified, then the stream has non-blocking
1.50 + * stream semantics. This means that if the stream has no data and is
1.51 + * not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK.
1.52 + * In addition, in non-blocking mode, the stream is guaranteed to
1.53 + * support nsIAsyncInputStream. This interface allows the consumer of
1.54 + * the stream to be notified when the stream can again be read.
1.55 + *
1.56 + * OPEN_UNBUFFERED
1.57 + * If specified, the resulting stream may not support ReadSegments.
1.58 + * ReadSegments is only gauranteed to be implemented when this flag is
1.59 + * NOT specified.
1.60 + *
1.61 + * @param aFlags
1.62 + * optional transport specific flags.
1.63 + * @param aSegmentSize
1.64 + * if OPEN_UNBUFFERED is not set, then this parameter specifies the
1.65 + * size of each buffer segment (pass 0 to use default value).
1.66 + * @param aSegmentCount
1.67 + * if OPEN_UNBUFFERED is not set, then this parameter specifies the
1.68 + * maximum number of buffer segments (pass 0 to use default value).
1.69 + */
1.70 + nsIInputStream openInputStream(in unsigned long aFlags,
1.71 + in unsigned long aSegmentSize,
1.72 + in unsigned long aSegmentCount);
1.73 +
1.74 + /**
1.75 + * Open an output stream on this transport.
1.76 + *
1.77 + * Flags have the following meaning:
1.78 + *
1.79 + * OPEN_BLOCKING
1.80 + * If specified, then the resulting stream will have blocking stream
1.81 + * semantics. This means that if the stream is full and is not closed,
1.82 + * then writing to it will block the calling thread until ALL of the
1.83 + * data can be written or until the stream is closed. If this flag is
1.84 + * NOT specified, then the stream has non-blocking stream semantics.
1.85 + * This means that if the stream is full and is not closed, then writing
1.86 + * to it returns NS_BASE_STREAM_WOULD_BLOCK. In addition, in non-
1.87 + * blocking mode, the stream is guaranteed to support
1.88 + * nsIAsyncOutputStream. This interface allows the consumer of the
1.89 + * stream to be notified when the stream can again accept more data.
1.90 + *
1.91 + * OPEN_UNBUFFERED
1.92 + * If specified, the resulting stream may not support WriteSegments and
1.93 + * WriteFrom. WriteSegments and WriteFrom are only guaranteed to be
1.94 + * implemented when this flag is NOT specified.
1.95 + *
1.96 + * @param aFlags
1.97 + * optional transport specific flags.
1.98 + * @param aSegmentSize
1.99 + * if OPEN_UNBUFFERED is not set, then this parameter specifies the
1.100 + * size of each buffer segment (pass 0 to use default value).
1.101 + * @param aSegmentCount
1.102 + * if OPEN_UNBUFFERED is not set, then this parameter specifies the
1.103 + * maximum number of buffer segments (pass 0 to use default value).
1.104 + */
1.105 + nsIOutputStream openOutputStream(in unsigned long aFlags,
1.106 + in unsigned long aSegmentSize,
1.107 + in unsigned long aSegmentCount);
1.108 +
1.109 + /**
1.110 + * Close the transport and any open streams.
1.111 + *
1.112 + * @param aReason
1.113 + * the reason for closing the stream.
1.114 + */
1.115 + void close(in nsresult aReason);
1.116 +
1.117 + /**
1.118 + * Set the transport event sink.
1.119 + *
1.120 + * @param aSink
1.121 + * receives transport layer notifications
1.122 + * @param aEventTarget
1.123 + * indicates the event target to which the notifications should
1.124 + * be delivered. if NULL, then the notifications may occur on
1.125 + * any thread.
1.126 + */
1.127 + void setEventSink(in nsITransportEventSink aSink,
1.128 + in nsIEventTarget aEventTarget);
1.129 +
1.130 + /**
1.131 + * Generic nsITransportEventSink status codes. nsITransport
1.132 + * implementations may override these status codes with their own more
1.133 + * specific status codes (e.g., see nsISocketTransport).
1.134 + *
1.135 + * In C++, these constants have a type of uint32_t, so C++ callers must use
1.136 + * the NS_NET_STATUS_* constants defined below, which have a type of
1.137 + * nsresult.
1.138 + */
1.139 + const unsigned long STATUS_READING = 0x804b0008;
1.140 + const unsigned long STATUS_WRITING = 0x804b0009;
1.141 +};
1.142 +
1.143 +[scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)]
1.144 +interface nsITransportEventSink : nsISupports
1.145 +{
1.146 + /**
1.147 + * Transport status notification.
1.148 + *
1.149 + * @param aTransport
1.150 + * the transport sending this status notification.
1.151 + * @param aStatus
1.152 + * the transport status (resolvable to a string using
1.153 + * nsIErrorService). See nsISocketTransport for socket specific
1.154 + * status codes and more comments.
1.155 + * @param aProgress
1.156 + * the amount of data either read or written depending on the value
1.157 + * of the status code. this value is relative to aProgressMax.
1.158 + * @param aProgressMax
1.159 + * the maximum amount of data that will be read or written. if
1.160 + * unknown, 0xFFFFFFFF will be passed.
1.161 + */
1.162 + void onTransportStatus(in nsITransport aTransport,
1.163 + in nsresult aStatus,
1.164 + in unsigned long long aProgress,
1.165 + in unsigned long long aProgressMax);
1.166 +};
