Skip to content

Commit 3feb652

Browse files
miketaylrmiketaylr
committed
Issue WebAudio#220 - Rewrite the requestMIDIAccess algorithm (part 1)
1 parent 3d823b6 commit 3feb652

1 file changed

Lines changed: 154 additions & 89 deletions

File tree

‎index.html‎

Lines changed: 154 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -193,8 +193,9 @@ <h2>
193193
</dt>
194194
<dd>
195195
<p>
196-
When invoked, returns a Promise object representing a request for
197-
access to MIDI devices on the user's system.
196+
When invoked the {{Navigator/requestMIDIAccess()}} method returns
197+
a promise that represents a request for access to MIDI devices on
198+
the user's system.
198199
</p>
199200
<p>
200201
Requesting MIDI access SHOULD prompt the user for access to MIDI
@@ -216,106 +217,170 @@ <h2>
216217
</p>
217218
<p data-link-for="Navigator">
218219
When the {{requestMIDIAccess()}} method is called, the user agent
219-
MUST run the <dfn>algorithm to request MIDI Access</dfn>:
220+
MUST run the following steps:
220221
</p>
221222
<ol>
222223
<li>
223224
<p>
224-
Let <var>promise</var> be a new Promise object and
225-
<var>resolver</var> be its associated resolver.
226-
</p>
227-
</li>
228-
<li>
229-
<p>
230-
Return <var>promise</var> and run the following steps
231-
asynchronously.
232-
</p>
233-
</li>
234-
<li>
235-
<p>
236-
Let <var>document</var> be the calling context's
237-
<a>Document</a>.
238-
</p>
239-
</li>
240-
<li>
241-
<p>
242-
If <var>document</var> is not <a>allowed to use</a> the
243-
<a>policy-controlled feature</a> named <a>midi</a>, jump to
244-
the step labeled <em>failure</em> below.
245-
</p>
246-
</li>
247-
<li>
248-
<p>
249-
Optionally, e.g. based on a previously-established user
250-
preference, for security reasons, or due to platform
251-
limitations, jump to the step labeled <em>failure</em> below.
252-
</p>
253-
</li>
254-
<li>
255-
<p>
256-
Optionally, e.g. based on a previously-established user
257-
preference, jump to the step labeled <em>success</em> below.
258-
</p>
259-
</li>
260-
<li>
261-
<p>
262-
Prompt the user in a user-agent-specific manner for
263-
permission to provide the entry script's origin with a
264-
{{MIDIAccess}} object representing control over user's MIDI
265-
devices. This prompt may be contingent upon whether system
266-
exclusive support was requested, and may allow the user to
267-
enable or disable that access.
268-
</p>
269-
<p>
270-
If permission is denied, jump to the step labeled
271-
<em>failure</em> below. If the user never responds, this
272-
algorithm will never progress beyond this step. If permission
273-
is granted, continue the following steps.
274-
</p>
275-
</li>
276-
<li>
277-
<p>
278-
<em><b>success</b></em>: Let <var>access</var> be a new
279-
{{MIDIAccess}} object. (It is possible to call
280-
requestMIDIAccess() multiple times; this may prompt the user
281-
multiple times, so it may not be best practice, and the same
282-
instance of MIDIAccess will not be returned each time.)
283-
</p>
284-
</li>
285-
<li>
286-
<p>
287-
Call <var>resolver</var>'s <code>accept(value)</code> method
288-
with <var>access</var> as value argument.
289-
</p>
290-
</li>
291-
<li>
292-
<p>
293-
Terminate these steps.
294-
</p>
295-
</li>
296-
<li>
297-
<p>
298-
<em><b>failure</b></em>: Let <var>error</var> be a new
299-
{{DOMException}}. This exception's .name should be
300-
{{"SecurityError"}} if the user or their security settings
301-
denied the application from creating a MIDIAccess instance
302-
with the requested options, or if the error is the result of
303-
<var>document</var> not being <a>allowed to use</a> the
304-
feature, {{"AbortError"}} if the page is going to be closed
305-
for a user navigation, {{"InvalidStateError"}} if the
306-
underlying systems raise any errors, or otherwise it should
307-
be {{"NotSupportedError"}}.
225+
Let <var>promise</var> be [=a new promise=].
308226
</p>
309227
</li>
310228
<li>
311229
<p>
312-
Call <var>resolver</var>'s <code>reject(value)</code> method
313-
with <var>error</var> as value argument.
230+
Run the following steps [=in parallel=]:
314231
</p>
315232
</li>
233+
<ol>
234+
<li>
235+
<p>
236+
Let <var>document</var> be the calling context's
237+
<a>Document</a>.
238+
</p>
239+
</li>
240+
<li>
241+
<p>
242+
If <var>document</var> is not <a>allowed to use</a> the
243+
<a>policy-controlled feature</a> named <a>"midi"</a>, then:
244+
<ol>
245+
<li>
246+
<p>
247+
[=Deny MIDI access=] with |promise| and
248+
{{"SecurityError"}}.
249+
</p>
250+
</li>
251+
<li>
252+
<p>Return |promise|.</p>
253+
</li>
254+
</ol>
255+
</p>
256+
</li>
257+
<li>
258+
<p>
259+
Optionally, e.g. based on a previously-established user
260+
preference, for security reasons, or due to platform
261+
limitations:
262+
<ol>
263+
<li>
264+
<p>
265+
Let |exception name| be {{"SecurityError"}} if the
266+
user or their security settings denied the application
267+
from creating a {{MIDIAccess}} instance with the
268+
requested options, {{"AbortError"}} if the
269+
page is going to be closed for a user navigation,
270+
{{"InvalidStateError"}} if the underlying systems
271+
raise any errors, or otherwise to
272+
{{"NotSupportedError"}}.
273+
</p>
274+
<li>
275+
<p>
276+
[=Deny MIDI access=] with |promise| and
277+
|exception name|.
278+
</p>
279+
</li>
280+
<li>
281+
<p>Return |promise|.</p>
282+
</li>
283+
</li>
284+
</ol>
285+
</p>
286+
</li>
287+
<li>
288+
<p>
289+
Optionally, e.g. based on a previously-established user
290+
preference:
291+
<ol>
292+
<li>
293+
<p>
294+
[=Grant MIDI access=] with |promise|.
295+
</p>
296+
</li>
297+
<li>
298+
<p>Return |promise|.</p>
299+
</li>
300+
</ol>
301+
</p>
302+
</li>
303+
<li>
304+
<p>
305+
Prompt the user in a user-agent-specific manner for
306+
permission to provide the entry script's origin with a
307+
{{MIDIAccess}} object representing control over user's MIDI
308+
devices. This prompt may be contingent upon whether system
309+
exclusive support was requested, and may allow the user to
310+
enable or disable that access:
311+
<ol>
312+
<li>
313+
<p>
314+
If permission is denied:
315+
<ol>
316+
<li>
317+
<p>
318+
[=Deny MIDI access=] with |promise| and
319+
{{"SecurityError"}}.
320+
</p>
321+
</li>
322+
<li>
323+
<p>Return |promise|.</p>
324+
</li>
325+
</ol>
326+
</p>
327+
</li>
328+
<li>
329+
<p>
330+
If permission is granted:
331+
</p>
332+
<ol>
333+
<li>
334+
<p>
335+
[=Grant MIDI access=] with |promise|.
336+
</p>
337+
</li>
338+
<li>
339+
<p>Return |promise|.</p>
340+
</li>
341+
</ol>
342+
</p>
343+
</li>
344+
</ol>
345+
</p>
346+
</li>
347+
</ol>
316348
</ol>
317349
</dd>
318350
</dl>
351+
<p>
352+
To <dfn>deny MIDI access</dfn> with |promise| and |exception name|,
353+
run these steps:
354+
<ol>
355+
<li>
356+
<p>Let |error| be a new {{DOMException}} with its
357+
{{DOMException/name}} set to |exception name|.</p>
358+
</li>
359+
<li>
360+
<p>[=Reject=] |promise| with |error|.</p>
361+
</li>
362+
</ol>
363+
</p>
364+
<p>
365+
To <dfn>grant MIDI access</dfn> with |promise|, run these
366+
steps:
367+
<ol>
368+
<li>
369+
<p>
370+
Let <var>access</var> be a new {{MIDIAccess}} object.
371+
</p>
372+
<p class="note">
373+
It is possible to call {{Navigator/requestMIDIAccess()}}
374+
multiple times; this may prompt the user multiple times, so it
375+
may not be best practice, and the same instance of
376+
{{MIDIAccess}} will not be returned each time.
377+
</p>
378+
</li>
379+
<li>
380+
<p>[=Resolve=] |promise| with |access|.</p>
381+
</li>
382+
</ol>
383+
</p>
319384
</section>
320385
<section data-dfn-for="MidiPermissionDescriptor" data-link-for="Navigator">
321386
<h2 id="MidiPermissionDescriptor">

0 commit comments

Comments
 (0)