[webrtc-extensions] Header extension: direction woes and renames (#141)

henbos has just created a new issue for https://github.com/w3c/webrtc-extensions:

== Header extension: direction woes and renames ==
The direction could refer to any of the following:
- What we want to negotiate.
- What we have already negotiate.
- What the user agent uses by default.
- What the user agent is capable of doing.

For example, a header extension might be "stopped" by default, we want to negotiate it as "sendonly" but we are capable of negotiating it as "sendrecv" and at the moment nothing is negotiated, so "stopped".

What's even more confusion about direction is that currently, header extension capabilities are spread out across both `RTCRtpSender.getCapabilities(kind).headerExtensions` and `RTCRtpReciever.getCapabilities(kind).headerExtensions`.

Here's my proposal to reduce confusion and get a more unified API shape, plus some renames while we're at it.
This potentially fixes #130, #132, #137 and #136.

```
partial interface RTCRtpTransciever {
  // exts[i].direction refers to what is default, e.g. this could be "stopped" even
  // though it is possible to negotiate it.
  static sequence<RTCRtpHeaderExtensionCapability> getDefaultHeaderExtensions();

  // Rename of headerExtensionsToOffer, fixes #132.
  // Not using FrozenArray, fixes #137 and #136.
  sequence<RTCRtpHeaderExtensionCapability> getHeaderExtensionsToNegotiate();

  // This gives us the get-modify-set pattern, fixing #130.
  void setHeaderExtensionsToNegotiate(sequence<RTCRtpHeaderExtensionCapability> exts);
};
```

Here's an example usage:
```
const extensions = transciever.getHeaderExtensionsToNegotiate();
const desiredExtension = extensions.find(ext => ext.uri == 'foo');
if (desiredExtension) {
  // The app should know what directions are applicable to a particular header extension,
  // but if 'sendrecv' isn't applicable, the UA will downgrade this to 'sendonly' or
  // 'recvonly' as necessary. getHeaderExtensionsToNegotiate() will let you know.
  desiredExtension.direction = 'sendrecv';
}
transceiver.setHeaderExtensionsToNegotiate(extensions);

// After an O/A, transceiver.getNegotiatedHeaderExtensions() will match `extensions`
// if the other endpoints accepted everything, otherwise directions may be less.
```

Please view or discuss this issue at https://github.com/w3c/webrtc-extensions/issues/141 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 3 February 2023 13:08:51 UTC