netwerk/base/nsITransport.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIInputStream;
   8 interface nsIOutputStream;
   9 interface nsITransportEventSink;
  10 interface nsIEventTarget;
  11
  12 /**
  13  * nsITransport
  14  *
  15  * This interface provides a common way of accessing i/o streams connected
  16  * to some resource.  This interface does not in any way specify the resource.
  17  * It provides methods to open blocking or non-blocking, buffered or unbuffered
  18  * streams to the resource.  The name "transport" is meant to connote the
  19  * inherent data transfer implied by this interface (i.e., data is being
  20  * transfered in some fashion via the streams exposed by this interface).
  21  *
  22  * A transport can have an event sink associated with it.  The event sink
  23  * receives transport-specific events as the transfer is occuring.  For a
  24  * socket transport, these events can include status about the connection.
  25  * See nsISocketTransport for more info about socket transport specifics.
  26  */
  27 [scriptable, uuid(2a8c6334-a5e6-4ec3-9865-1256541446fb)]
  28 interface nsITransport : nsISupports
  29 {
  30     /**
  31      * Open flags.
  32      */
  33     const unsigned long OPEN_BLOCKING   = 1<<0;
  34     const unsigned long OPEN_UNBUFFERED = 1<<1;
  35
  36     /**
  37      * Open an input stream on this transport.
  38      *
  39      * Flags have the following meaning:
  40      *
  41      * OPEN_BLOCKING
  42      *   If specified, then the resulting stream will have blocking stream
  43      *   semantics.  This means that if the stream has no data and is not
  44      *   closed, then reading from it will block the calling thread until
  45      *   at least one byte is available or until the stream is closed.
  46      *   If this flag is NOT specified, then the stream has non-blocking
  47      *   stream semantics.  This means that if the stream has no data and is
  48      *   not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK.
  49      *   In addition, in non-blocking mode, the stream is guaranteed to
  50      *   support nsIAsyncInputStream.  This interface allows the consumer of
  51      *   the stream to be notified when the stream can again be read.
  52      *
  53      * OPEN_UNBUFFERED
  54      *   If specified, the resulting stream may not support ReadSegments.
  55      *   ReadSegments is only gauranteed to be implemented when this flag is
  56      *   NOT specified.
  57      *
  58      * @param aFlags
  59      *        optional transport specific flags.
  60      * @param aSegmentSize
  61      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  62      *        size of each buffer segment (pass 0 to use default value).
  63      * @param aSegmentCount
  64      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  65      *        maximum number of buffer segments (pass 0 to use default value).
  66      */
  67     nsIInputStream openInputStream(in unsigned long aFlags,
  68                                    in unsigned long aSegmentSize,
  69                                    in unsigned long aSegmentCount);
  70
  71     /**
  72      * Open an output stream on this transport.
  73      *
  74      * Flags have the following meaning:
  75      *
  76      * OPEN_BLOCKING
  77      *   If specified, then the resulting stream will have blocking stream
  78      *   semantics.  This means that if the stream is full and is not closed,
  79      *   then writing to it will block the calling thread until ALL of the
  80      *   data can be written or until the stream is closed.  If this flag is
  81      *   NOT specified, then the stream has non-blocking stream semantics.
  82      *   This means that if the stream is full and is not closed, then writing
  83      *   to it returns NS_BASE_STREAM_WOULD_BLOCK.  In addition, in non-
  84      *   blocking mode, the stream is guaranteed to support
  85      *   nsIAsyncOutputStream.  This interface allows the consumer of the
  86      *   stream to be notified when the stream can again accept more data.
  87      *
  88      * OPEN_UNBUFFERED
  89      *   If specified, the resulting stream may not support WriteSegments and
  90      *   WriteFrom.  WriteSegments and WriteFrom are only guaranteed to be
  91      *   implemented when this flag is NOT specified.
  92      *
  93      * @param aFlags
  94      *        optional transport specific flags.
  95      * @param aSegmentSize
  96      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  97      *        size of each buffer segment (pass 0 to use default value).
  98      * @param aSegmentCount
  99      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
 100      *        maximum number of buffer segments (pass 0 to use default value).
 101      */
 102     nsIOutputStream openOutputStream(in unsigned long aFlags,
 103                                      in unsigned long aSegmentSize,
 104                                      in unsigned long aSegmentCount);
 105
 106     /**
 107      * Close the transport and any open streams.
 108      *
 109      * @param aReason
 110      *        the reason for closing the stream.
 111      */
 112     void close(in nsresult aReason);
 113
 114     /**
 115      * Set the transport event sink.
 116      *
 117      * @param aSink
 118      *        receives transport layer notifications
 119      * @param aEventTarget
 120      *        indicates the event target to which the notifications should
 121      *        be delivered.  if NULL, then the notifications may occur on
 122      *        any thread.
 123      */
 124     void setEventSink(in nsITransportEventSink aSink,
 125                       in nsIEventTarget aEventTarget);
 126
 127     /**
 128      * Generic nsITransportEventSink status codes.  nsITransport
 129      * implementations may override these status codes with their own more
 130      * specific status codes (e.g., see nsISocketTransport).
 131      *
 132      * In C++, these constants have a type of uint32_t, so C++ callers must use
 133      * the NS_NET_STATUS_* constants defined below, which have a type of
 134      * nsresult.
 135      */
 136     const unsigned long STATUS_READING = 0x4b0008;
 137     const unsigned long STATUS_WRITING = 0x4b0009;
 138 };
 139
 140 [scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)]
 141 interface nsITransportEventSink : nsISupports
 142 {
 143     /**
 144      * Transport status notification.
 145      *
 146      * @param aTransport
 147      *        the transport sending this status notification.
 148      * @param aStatus
 149      *        the transport status. See nsISocketTransport for socket specific
 150      *        status codes and more comments.
 151      * @param aProgress
 152      *        the amount of data either read or written depending on the value
 153      *        of the status code.  this value is relative to aProgressMax.
 154      * @param aProgressMax
 155      *        the maximum amount of data that will be read or written.  if
 156      *        unknown, -1 will be passed.
 157      */
 158     void onTransportStatus(in nsITransport aTransport,
 159                            in nsresult aStatus,
 160                            in long long aProgress,
 161                            in long long aProgressMax);
 162 };