DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (5b21e285d546)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsITransport.idl"

interface nsIInterfaceRequestor;
interface nsINetAddr;

%{ C++
#include "mozilla/BasePrincipal.h"
namespace mozilla {
namespace net {
union NetAddr;
class TCPFastOpen;
}
}
%}
native NetAddr(mozilla::net::NetAddr);
[ptr] native NetAddrPtr(mozilla::net::NetAddr);
native OriginAttributes(mozilla::OriginAttributes);
[ref] native const_OriginAttributesRef(const mozilla::OriginAttributes);
[ptr] native TCPFastOpenPtr(mozilla::net::TCPFastOpen);

/**
 * nsISocketTransport
 *
 * 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).
 *
 * NOTE: This is a free-threaded interface, meaning that the methods on
 * this interface may be called from any thread.
 */
[scriptable, uuid(79221831-85e2-43a8-8152-05d77d6fde31)]
interface nsISocketTransport : nsITransport
{
    /**
     * Get the peer's host for the underlying socket connection.
     * For Unix domain sockets, this is a pathname, or the empty string for
     * unnamed and abstract socket addresses.
     */
    readonly attribute AUTF8String host;

    /**
     * Get the port for the underlying socket connection.
     * For Unix domain sockets, this is zero.
     */
    readonly attribute long port;

    /**
     * The origin attributes are used to create sockets.  The first party domain
     * will eventually be used to isolate OCSP cache and is only non-empty when
     * "privacy.firstparty.isolate" is enabled.  Setting this is the only way to
     * carry origin attributes down to NSPR layers which are final consumers.
     * It must be set before the socket transport is built.
     */
    [implicit_jscontext, binaryname(ScriptableOriginAttributes)]
    attribute jsval originAttributes;

    [noscript, nostdcall, binaryname(GetOriginAttributes)]
    OriginAttributes binaryGetOriginAttributes();

    [noscript, nostdcall, binaryname(SetOriginAttributes)]
    void binarySetOriginAttributes(in const_OriginAttributesRef aOriginAttrs);

    /**
     * Returns the IP address of the socket connection peer. This
     * attribute is defined only once a connection has been established.
     */
    [noscript] NetAddr getPeerAddr();

    /**
     * Returns the IP address of the initiating end. This attribute
     * is defined only once a connection has been established.
     */
    [noscript] NetAddr getSelfAddr();

    /**
     * Bind to a specific local address.
     */
    [noscript] void bind(in NetAddrPtr aLocalAddr);

    /**
     * Returns a scriptable version of getPeerAddr. This attribute is defined
     * only once a connection has been established.
     */
    nsINetAddr getScriptablePeerAddr();

    /**
     * Returns a scriptable version of getSelfAddr. This attribute is defined
     * only once a connection has been established.
     */
    nsINetAddr getScriptableSelfAddr();

    /**
     * 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.
     */
    readonly attribute nsISupports securityInfo;

    /**
     * Security notification callbacks passed to the secure socket provider
     * via nsISSLSocketControl at socket creation time.
     *
     * NOTE: this attribute cannot be changed once a stream has been opened.
     */
    attribute nsIInterfaceRequestor securityCallbacks;

    /**
     * Test if this socket transport is (still) connected.
     */
    boolean isAlive();

    /**
     * Socket timeouts in seconds.  To specify no timeout, pass UINT32_MAX
     * as aValue to setTimeout.  The implementation may truncate timeout values
     * to a smaller range of values (e.g., 0 to 0xFFFF).
     */
    unsigned long getTimeout(in unsigned long aType);
    void          setTimeout(in unsigned long aType, in unsigned long aValue);

    /**
     * Sets the SO_LINGER option with the specified values for the l_onoff and
     * l_linger parameters. This applies PR_SockOpt_Linger before PR_Close and
     * can be used with a timeout of zero to send an RST packet when closing.
     */
    void setLinger(in boolean aPolarity, in short aTimeout);

    /**
     * True to set addr and port reuse socket options.
     */
    void setReuseAddrPort(in bool reuseAddrPort);

    /**
     * Values for the aType parameter passed to get/setTimeout.
     */
    const unsigned long TIMEOUT_CONNECT    = 0;
    const unsigned long TIMEOUT_READ_WRITE = 1;

    /**
     * nsITransportEventSink status codes.
     *
     * Although these look like XPCOM error codes and are passed in an nsresult
     * variable, they are *not* error codes.  Note that while 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 impl
     * of this interface may choose not to generate.
     *
     * In C++, these constants have a type of uint32_t, so C++ callers must use
     * the NS_NET_STATUS_* constants defined below, which have a type of
     * nsresult.
     */
    const unsigned long STATUS_RESOLVING      = 0x804b0003;
    const unsigned long STATUS_RESOLVED       = 0x804b000b;
    const unsigned long STATUS_CONNECTING_TO  = 0x804b0007;
    const unsigned long STATUS_CONNECTED_TO   = 0x804b0004;
    const unsigned long STATUS_SENDING_TO     = 0x804b0005;
    const unsigned long STATUS_WAITING_FOR    = 0x804b000a;
    const unsigned long STATUS_RECEIVING_FROM = 0x804b0006;
    const unsigned long STATUS_TLS_HANDSHAKE_STARTING = 0x804b000c;
    const unsigned long STATUS_TLS_HANDSHAKE_ENDED    = 0x804b000d;

    /**
     * connectionFlags is a bitmask that can be used to modify underlying
     * behavior of the socket connection. See the flags below.
     */
    attribute unsigned long connectionFlags;

    /**
     * Values for the connectionFlags
     *
     * 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.
     */
    const unsigned long BYPASS_CACHE = (1 << 0);

    /**
     * When setting this flag, 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.
     */
    const unsigned long ANONYMOUS_CONNECT = (1 << 1);

    /**
     * If set, we will skip all IPv6 addresses the host may have and only
     * connect to IPv4 ones.
     */
    const unsigned long DISABLE_IPV6 = (1 << 2);

    /**
     * If set, indicates that the connection was initiated from a source
     * defined as being private in the sense of Private Browsing. Generally,
     * there should be no state shared between connections that are private
     * and those that are not; it is OK for multiple private connections
     * to share state with each other, and it is OK for multiple non-private
     * connections to share state with each other.
     */
    const unsigned long NO_PERMANENT_STORAGE = (1 << 3);

    /**
     * If set, we will skip all IPv4 addresses the host may have and only
     * connect to IPv6 ones.
     */
    const unsigned long DISABLE_IPV4 = (1 << 4);

    /**
     * If set, indicates that the socket should not connect if the hostname
     * resolves to an RFC1918 address or IPv6 equivalent.
     */
    const unsigned long DISABLE_RFC1918 = (1 << 5);

    /**
     * This flag is an explicit opt-in that allows a normally secure socket
     * provider to use, at its discretion, an insecure algorithm. e.g.
     * a TLS socket without authentication.
     */
    const unsigned long MITM_OK = (1 << 6);

    /**
     * If set, do not use newer protocol features that might have interop problems
     * on the Internet. Intended only for use with critical infra like the updater.
     * default is false.
     */
    const unsigned long BE_CONSERVATIVE = (1 << 7);

    /**
     * If set, do not use TRR for resolving the host name. Intended only for
     * retries or other scenarios when TRR is deemed likely to have returned a
     * wrong adddress.
     */
    const unsigned long DISABLE_TRR = (1 << 8);

    /**
     * Values for the connectionFlags
     *
     * When using BYPASS_CACHE, setting this bit will invalidate the existing
     * cached entry immediately while the new resolve is being done to avoid
     * other users from using stale content in the mean time.
     */
    const unsigned long REFRESH_CACHE = (1 << 9);

    /**
     * If this flag is set then it means that if connecting the preferred ip
     * family has failed, retry with the oppsite one once more.
     */
    const unsigned long RETRY_WITH_DIFFERENT_IP_FAMILY = (1 << 10);

    /**
     * If we know that a server speaks only tls <1.3 there is no need to try
     * to use esni and query dns for esni keys.
     */
    const unsigned long DONT_TRY_ESNI = (1 << 11);

    /**
     * An opaque flags for non-standard behavior of the TLS system.
     * It is unlikely this will need to be set outside of telemetry studies
     * relating to the TLS implementation.
     */
    attribute unsigned long tlsFlags;

    /**
     * Socket QoS/ToS markings. Valid values are IPTOS_DSCP_AFxx or
     * IPTOS_CLASS_CSx (or IPTOS_DSCP_EF, but currently no supported
     * services require expedited-forwarding).
     * Not setting this value will leave the socket with the default
     * ToS value, which on most systems if IPTOS_CLASS_CS0 (formerly
     * IPTOS_PREC_ROUTINE).
     */
    attribute octet QoSBits;

    /**
     * TCP send and receive buffer sizes. A value of 0 means OS level
     * auto-tuning is in effect.
     */
    attribute unsigned long recvBufferSize;
    attribute unsigned long sendBufferSize;

    /**
     * TCP keepalive configuration (support varies by platform).
     * Note that the attribute as well as the setter can only accessed
     * in the socket thread.
     */
    attribute boolean keepaliveEnabled;
    void setKeepaliveVals(in long keepaliveIdleTime,
                          in long keepaliveRetryInterval);

    [noscript] void setFastOpenCallback(in TCPFastOpenPtr aFastOpen);

    readonly attribute nsresult firstRetryError;

    /**
     * If true, this socket transport has found out the prefered family
     * according it's connection flags could not be used to establish
     * connections any more.  Hence, the preference should be reset.
     */
    readonly attribute boolean resetIPFamilyPreference;

    /**
     * This attribute holds information whether esni has been used.
     * The value is set after PR_Connect is called.
     */
   readonly attribute boolean esniUsed;

    /**
     * IP address resolved using TRR.
     */
    bool resolvedByTRR();
};