nsISocketTransport

This interface specializes nsITransport for communication over network sockets. It provides methods to open blocking or non-blocking, buffered or unbuffered streams between two end-point in a IP based network.
Inherits from: nsITransport Last changed in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

Note: Connection setup is triggered by opening an input or output stream, it does not start on its own. Completion of the connection setup is indicated by a STATUS_CONNECTED_TO notification to the event sink (if set).

To create an instance, call nsISocketTransportService.createTransport()

Method overview

PRNetAddr getPeerAddr(); Native code only!
PRNetAddr getSelfAddr(); Native code only!
unsigned long getTimeout(in unsigned long aType);
boolean isAlive();
void setTimeout(in unsigned long aType, in unsigned long aValue);

Attributes

Attribute Type Description
connectionFlags unsigned long A bitmask that can be used to modify underlying behavior of the socket connection. See Connection Flag Constants for more details.
host AUTF8String Get the host for the underlying socket connection. Read only.
port long Get the port for the underlying socket connection. Read only.
securityCallbacks nsIInterfaceRequestor

Security notification callbacks passed to the secure socket provider via nsISSLSocketControl at socket creation time. This object supports nsIBadCertListener2 and nsISSLErrorListener for SSL connections, and possibly other interfaces.

Note: This attribute cannot be changed once a stream has been opened.
securityInfo nsISupports

Security info object returned from the secure socket provider. This object supports nsISSLSocketControl, nsITransportSecurityInfo, and possibly other interfaces.

This attribute is only available once the socket is connected. Read only.

Constants

Timeout type

This constants are used by getTransport() and setTransport() to specify socket timeouts

Constant Value Description
TIMEOUT_CONNECT 0 Connecting timeout.
TIMEOUT_READ_WRITE 1 Read and write timeouts.

nsITransportEventSink status codes

Note: Although these constants look like XPCOM error codes and are passed in an nsresult variable, they are not error codes. They do overlap with existing error codes in Necko, these status codes are confined within a very limited context where no error codes may appear, so there is no ambiguity. The values of these status codes must never change.

The status codes appear in near-chronological order (not in numeric order). STATUS_RESOLVING may be skipped if the host does not need to be resolved. STATUS_WAITING_FOR is an optional status code, which the implementation of this interface may choose not to generate.

Constant Value Description
STATUS_RESOLVING 0x804b0003 Transport is resolving the host. Usually a DNS lookup.
STATUS_RESOLVED 0x804b000b Transport has resolved the host.
STATUS_CONNECTING_TO 0x804b0007  
STATUS_CONNECTED_TO 0x804b0004  
STATUS_SENDING_TO 0x804b0005  
STATUS_WAITING_FOR 0x804b000a  
STATUS_RECEIVING_FROM 0x804b0006  

Connection flags

Values for the connectionFlags attribute

Constant Value Description
BYPASS_CACHE 0 When making a new connection BYPASS_CACHE will force the Necko DNS cache entry to be refreshed with a new call to NSPR if it is set before opening the new stream.
ANONYMOUS_CONNECT 1 When this flag is set, the socket will not apply any credentials when establishing a connection. For example, an SSL connection would not send any client-certificates if this flag is set.
DISABLE_IPV6 2 When this flag is set, the socket will ignore any IPv6 addresses the host may offer and will only attempt to connect to IPv4 addresses.

Methods

Native code only!

getPeerAddr

Returns the IP address of the socket connection peer. This attribute is defined only once a connection has been established.

PRNetAddr getPeerAddr();
Parameters

None.

Return value

An PRNetAddr containing the resolved IP address.

Native code only!

getSelfAddr

Returns the IP address of the initiating end. This attribute is defined only once a connection has been established.

PRNetAddr getSelfAddr();
Parameters

None.

Return value

An PRNetAddr containing the resolved IP address.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

getTimeout()

Retrieves a Socket timeout.

unsigned long getTimeout(
  in unsigned long aType
);
Parameters
aType
The timeout type, who's associated value should be retrieved. Can be one of the constants TIMEOUT_CONNECT or TIMEOUT_READ_WRITE.
Return value

Returns the timeout in seconds for the given Type. A value of PR_UINT32_MAX is equivalent to no timeout.

isAlive()

Test if this socket transport is (still) connected.

 boolean isAlive();
Parameters

None.

Return value

Returns true if the socket is connected. Otherwise false.

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

setTimeout()

Sets a Socket timeout.

void setTimeout(
  in unsigned long aType,
  in unsigned long aValue
);
Parameters
aType
The timeout type which should be set to aValue. Can be one of the constants TIMEOUT_CONNECT or TIMEOUT_READ_WRITE.
aValue
Defines the timeout in seconds, pass PR_UINT32_MAX to specify no timeout. The implementation may truncate timeout values to a smaller range of values (for example, 0 to 0xFFFF).

Remarks

This is a free-threaded interface, meaning that the methods on this interface may be called from any thread.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, kmaglione, trevorh, cbakgly, Smi
 Last updated by: Sheppy,