nsITransport.idl (6900B)
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 };