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
|
---
title: RTCPeerConnection.createOffer()
slug: Web/API/RTCPeerConnection/createOffer
tags:
- API
- Media
- RTCPeerConnection
- Reference
- SDP
- WebRTC
- createOffer
translation_of: Web/API/RTCPeerConnection/createOffer
---
<div>{{APIRef("WebRTC")}}</div>
<div>{{domxref("RTCPeerConnection")}}接口的createOffer（）方法启动创建一个{{Glossary("SDP")}} offer，目的是启动一个新的WebRTC去连接远程端点。SDP offer包含有关已附加到WebRTC会话，浏览器支持的编解码器和选项的所有{{domxref("MediaStreamTrack")}}s信息，以及{{Glossary("ICE")}} 代理，目的是通过信令信道发送给潜在远程端点，以请求连接或更新现有连接的配置。</div>
<div>返回值是一个{{domxref("Promise")}}，创建 offer 后，将使用包含新创建的要约的{{domxref("RTCSessionDescription")}}对象来解析该返回值。</div>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox"><em>aPromise</em> = <em>myPeerConnection</em>.createOffer([<em>options</em>]);
<em>myPeerConnection</em>.createOffer(<em>successCallback</em>, <em>failureCallback, </em>[<em>options</em>]) {{deprecated_inline}}
</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
<dt><font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">选项</span></font> {{optional_inline}}</dt>
<dd><code><a href="#RTCOfferOptions_dictionary">RTCOfferOptions</a></code> 词典提供要约所要求的选项。</dd>
</dl>
<h4 id="RTCOfferOptions_词典">RTCOfferOptions 词典</h4>
<p><code>RTCOfferOptions</code> 词典被用于自定义通过此方法创建offer。</p>
<dl>
<dt><code><a href="/en-US/docs/Web/API/RTCOfferOptions/iceRestart">iceRestart</a></code> {{optional_inline}}</dt>
<dd>要在活动连接上重新启动ICE，请将其设置为<code>true</code>。 这将导致返回的 offer 与已经存在的凭证不同。 如果您应用返回的offer，则ICE将重新启动。 指定<code>false</code>以保留相同的凭据，因此不重新启动ICE。 默认值为<code>false</code>。</dd>
<dt><code>offerToReceiveAudio</code> {{optional_inline}} (Legacy)</dt>
<dd>
<p>传统的布尔选项，用于控制是否向远程对等方提供尝试发送音频的机会。 如果该值为<code>false</code>，即使本地端将发送音频数据，也不会提供远程端点发送音频数据。 如果此值为<code>true</code>，即使本地端不会发送音频数据，也将向远程端点发送音频数据。 默认行为是仅在本地发送音频时才提供接收音频，否则不提供。</p>
</dd>
<dd>为了在现代实现中模拟此行为，该成员的值为false将设置所有现有音频收发器的方向以排除接收（即，设置为“仅发送”或“无效”）。</dd>
<dd>在现代实现中，此成员的值为true的存在将确保至少有一个收发器集可以接收尚未停止的音频，如果没有，则将创建一个。</dd>
<dd>
<div class="note"><strong>笔记:</strong> 您不应该使用此旧版属性。取而代之, 用 {{domxref("RTCRtpTransceiver")}} 去控制是否接受传入的音频。</div>
</dd>
<dt><code>offerToReceiveVideo</code> {{optional_inline}} (Legacy)</dt>
<dd>传统的布尔选项，用于控制是否向远程对等方提供尝试发送视频的机会。 如果此值为<code>false</code>，即使本地端将发送视频数据，也不会提供远程端点发送视频数据。 如果此值为<code>true</code>，即使本地端将不发送视频数据，也将向远程端点发送视频数据。 默认行为是仅在本地端正在发送视频时才提供接收视频，否则不提供。</dd>
<dd>为了在现代实现中模拟这种行为，该成员的值为<code>false</code>将设置所有现有视频收发器的方向以排除接收（即设置为“仅发送”或“无效”）。</dd>
<dd>在现代实现中，该成员的值为true的存在将确保至少有一个收发器集可以接收尚未停止的视频，如果没有，则将创建一个。</dd>
<dd>
<div class="note"><strong>笔记:</strong> 您不应该使用此旧版属性。取而代之, 用 {{domxref("RTCRtpTransceiver")}} 去控制是否接受传入的视频。</div>
</dd>
<dt><code>voiceActivityDetection</code> {{optional_inline}}</dt>
<dd>一些编解码器和硬件能够通过监视是否出现“静音”（或相对较低的声音水平）来检测音频何时开始和结束。 通过仅在实际有广播内容时发送音频数据，从而减少了用于音频的网络带宽。 但是，在某些情况下，这是不需要的。 例如，在音乐或其他非语音传输的情况下，这可能会导致重要的低音量声音丢失。 而且，紧急呼叫在安静时切勿切断音频。 此选项默认为<strong><code>true</code></strong>（启用语音活动检测）。</dd>
</dl>
<dl>
<dt>
<h3 id="不推荐使用的参数">不推荐使用的参数</h3>
</dt>
<dd>
<p>在较早的代码和文档中，您可能会看到此函数的基于回调的版本。 不推荐使用并强烈建议不要使用它。 您应该更新任何现有代码，以使用基于 {{jsxref("Promise")}}的<code>createOffer()</code>版本。 下面介绍了这种形式的<code>createOffer()</code>的参数，以帮助更新现有代码。</p>
</dd>
</dl>
<dl>
<dt><code>successCallback</code> {{deprecated_inline}}</dt>
<dd>{{domxref("RTCSessionDescriptionCallback")}}将传递一个描述新创建的offer的{{domxref("RTCSessionDescription")}}对象。</dd>
<dt><code>errorCallback</code> {{deprecated_inline}}</dt>
<dd>{{domxref("RTCPeerConnectionErrorCallback")}}将会传递给一个{{domxref("DOMException")}}对象，该对象说明了创建offer的请求失败的原因。</dd>
<dt><code>options</code> {{optional_inline}}</dt>
<dd>可选的<code><a href="#RTCOfferOptions_dictionary">RTCOfferOptions</a></code>词典，提供 offer所要求的选项。</dd>
</dl>
<h3 id="返回值">返回值</h3>
<p>{{jsxref("Promise")}}的履行处理程序将接收符合{{domxref("RTCSessionDescriptionInit")}}字典的对象，该字典包含描述所生成 offer 的SDP。 收到的 offer 应通过信令服务器传递到。</p>
<h3 id="异常">异常</h3>
<p>通过拒绝返回的承诺返回这些异常。 您的拒绝处理程序应检查收到的异常，以确定发生了哪些异常。</p>
<dl>
<dt><code>InvalidStateError</code></dt>
<dd><code>RTCPeerConnection</code> 被关闭.</dd>
<dt><code>NotReadableError</code></dt>
<dd>没有提供用于保护连接的证书或一组证书，并且<code>createOffer()</code>无法创建新证书。 由于需要保护所有WebRTC连接，因此会导致错误。</dd>
<dt><code>OperationError</code></dt>
<dd>由于某些原因，检查系统状态以确定资源可用性以生成报价失败。</dd>
</dl>
<h2 id="举例">举例</h2>
<p>在这里，我们看到了{{event("negotiationneeded")}}事件的处理程序，该处理程序创建了要约，并通过信令通道将其发送到远程系统。</p>
<div class="note">
<p><strong>笔记:</strong> 请记住，这是信令过程的一部分，传输层的实现细节完全由您决定。 在这种情况下，<a href="/en-US/docs/Web/API/WebSocket_API">WebSocket</a>连接用于向其他端点发送带有值为“ video-offer”的类型字段的{{Glossary("JSON")}}消息。 传递给<code>sendToServer()</code>函数的对象的内容，以及承诺履行处理程序中的所有其他内容，完全取决于您的设计。</p>
</div>
<pre class="brush: js"> myPeerConnection.createOffer().then(function(offer) {
return myPeerConnection.setLocalDescription(offer);
})
.then(function() {
sendToServer({
name: myUsername,
target: targetUsername,
type: "video-offer",
sdp: myPeerConnection.localDescription
});
})
.catch(function(reason) {
// An error occurred, so handle the failure to connect
});</pre>
<p>在此代码中，创建了offer，一旦成功，就将{{domxref("RTCPeerConnection")}}的本地端配置为通过传递要约进行匹配（使用符合{{domxref("RTCSessionDescriptionInit")}}）放入{{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}。 完成后，要约将通过信令通道发送到远程系统。 在这种情况下，使用名为<code>sendToServer()</code>的自定义函数。 信令服务器的实现独立于WebRTC规范，因此只要主叫方和潜在接收方都使用相同的offer，如何发送offer都无关紧要。</p>
<p>用 {{jsxref("Promise.catch()")}} 来捕获和处理错误.</p>
<p>请参阅 <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a>，以获取此摘录的完整示例。 这将帮助您了解此处的信令代码如何工作。</p>
<h2 id="技术指标">技术指标</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-createoffer', 'createOffer()')}}</td>
<td>{{Spec2('WebRTC 1.0')}}</td>
<td>Initial definition.</td>
</tr>
</tbody>
</table>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<div>
<p>{{Compat("api.RTCPeerConnection.createOffer")}}</p>
</div>
|
