Skip to main content

Visit Mozilla.org

nsITransport

From MDC

« XPCOM API Reference

Contents

[edit] Summary

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.

nsITransport is defined in netwerk/base/public/nsITransport.idl. It is scriptable and unfrozen (hasn't changed since mozilla1.8alpha6).

[edit] Interface Code 

[scriptable, uuid(cbb0baeb-5fcb-408b-a2be-9f8fc98d0af1)]
interface nsITransport : nsISupports
{
    const unsigned long OPEN_BLOCKING   = 1<<0;
    const unsigned long OPEN_UNBUFFERED = 1<<1;

    nsIInputStream openInputStream(in unsigned long aFlags,
                                   in unsigned long aSegmentSize,
                                   in unsigned long aSegmentCount);

    nsIOutputStream openOutputStream(in unsigned long aFlags,
                                     in unsigned long aSegmentSize,
                                     in unsigned long aSegmentCount);

    void close(in nsresult aReason);

    void setEventSink(in nsITransportEventSink aSink,
                      in nsIEventTarget aEventTarget); 

    const unsigned long STATUS_READING = 0x804b0008;
    const unsigned long STATUS_WRITING = 0x804b0009;
};

[edit] Constants

Open flags.

OPEN_BLOCKING

OPEN_UNBUFFERED

Generic nsITransportEventSink status codes. nsITransport implementations may override these status codes with their own more specific status codes (e.g., see nsISocketTransport).

STATUS_READING

STATUS_WRITING

[edit] Methods

[edit] openInputStream 

nsIInputStream openInputStream(in unsigned long aFlags,
                               in unsigned long aSegmentSize,
                               in unsigned long aSegmentCount);

Open an input stream on this transport.

Flags have the folloving 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.

[edit] Parameters

aFlags

Optional transport specific flags.

aSegmentSize

If OPEN_UNBUFFERED is not set, then this parameter specifies the size of each buffer segment (pass 0 to use default value).

aSegmentCount

If OPEN_UNBUFFERED is not set, then this parameter specifies the maximum number of buffer segments (pass 0 to use default value).

[edit] openOutputStream 

nsIOutputStream openOutputStream(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 gauranteed to be implemented when this flag is NOT specified.

[edit] Parameters

aFlags

Optional transport specific flags.

aSegmentSize

If OPEN_UNBUFFERED is not set, then this parameter specifies the size of each buffer segment (pass 0 to use default value).

aSegmentCount

If OPEN_UNBUFFERED is not set, then this parameter specifies the maximum number of buffer segments (pass 0 to use default value).

[edit] close 

void close(in nsresult aReason);

Close the transport and any open streams.

[edit] Parameters

aReason

The reason for closing the stream.

[edit] setEventSink 

void setEventSink(in nsITransportEventSink aSink,
                  in nsIEventTarget aEventTarget);

Set the transport event sink.

[edit] Parameters

aSink

Receives transport layer notifications

aEventTarget

Indicates the event target to which the notifications should be delivered. If NULL, then the notifications may occur on any thread.
Retrieved from "http://developer.mozilla.org/en/docs/nsITransport"