0
# Common Shims
1

2
Common shims are universal WebRTC compatibility fixes applied across all browsers to handle differences in WebRTC specification implementations and ensure consistent behavior.
3

4
## Capabilities
5

6
### RTCIceCandidate Shimming
7

8
Normalizes RTCIceCandidate interface across browsers by parsing and augmenting candidate properties.
9

10
```javascript { .api }
11
/**
12
 * Shims RTCIceCandidate to parse and augment candidate properties
13
 * Adds parsed fields from SDP candidate string to the candidate object
14
 * @param window - Browser window object
15
 */
16
function shimRTCIceCandidate(window: Window): void;
17
```
18

19
**What it fixes:**
20
- Removes erroneous 'a=' prefix from candidate strings
21
- Adds parsed candidate properties (foundation, component, priority, etc.)
22
- Standardizes candidate serialization with toJSON method
23
- Ensures consistent icecandidate event handling
24

25
**Usage Examples:**
26

27
```javascript
28
import adapter from 'webrtc-adapter';
29

30
// RTCIceCandidate is automatically shimmed after import
31
const candidate = new RTCIceCandidate({
32
  candidate: 'candidate:1 1 UDP 2113667327 192.168.1.100 54400 typ host',
33
  sdpMid: '0',
34
  sdpMLineIndex: 0
35
});
36

37
// Parsed properties are automatically available
38
console.log(candidate.foundation); // '1'
39
console.log(candidate.component); // 1
40
console.log(candidate.priority); // 2113667327
41
console.log(candidate.address); // '192.168.1.100'
42
console.log(candidate.port); // 54400
43
console.log(candidate.type); // 'host'
44
```
45

46
### RTCIceCandidate Relay Protocol Shimming
47

48
Adds relayProtocol property to relay-type ICE candidates based on priority values.
49

50
```javascript { .api }
51
/**
52
 * Adds relayProtocol property to ICE candidates for relay connections
53
 * Maps libwebrtc priority values to protocol names
54
 * @param window - Browser window object
55
 */
56
function shimRTCIceCandidateRelayProtocol(window: Window): void;
57
```
58

59
**What it fixes:**
60
- Adds missing relayProtocol property to relay candidates
61
- Maps priority bits to protocol names: 'tls', 'tcp', 'udp'
62
- Provides standard way to identify relay connection type
63

64
### Max Message Size Shimming
65

66
Provides maxMessageSize property for SCTP data channels when not natively supported.
67

68
```javascript { .api }
69
/**
70
 * Shims maxMessageSize property for SCTP data channels
71
 * Provides consistent way to query maximum message size limits
72
 * @param window - Browser window object
73
 * @param browserDetails - Browser detection information
74
 */
75
function shimMaxMessageSize(window: Window, browserDetails: IBrowserDetails): void;
76
```
77

78
**What it fixes:**
79
- Adds maxMessageSize property to RTCPeerConnection.sctp
80
- Provides browser-specific message size limits
81
- Standardizes data channel size constraint queries
82

83
**Usage Examples:**
84

85
```javascript
86
import adapter from 'webrtc-adapter';
87

88
const pc = new RTCPeerConnection();
89

90
// Check maximum message size (automatically shimmed)
91
if (pc.sctp && pc.sctp.maxMessageSize) {
92
  console.log('Max message size:', pc.sctp.maxMessageSize);
93
  
94
  // Send data respecting size limits
95
  const data = 'Large message content...';
96
  if (data.length <= pc.sctp.maxMessageSize) {
97
    dataChannel.send(data);
98
  }
99
}
100
```
101

102
### Send Type Error Shimming
103

104
Ensures DataChannel.send() throws TypeError for invalid data types.
105

106
```javascript { .api }
107
/**
108
 * Shims data channel send to throw TypeError for invalid data types
109
 * Standardizes error handling across browser implementations
110
 * @param window - Browser window object
111
 */
112
function shimSendThrowTypeError(window: Window): void;
113
```
114

115
**What it fixes:**
116
- Ensures consistent TypeError for invalid send() parameters
117
- Standardizes data channel error handling behavior
118
- Provides predictable exception patterns
119

120
### Connection State Shimming
121

122
Provides connectionState property for RTCPeerConnection when not natively available.
123

124
```javascript { .api }
125
/**
126
 * Shims RTCPeerConnection connectionState property
127
 * Derives connection state from iceConnectionState when needed
128
 * @param window - Browser window object
129
 */
130
function shimConnectionState(window: Window): void;
131
```
132

133
**What it fixes:**
134
- Adds missing connectionState property and events
135
- Maps iceConnectionState values to connectionState
136
- Provides consistent connection monitoring API
137

138
**Usage Examples:**
139

140
```javascript
141
import adapter from 'webrtc-adapter';
142

143
const pc = new RTCPeerConnection();
144

145
// Connection state is automatically available
146
pc.addEventListener('connectionstatechange', () => {
147
  console.log('Connection state:', pc.connectionState);
148
  
149
  switch (pc.connectionState) {
150
    case 'connected':
151
      console.log('Peer connection established');
152
      break;
153
    case 'disconnected':
154
      console.log('Peer connection lost');
155
      break;
156
    case 'failed':
157
      console.log('Peer connection failed');
158
      break;
159
  }
160
});
161
```
162

163
### Extmap Allow Mixed Removal
164

165
Removes problematic extmap-allow-mixed attribute from SDP.
166

167
```javascript { .api }
168
/**
169
 * Removes extmap-allow-mixed attribute from SDP
170
 * Prevents compatibility issues with certain browsers
171
 * @param window - Browser window object  
172
 * @param browserDetails - Browser detection information
173
 */
174
function removeExtmapAllowMixed(window: Window, browserDetails: IBrowserDetails): void;
175
```
176

177
**What it fixes:**
178
- Removes extmap-allow-mixed from offer/answer SDP
179
- Prevents negotiation failures in mixed browser scenarios
180
- Ensures wider browser compatibility
181

182
### Add ICE Candidate Null/Empty Handling
183

184
Handles null or empty ICE candidate additions gracefully.
185

186
```javascript { .api }
187
/**
188
 * Handles null or empty ICE candidate additions gracefully
189
 * Standardizes end-of-candidates signaling behavior
190
 * @param window - Browser window object
191
 * @param browserDetails - Browser detection information
192
 */
193
function shimAddIceCandidateNullOrEmpty(window: Window, browserDetails: IBrowserDetails): void;
194
```
195

196
**What it fixes:**
197
- Allows null candidate to signal end of candidates
198
- Handles empty candidate objects properly
199
- Standardizes ICE gathering completion signaling
200

201
### Parameterless SetLocalDescription
202

203
Enables parameterless setLocalDescription() calls.
204

205
```javascript { .api }
206
/**
207
 * Supports parameterless setLocalDescription calls
208
 * Automatically uses last created offer/answer when no parameters provided
209
 * @param window - Browser window object
210
 * @param browserDetails - Browser detection information  
211
 */
212
function shimParameterlessSetLocalDescription(window: Window, browserDetails: IBrowserDetails): void;
213
```
214

215
**What it fixes:**
216
- Enables modern parameterless setLocalDescription() usage
217
- Automatically applies last created offer/answer
218
- Simplifies WebRTC negotiation code patterns
219

220
**Usage Examples:**
221

222
```javascript
223
import adapter from 'webrtc-adapter';
224

225
const pc = new RTCPeerConnection();
226

227
// Modern parameterless usage (automatically shimmed)
228
const offer = await pc.createOffer();
229
await pc.setLocalDescription(); // Uses created offer automatically
230

231
// Traditional explicit usage still works
232
await pc.setLocalDescription(offer);
233
```
234

235
## Common Shim Interface
236

237
All common shims are available through the adapter object:
238

239
```javascript { .api }
240
interface ICommonShim {
241
  shimRTCIceCandidate: (window: Window, browserDetails?: IBrowserDetails) => void;
242
  shimRTCIceCandidateRelayProtocol: (window: Window, browserDetails?: IBrowserDetails) => void;
243
  shimMaxMessageSize: (window: Window, browserDetails: IBrowserDetails) => void;
244
  shimSendThrowTypeError: (window: Window) => void;
245
  shimConnectionState: (window: Window, browserDetails?: IBrowserDetails) => void;
246
  removeExtmapAllowMixed: (window: Window, browserDetails: IBrowserDetails) => void;
247
  shimAddIceCandidateNullOrEmpty: (window: Window, browserDetails: IBrowserDetails) => void;
248
  shimParameterlessSetLocalDescription: (window: Window, browserDetails: IBrowserDetails) => void;
249
}
250
```
251

252
These shims are automatically applied when importing webrtc-adapter, and are accessible via `adapter.commonShim` for manual application or testing purposes.