netwerk/protocol/webtransport/nsIWebTransport.idl

   1 /* -*- Mode: C++; 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/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsIURI.idl"
   8 #include "nsIPrincipal.idl"
   9
  10 interface WebTransportSessionEventListener;
  11 interface nsIWebTransportStreamCallback;
  12 interface nsIWebTransportBidirectionalStream;
  13 interface nsIWebTransportSendStream;
  14 interface nsIWebTransportReceiveStream;
  15
  16 %{C++
  17 namespace mozilla::dom {
  18 class ClientInfo;
  19 }
  20 namespace mozilla::net {
  21 class Http3WebTransportSession;
  22 class Http3WebTransportStream;
  23 }
  24 %}
  25
  26 [ptr] native Http3WebTransportSessionPtr(mozilla::net::Http3WebTransportSession);
  27 [ptr] native Http3WebTransportStreamPtr(mozilla::net::Http3WebTransportStream);
  28 native Datagram(nsTArray<uint8_t>&&);
  29 [ref] native const_MaybeClientInfoRef(const mozilla::Maybe<mozilla::dom::ClientInfo>);
  30
  31 [builtinclass, scriptable, uuid(c20d6e77-8cb1-4838-a88d-fff826080aa3)]
  32 interface nsIWebTransport : nsISupports {
  33   cenum WebTransportError : 16 {
  34     UNKNOWN_ERROR,
  35     INVALID_STATE_ERROR,
  36   };
  37
  38   // When called, perform steps in "Initialization WebTransport over HTTP".
  39   void asyncConnect(in nsIURI aURI,
  40                     in nsIPrincipal aLoadingPrincipal,
  41                     in unsigned long aSecurityFlags,
  42                     in WebTransportSessionEventListener aListener);
  43
  44   void asyncConnectWithClient(in nsIURI aURI,
  45                     in nsIPrincipal aLoadingPrincipal,
  46                     in unsigned long aSecurityFlags,
  47                     in WebTransportSessionEventListener aListener,
  48                     in const_MaybeClientInfoRef aClientInfo);
  49
  50   // Asynchronously get states.
  51   void getStats();
  52
  53   // Close the session.
  54   void closeSession(in uint32_t aErrorCode,
  55                     in ACString aReason);
  56
  57   // Create and open a new WebTransport stream.
  58   void createOutgoingBidirectionalStream(in nsIWebTransportStreamCallback aListener);
  59   void createOutgoingUnidirectionalStream(in nsIWebTransportStreamCallback aListener);
  60
  61   void sendDatagram(in Array<uint8_t> aData, in uint64_t aTrackingId);
  62
  63   void getMaxDatagramSize();
  64
  65   // This can be only called after onSessionReady().
  66   // After this point, we can retarget the underlying WebTransportSessionProxy
  67   // object off main thread.
  68   [noscript] void retargetTo(in nsIEventTarget aTarget);
  69 };
  70
  71 // Events related to a WebTransport session.
  72 [scriptable, uuid(0e3cb269-f318-43c8-959e-897f57894b71)]
  73 interface WebTransportSessionEventListener : nsISupports {
  74   // This is used to let the consumer of nsIWebTransport know that the
  75   // underlying WebTransportSession object is ready to use.
  76   void onSessionReady(in uint64_t aSessionId);
  77   // This is used internally to pass the reference of WebTransportSession
  78   // object to WebTransportSessionProxy.
  79   void onSessionReadyInternal(in Http3WebTransportSessionPtr aSession);
  80   void onSessionClosed(in bool aCleanly,
  81                        in uint32_t aErrorCode,
  82                        in ACString aReason);
  83
  84   // When a new stream has been received.
  85   void onIncomingBidirectionalStreamAvailable(in nsIWebTransportBidirectionalStream aStream);
  86   void onIncomingUnidirectionalStreamAvailable(in nsIWebTransportReceiveStream aStream);
  87
  88   // This is used internally to pass the reference of Http3WebTransportStream
  89   // object to WebTransportSessionProxy.
  90   void onIncomingStreamAvailableInternal(in Http3WebTransportStreamPtr aStream);
  91
  92   void onStopSending(in uint64_t aStreamId, in nsresult aError);
  93   void onResetReceived(in uint64_t aStreamId, in nsresult aError);
  94
  95   // When a new datagram has been received.
  96   void onDatagramReceived(in Array<uint8_t> aData);
  97
  98   // This is used internally to pass the datagram to WebTransportSessionProxy.
  99   void onDatagramReceivedInternal(in Datagram aData);
 100
 101   void onMaxDatagramSize(in uint64_t aSize);
 102
 103   cenum DatagramOutcome: 32 {
 104     UNKNOWN               = 0,
 105     DROPPED_TOO_MUCH_DATA = 1,
 106     SENT                  = 2,
 107   };
 108
 109   void onOutgoingDatagramOutCome(
 110     in uint64_t aId,
 111     in WebTransportSessionEventListener_DatagramOutcome aOutCome);
 112
 113   // void onStatsAvailable(in WebTransportStats aStats);
 114 };
 115
 116 // This interface is used as a callback when creating an outgoing
 117 // unidirectional or bidirectional stream.
 118 [scriptable, uuid(c6eeff1d-599b-40a8-9157-c7a40c3d51a2)]
 119 interface nsIWebTransportStreamCallback : nsISupports {
 120   void onBidirectionalStreamReady(in nsIWebTransportBidirectionalStream aStream);
 121   void onUnidirectionalStreamReady(in nsIWebTransportSendStream aStream);
 122   void onError(in uint8_t aError);
 123 };