1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsITransport.idl"
7 #include
"nsIRequest.idl"
8 #include
"nsITRRSkipReason.idl"
10 interface nsIInterfaceRequestor
;
12 interface nsITLSSocketControl
;
15 #include
"mozilla/BasePrincipal.h"
22 native NetAddr
(mozilla
::net
::NetAddr
);
23 [ptr] native NetAddrPtr
(mozilla
::net
::NetAddr
);
24 native OriginAttributes
(mozilla
::OriginAttributes
);
25 [ref] native const_OriginAttributesRef
(const mozilla
::OriginAttributes
);
30 * NOTE: Connection setup is triggered by opening an input or output stream,
31 * it does not start on its own. Completion of the connection setup is
32 * indicated by a STATUS_CONNECTED_TO notification to the event sink (if set).
34 * NOTE: This is a free-threaded interface, meaning that the methods on
35 * this interface may be called from any thread.
37 [scriptable
, builtinclass
, uuid(79221831-85e2
-43a8
-8152-05d77d6fde31
)]
38 interface nsISocketTransport
: nsITransport
41 * Get the peer's host for the underlying socket connection.
42 * For Unix domain sockets, this is a pathname, or the empty string for
43 * unnamed and abstract socket addresses.
45 readonly attribute AUTF8String host
;
48 * Get the port for the underlying socket connection.
49 * For Unix domain sockets, this is zero.
51 readonly attribute
long port
;
54 * The origin attributes are used to create sockets. The first party domain
55 * will eventually be used to isolate OCSP cache and is only non-empty when
56 * "privacy.firstparty.isolate" is enabled. Setting this is the only way to
57 * carry origin attributes down to NSPR layers which are final consumers.
58 * It must be set before the socket transport is built.
60 [implicit_jscontext
, binaryname
(ScriptableOriginAttributes
)]
61 attribute jsval originAttributes
;
63 [noscript
, nostdcall
, binaryname
(GetOriginAttributes
)]
64 OriginAttributes binaryGetOriginAttributes
();
66 [noscript
, nostdcall
, binaryname
(SetOriginAttributes
)]
67 void binarySetOriginAttributes
(in const_OriginAttributesRef aOriginAttrs
);
70 * Returns the IP address of the socket connection peer. This
71 * attribute is defined only once a connection has been established.
73 [noscript
] NetAddr getPeerAddr
();
76 * Returns the IP address of the initiating end. This attribute
77 * is defined only once a connection has been established.
79 [noscript
] NetAddr getSelfAddr
();
82 * Bind to a specific local address.
84 [noscript
] void bind
(in NetAddrPtr aLocalAddr
);
87 * Returns a scriptable version of getPeerAddr. This attribute is defined
88 * only once a connection has been established.
90 nsINetAddr getScriptablePeerAddr
();
93 * Returns a scriptable version of getSelfAddr. This attribute is defined
94 * only once a connection has been established.
96 nsINetAddr getScriptableSelfAddr
();
99 * TLS socket control object. This attribute is only available once the
100 * socket is connected.
102 readonly attribute nsITLSSocketControl tlsSocketControl
;
105 * Security notification callbacks passed to the secure socket provider
106 * via nsITLSSocketControl at socket creation time.
108 * NOTE: this attribute cannot be changed once a stream has been opened.
110 attribute nsIInterfaceRequestor securityCallbacks
;
113 * Test if this socket transport is (still) connected.
118 * Socket timeouts in seconds. To specify no timeout, pass UINT32_MAX
119 * as aValue to setTimeout. The implementation may truncate timeout values
120 * to a smaller range of values (e.g., 0 to 0xFFFF).
122 unsigned long getTimeout
(in unsigned long aType
);
123 void setTimeout
(in unsigned long aType
, in unsigned long aValue
);
126 * Sets the SO_LINGER option with the specified values for the l_onoff and
127 * l_linger parameters. This applies PR_SockOpt_Linger before PR_Close and
128 * can be used with a timeout of zero to send an RST packet when closing.
130 void setLinger
(in boolean aPolarity
, in short aTimeout
);
133 * True to set addr and port reuse socket options.
135 void setReuseAddrPort
(in bool reuseAddrPort
);
138 * Values for the aType parameter passed to get/setTimeout.
140 const unsigned long TIMEOUT_CONNECT
= 0;
141 const unsigned long TIMEOUT_READ_WRITE
= 1;
144 * nsITransportEventSink status codes.
146 * Although these look like XPCOM error codes and are passed in an nsresult
147 * variable, they are *not* error codes. Note that while they *do* overlap
148 * with existing error codes in Necko, these status codes are confined
149 * within a very limited context where no error codes may appear, so there
152 * The values of these status codes must never change.
154 * The status codes appear in near-chronological order (not in numeric
155 * order). STATUS_RESOLVING may be skipped if the host does not need to be
156 * resolved. STATUS_WAITING_FOR is an optional status code, which the impl
157 * of this interface may choose not to generate.
159 * In C++, these constants have a type of uint32_t, so C++ callers must use
160 * the NS_NET_STATUS_* constants defined below, which have a type of
163 const unsigned long STATUS_RESOLVING
= 0x4b0003;
164 const unsigned long STATUS_RESOLVED
= 0x4b000b;
165 const unsigned long STATUS_CONNECTING_TO
= 0x4b0007;
166 const unsigned long STATUS_CONNECTED_TO
= 0x4b0004;
167 const unsigned long STATUS_SENDING_TO
= 0x4b0005;
168 const unsigned long STATUS_WAITING_FOR
= 0x4b000a;
169 const unsigned long STATUS_RECEIVING_FROM
= 0x4b0006;
170 const unsigned long STATUS_TLS_HANDSHAKE_STARTING
= 0x4b000c;
171 const unsigned long STATUS_TLS_HANDSHAKE_ENDED
= 0x4b000d;
174 * connectionFlags is a bitmask that can be used to modify underlying
175 * behavior of the socket connection. See the flags below.
177 attribute
unsigned long connectionFlags
;
180 * Values for the connectionFlags
182 * When making a new connection BYPASS_CACHE will force the Necko DNS
183 * cache entry to be refreshed with a new call to NSPR if it is set before
184 * opening the new stream.
186 const unsigned long BYPASS_CACHE
= (1 << 0);
189 * When setting this flag, the socket will not apply any
190 * credentials when establishing a connection. For example,
191 * an SSL connection would not send any client-certificates
192 * if this flag is set.
194 const unsigned long ANONYMOUS_CONNECT
= (1 << 1);
197 * If set, we will skip all IPv6 addresses the host may have and only
198 * connect to IPv4 ones.
200 const unsigned long DISABLE_IPV6
= (1 << 2);
203 * If set, indicates that the connection was initiated from a source
204 * defined as being private in the sense of Private Browsing. Generally,
205 * there should be no state shared between connections that are private
206 * and those that are not; it is OK for multiple private connections
207 * to share state with each other, and it is OK for multiple non-private
208 * connections to share state with each other.
210 const unsigned long NO_PERMANENT_STORAGE
= (1 << 3);
213 * If set, we will skip all IPv4 addresses the host may have and only
214 * connect to IPv6 ones.
216 const unsigned long DISABLE_IPV4
= (1 << 4);
219 * If set, indicates that the socket should not connect if the hostname
220 * resolves to an RFC1918 address or IPv6 equivalent.
222 const unsigned long DISABLE_RFC1918
= (1 << 5);
225 * If set, do not use newer protocol features that might have interop problems
226 * on the Internet. Intended only for use with critical infra like the updater.
229 const unsigned long BE_CONSERVATIVE
= (1 << 6);
232 * If set, do not use TRR for resolving the host name. Intended only for
233 * retries or other scenarios when TRR is deemed likely to have returned a
236 const unsigned long DISABLE_TRR
= (1 << 7);
239 * Values for the connectionFlags
241 * When using BYPASS_CACHE, setting this bit will invalidate the existing
242 * cached entry immediately while the new resolve is being done to avoid
243 * other users from using stale content in the mean time.
245 const unsigned long REFRESH_CACHE
= (1 << 8);
248 * If this flag is set then it means that if connecting the preferred ip
249 * family has failed, retry with the oppsite one once more.
251 const unsigned long RETRY_WITH_DIFFERENT_IP_FAMILY
= (1 << 9);
254 * If we know that a server speaks only tls <1.3 there is no need to try
257 const unsigned long DONT_TRY_ECH
= (1 << 10);
260 * These two bits encode the TRR mode of the request.
261 * Use the static helper methods convert between the TRR mode and flags.
263 const unsigned long TRR_MODE_FLAGS
= (1 << 11) |
(1 << 12);
267 static uint32_t GetFlagsFromTRRMode
(nsIRequest
::TRRMode aMode
) {
268 return static_cast
<uint32_t
>(aMode
) << 11;
271 static nsIRequest
::TRRMode GetTRRModeFromFlags
(uint32_t aFlags
) {
272 return static_cast
<nsIRequest
::TRRMode
>((aFlags
& TRR_MODE_FLAGS
) >> 11);
277 * If set, we will use IP hint addresses to connect to the host.
279 const unsigned long USE_IP_HINT_ADDRESS
= (1 << 13);
282 * This is used for a temporary workaround for a web-compat issue. The flag is
283 * only set on CORS preflight request to allowed sending client certificates
284 * on a connection for an anonymous request.
286 const unsigned long ANONYMOUS_CONNECT_ALLOW_CLIENT_CERT
= (1 << 14);
289 * If set, we've retrying after a failed connection attempt.
291 const unsigned long IS_RETRY
= (1 << 15);
294 * If set, this is a speculative connection.
296 const unsigned long IS_SPECULATIVE_CONNECTION
= (1 << 16);
299 * An opaque flags for non-standard behavior of the TLS system.
300 * It is unlikely this will need to be set outside of telemetry studies
301 * relating to the TLS implementation.
303 attribute
unsigned long tlsFlags
;
306 * Socket QoS/ToS markings. Valid values are IPTOS_DSCP_AFxx or
307 * IPTOS_CLASS_CSx (or IPTOS_DSCP_EF, but currently no supported
308 * services require expedited-forwarding).
309 * Not setting this value will leave the socket with the default
310 * ToS value, which on most systems if IPTOS_CLASS_CS0 (formerly
311 * IPTOS_PREC_ROUTINE).
313 attribute octet QoSBits
;
316 * TCP send and receive buffer sizes. A value of 0 means OS level
317 * auto-tuning is in effect.
319 attribute
unsigned long recvBufferSize
;
320 attribute
unsigned long sendBufferSize
;
323 * TCP keepalive configuration (support varies by platform).
324 * Note that the attribute as well as the setter can only accessed
325 * in the socket thread.
327 attribute
boolean keepaliveEnabled
;
328 void setKeepaliveVals
(in long keepaliveIdleTime
,
329 in long keepaliveRetryInterval
);
332 * If true, this socket transport has found out the prefered family
333 * according it's connection flags could not be used to establish
334 * connections any more. Hence, the preference should be reset.
336 readonly attribute
boolean resetIPFamilyPreference
;
339 * This attribute holds information whether echConfig has been used.
340 * The value is set after PR_Connect is called.
342 readonly attribute
boolean echConfigUsed
;
345 * Called to set the echConfig to the securityInfo object.
347 void setEchConfig
(in ACString echConfig
);
350 * IP address resolved using TRR.
352 bool resolvedByTRR
();
355 * Returns the effectiveTRRMode used for the DNS resolution.
357 readonly attribute nsIRequest_TRRMode effectiveTRRMode
;
360 * Returns the TRR skip reason used for the DNS resolution.
362 readonly attribute nsITRRSkipReason_value trrSkipReason
;
365 * Indicate whether this socket is created from a private window. If yes,
366 * this socket will be closed when the last private window is closed.
368 [noscript
] void setIsPrivate
(in boolean isPrivate
);
371 * If DNS is performed externally, this flag informs the caller that it may
372 * retry connecting with a different DNS configuration (e.g. different IP
373 * family preference). The flag is set only if a network error is encounder,
374 * e.g. NS_ERROR_CONNECTION_REFUSED, NS_ERROR_RESET, etc.
376 readonly attribute
boolean retryDnsIfPossible
;
379 * Return the current status of the socket.
381 [noscript
] readonly attribute nsresult status
;