Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 162 insertions, 0 deletions

diff --git a/netwerk/base/nsITransport.idl b/netwerk/base/nsITransport.idl
new file mode 100644
index 0000000000..856c4e2000
--- /dev/null
+++ b/netwerk/base/nsITransport.idl
@@ -0,0 +1,162 @@
+/* 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 = 0x4b0008;
+    const unsigned long STATUS_WRITING = 0x4b0009;
+};
+
+[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. 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);
+};