netwerk/base/public/nsITransport.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Mozilla.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 2002
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Darin Fisher <darin@netscape.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 interface nsIInputStream;
  41 interface nsIOutputStream;
  42 interface nsITransportEventSink;
  43 interface nsIEventTarget;
  44
  45 /**
  46  * nsITransport
  47  *
  48  * This interface provides a common way of accessing i/o streams connected
  49  * to some resource.  This interface does not in any way specify the resource.
  50  * It provides methods to open blocking or non-blocking, buffered or unbuffered
  51  * streams to the resource.  The name "transport" is meant to connote the
  52  * inherent data transfer implied by this interface (i.e., data is being
  53  * transfered in some fashion via the streams exposed by this interface).
  54  *
  55  * A transport can have an event sink associated with it.  The event sink
  56  * receives transport-specific events as the transfer is occuring.  For a
  57  * socket transport, these events can include status about the connection.
  58  * See nsISocketTransport for more info about socket transport specifics.
  59  */
  60 [scriptable, uuid(d8786c64-eb49-4a0b-b42c-0936a745fbe8)]
  61 interface nsITransport : nsISupports
  62 {
  63     /**
  64      * Open flags.
  65      */
  66     const unsigned long OPEN_BLOCKING   = 1<<0;
  67     const unsigned long OPEN_UNBUFFERED = 1<<1;
  68
  69     /**
  70      * Open an input stream on this transport.
  71      *
  72      * Flags have the following meaning:
  73      *
  74      * OPEN_BLOCKING
  75      *   If specified, then the resulting stream will have blocking stream
  76      *   semantics.  This means that if the stream has no data and is not
  77      *   closed, then reading from it will block the calling thread until
  78      *   at least one byte is available or until the stream is closed.
  79      *   If this flag is NOT specified, then the stream has non-blocking
  80      *   stream semantics.  This means that if the stream has no data and is
  81      *   not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK.
  82      *   In addition, in non-blocking mode, the stream is guaranteed to
  83      *   support nsIAsyncInputStream.  This interface allows the consumer of
  84      *   the stream to be notified when the stream can again be read.
  85      *
  86      * OPEN_UNBUFFERED
  87      *   If specified, the resulting stream may not support ReadSegments.
  88      *   ReadSegments is only gauranteed to be implemented when this flag is
  89      *   NOT specified.
  90      *
  91      * @param aFlags
  92      *        optional transport specific flags.
  93      * @param aSegmentSize
  94      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  95      *        size of each buffer segment (pass 0 to use default value).
  96      * @param aSegmentCount
  97      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  98      *        maximum number of buffer segments (pass 0 to use default value).
  99      */
 100     nsIInputStream openInputStream(in unsigned long aFlags,
 101                                    in unsigned long aSegmentSize,
 102                                    in unsigned long aSegmentCount);
 103
 104     /**
 105      * Open an output stream on this transport.
 106      *
 107      * Flags have the following meaning:
 108      *
 109      * OPEN_BLOCKING
 110      *   If specified, then the resulting stream will have blocking stream
 111      *   semantics.  This means that if the stream is full and is not closed,
 112      *   then writing to it will block the calling thread until ALL of the
 113      *   data can be written or until the stream is closed.  If this flag is
 114      *   NOT specified, then the stream has non-blocking stream semantics.
 115      *   This means that if the stream is full and is not closed, then writing
 116      *   to it returns NS_BASE_STREAM_WOULD_BLOCK.  In addition, in non-
 117      *   blocking mode, the stream is guaranteed to support
 118      *   nsIAsyncOutputStream.  This interface allows the consumer of the
 119      *   stream to be notified when the stream can again accept more data.
 120      *
 121      * OPEN_UNBUFFERED
 122      *   If specified, the resulting stream may not support WriteSegments and
 123      *   WriteFrom.  WriteSegments and WriteFrom are only gauranteed to be
 124      *   implemented when this flag is NOT specified.
 125      *
 126      * @param aFlags
 127      *        optional transport specific flags.
 128      * @param aSegmentSize
 129      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
 130      *        size of each buffer segment (pass 0 to use default value).
 131      * @param aSegmentCount
 132      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
 133      *        maximum number of buffer segments (pass 0 to use default value).
 134      */
 135     nsIOutputStream openOutputStream(in unsigned long aFlags,
 136                                      in unsigned long aSegmentSize,
 137                                      in unsigned long aSegmentCount);
 138
 139     /**
 140      * Close the transport and any open streams.
 141      *
 142      * @param aReason
 143      *        the reason for closing the stream.
 144      */
 145     void close(in nsresult aReason);
 146
 147     /**
 148      * Set the transport event sink.
 149      *
 150      * @param aSink
 151      *        receives transport layer notifications
 152      * @param aEventTarget
 153      *        indicates the event target to which the notifications should
 154      *        be delivered.  if NULL, then the notifications may occur on
 155      *        any thread.
 156      */
 157     void setEventSink(in nsITransportEventSink aSink,
 158                       in nsIEventTarget aEventTarget);
 159
 160     /**
 161      * Generic nsITransportEventSink status codes.  nsITransport
 162      * implementations may override these status codes with their own more
 163      * specific status codes (e.g., see nsISocketTransport).
 164      */
 165     const unsigned long STATUS_READING = 0x804b0008;
 166     const unsigned long STATUS_WRITING = 0x804b0009;
 167 };
 168
 169 [scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)]
 170 interface nsITransportEventSink : nsISupports
 171 {
 172     /**
 173      * Transport status notification.
 174      *
 175      * @param aTransport
 176      *        the transport sending this status notification.
 177      * @param aStatus
 178      *        the transport status (resolvable to a string using
 179      *        nsIErrorService). See nsISocketTransport for socket specific
 180      *        status codes and more comments.
 181      * @param aProgress
 182      *        the amount of data either read or written depending on the value
 183      *        of the status code.  this value is relative to aProgressMax.
 184      * @param aProgressMax
 185      *        the maximum amount of data that will be read or written.  if
 186      *        unknown, 0xFFFFFFFF will be passed.
 187      */
 188     void onTransportStatus(in nsITransport aTransport,
 189                            in nsresult aStatus,
 190                            in unsigned long long aProgress,
 191                            in unsigned long long aProgressMax);
 192 };