DSTEngine/hGameTest/node_modules/openfl/docs/classes/openfl.media.soundloadercontext.html
2025-01-15 19:28:55 +01:00

455 lines
24 KiB
HTML

<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>SoundLoaderContext | openfl</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="../assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="../assets/js/search.js" data-base="..">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="../index.html" class="title">openfl</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-externals" checked />
<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="../index.html">openfl</a>
</li>
<li>
<a href="../modules/openfl.media.html">media</a>
</li>
<li>
<a href="openfl.media.soundloadercontext.html">SoundLoaderContext</a>
</li>
</ul>
<h1>Class SoundLoaderContext</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<section class="tsd-panel tsd-comment">
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>The SoundLoaderContext class provides security checks for files that load
sound. SoundLoaderContext objects are passed as an argument to the
constructor and the <code>load()</code> method of the Sound class.</p>
</div>
<p>When you use this class, consider the following security model:</p>
<ul>
<li>Loading and playing a sound is not allowed if the calling file is in
a network sandbox and the sound file to be loaded is local.</li>
<li>By default, loading and playing a sound is not allowed if the calling
is local and tries to load and play a remote sound. A user must grant
explicit permission to allow this.</li>
<li>Certain operations dealing with sound are restricted. The data in a
loaded sound cannot be accessed by a file in a different domain unless you
implement a URL policy file. Sound-related APIs that fall under this
restriction are the <code>Sound.id3</code> property and the
<code>SoundMixer.computeSpectrum()</code>,
<code>SoundMixer.bufferTime</code>, and <code>SoundTransform()</code>
methods.</li>
</ul>
<p>However, in Adobe AIR, content in the <code>application</code> security
sandbox(content installed with the AIR application) are not restricted by
these security limitations.</p>
<p>For more information related to security, see the Flash Player Developer
Center Topic: <a href="http://www.adobe.com/go/devnet_security_en">Security</a>.</p>
</div>
</section>
<section class="tsd-panel tsd-hierarchy">
<h3>Hierarchy</h3>
<ul class="tsd-hierarchy">
<li>
<span class="target">SoundLoaderContext</span>
</li>
</ul>
</section>
<section class="tsd-panel-group tsd-index-group">
<h2>Index</h2>
<section class="tsd-panel tsd-index-panel">
<div class="tsd-index-content">
<section class="tsd-index-section tsd-is-external">
<h3>Constructors</h3>
<ul class="tsd-index-list">
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-external"><a href="openfl.media.soundloadercontext.html#constructor" class="tsd-kind-icon">constructor</a></li>
</ul>
</section>
<section class="tsd-index-section tsd-is-external">
<h3>Properties</h3>
<ul class="tsd-index-list">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-external"><a href="openfl.media.soundloadercontext.html#buffertime" class="tsd-kind-icon">buffer<wbr>Time</a></li>
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-external"><a href="openfl.media.soundloadercontext.html#checkpolicyfile" class="tsd-kind-icon">check<wbr>Policy<wbr>File</a></li>
</ul>
</section>
</div>
</section>
</section>
<section class="tsd-panel-group tsd-member-group tsd-is-external">
<h2>Constructors</h2>
<section class="tsd-panel tsd-member tsd-kind-constructor tsd-parent-kind-class tsd-is-external">
<a name="constructor" class="tsd-anchor"></a>
<h3>constructor</h3>
<ul class="tsd-signatures tsd-kind-constructor tsd-parent-kind-class tsd-is-external">
<li class="tsd-signature tsd-kind-icon">new <wbr>Sound<wbr>Loader<wbr>Context<span class="tsd-signature-symbol">(</span>bufferTime<span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">number</span>, checkPolicyFile<span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">boolean</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><a href="openfl.media.soundloadercontext.html" class="tsd-signature-type">SoundLoaderContext</a></li>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/openfl/openfl/blob/9921d3bf/lib/openfl/media/SoundLoaderContext.d.ts#L141">lib/openfl/media/SoundLoaderContext.d.ts:141</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Creates a new sound loader context object.</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
<h5><span class="tsd-flag ts-flagOptional">Optional</span> bufferTime: <span class="tsd-signature-type">number</span></h5>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>The number of seconds to preload a streaming sound
into a buffer before the sound starts to stream.</p>
</div>
</div>
</li>
<li>
<h5><span class="tsd-flag ts-flagOptional">Optional</span> checkPolicyFile: <span class="tsd-signature-type">boolean</span></h5>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Specifies whether the existence of a URL policy
file should be checked upon loading the object
(<code>true</code>) or not.</p>
</div>
</div>
</li>
</ul>
<h4 class="tsd-returns-title">Returns <a href="openfl.media.soundloadercontext.html" class="tsd-signature-type">SoundLoaderContext</a></h4>
</li>
</ul>
</section>
</section>
<section class="tsd-panel-group tsd-member-group tsd-is-external">
<h2>Properties</h2>
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-class tsd-is-external">
<a name="buffertime" class="tsd-anchor"></a>
<h3>buffer<wbr>Time</h3>
<div class="tsd-signature tsd-kind-icon">buffer<wbr>Time<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">number</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/openfl/openfl/blob/9921d3bf/lib/openfl/media/SoundLoaderContext.d.ts#L50">lib/openfl/media/SoundLoaderContext.d.ts:50</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>The number of milliseconds to preload a streaming sound into a buffer
before the sound starts to stream.</p>
</div>
<p>Note that you cannot override the value of
<code>SoundLoaderContext.bufferTime</code> by setting the global
<code>SoundMixer.bufferTime</code> property. The
<code>SoundMixer.bufferTime</code> property affects the buffer time for
embedded streaming sounds in a SWF file and is independent of dynamically
created Sound objects(that is, Sound objects created in
ActionScript).</p>
</div>
</section>
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-class tsd-is-external">
<a name="checkpolicyfile" class="tsd-anchor"></a>
<h3>check<wbr>Policy<wbr>File</h3>
<div class="tsd-signature tsd-kind-icon">check<wbr>Policy<wbr>File<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">boolean</span></div>
<aside class="tsd-sources">
<ul>
<li>Defined in <a href="https://github.com/openfl/openfl/blob/9921d3bf/lib/openfl/media/SoundLoaderContext.d.ts#L141">lib/openfl/media/SoundLoaderContext.d.ts:141</a></li>
</ul>
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Specifies whether the application should try to download a URL policy file
from the loaded sound&#39;s server before beginning to load the sound. This
property applies to sound that is loaded from outside the calling file&#39;s
own domain using the <code>Sound.load()</code> method.</p>
</div>
<p>Set this property to <code>true</code> when you load a sound from
outside the calling file&#39;s own domain and code in the calling file needs
low-level access to the sound&#39;s data. Examples of low-level access to a
sound&#39;s data include referencing the <code>Sound.id3</code> property to
get an ID3Info object or calling the
<code>SoundMixer.computeSpectrum()</code> method to get sound samples from
the loaded sound. If you try to access sound data without setting the
<code>checkPolicyFile</code> property to <code>true</code> at loading
time, you may get a SecurityError exception because the required policy
file has not been downloaded.</p>
<p>If you don&#39;t need low-level access to the sound data that you are
loading, avoid setting <code>checkPolicyFile</code> to <code>true</code>.
Checking for a policy file consumes network bandwidth and might delay the
start of your download, so it should only be done when necessary.</p>
<p>When you call <code>Sound.load()</code> with
<code>SoundLoaderContext.checkPolicyFile</code> set to <code>true</code>,
Flash Player or AIR must either successfully download a relevant URL
policy file or determine that no such policy file exists before it begins
downloading the specified sound. Flash Player or AIR performs the
following actions, in this order, to verify the existence of a policy
file:</p>
<ul>
<li>Flash Player or AIR considers policy files that have already been
downloaded.</li>
<li>Flash Player or AIR tries to download any pending policy files
specified in calls to <code>Security.loadPolicyFile()</code>.</li>
<li>Flash Player or AIR tries to download a policy file from the default
location that corresponds to the sound&#39;s URL, which is
<code>/crossdomain.xml</code> on the same server as
<code>URLRequest.url</code>.(The sound&#39;s URL is specified in the
<code>url</code> property of the URLRequest object passed to
<code>Sound.load()</code> or the Sound() constructor function.)</li>
</ul>
<p>In all cases, Flash Player or AIR requires that an appropriate policy
file exist on the sound&#39;s server, that it provide access to the sound file
at <code>URLRequest.url</code> by virtue of the policy file&#39;s location,
and that it allow the domain of the calling file to access the sound,
through one or more <code>&lt;allow-access-from&gt;</code> tags.</p>
<p>If you set <code>checkPolicyFile</code> to <code>true</code>, Flash
Player or AIR waits until the policy file is verified before loading the
sound. You should wait to perform any low-level operations on the sound
data, such as calling <code>Sound.id3</code> or
<code>SoundMixer.computeSpectrum()</code>, until <code>progress</code> and
<code>complete</code> events are dispatched from the Sound object.</p>
<p>If you set <code>checkPolicyFile</code> to <code>true</code> but no
appropriate policy file is found, you will not receive an error until you
perform an operation that requires a policy file, and then Flash Player or
AIR throws a <code>SecurityError</code> exception. After you receive a
<code>complete</code> event, you can test whether a relevant policy file
was found by getting the value of <code>Sound.id3</code> within a
<code>try</code> block and seeing if a <code>SecurityError</code> is
thrown.</p>
<p>Be careful with <code>checkPolicyFile</code> if you are downloading
sound from a URL that uses server-side HTTP redirects. Flash Player or AIR
tries to retrieve policy files that correspond to the <code>url</code>
property of the URLRequest object passed to <code>Sound.load()</code>. If
the final sound file comes from a different URL because of HTTP redirects,
then the initially downloaded policy files might not be applicable to the
sound&#39;s final URL, which is the URL that matters in security
decisions.</p>
<p>If you find yourself in this situation, here is one possible solution.
After you receive a <code>progress</code> or <code>complete</code> event,
you can examine the value of the <code>Sound.url</code> property, which
contains the sound&#39;s final URL. Then call the
<code>Security.loadPolicyFile()</code> method with a policy file URL that
you calculate based on the sound&#39;s final URL. Finally, poll the value of
<code>Sound.id3</code> until no exception is thrown.</p>
<p>This does not apply to content in the AIR application sandbox. Content
in the application sandbox always has programatic access to sound content,
regardless of its origin.</p>
<p>For more information related to security, see the Flash Player
Developer Center Topic: <a href="http://www.adobe.com/go/devnet_security_en">Security</a>.</p>
</div>
</section>
</section>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="label tsd-is-external">
<span>Externals</span>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.desktop.html">openfl.desktop</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.display.html">openfl.display</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.display3d.html">openfl.display3D</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.errors.html">openfl.errors</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.events.html">openfl.events</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.external.html">openfl.external</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.filters.html">openfl.filters</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.geom.html">openfl.geom</a>
</li>
<li class="current tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.media.html">openfl.media</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.net.html">openfl.net</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.profiler.html">openfl.profiler</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.sensors.html">openfl.sensors</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.system.html">openfl.system</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.text.html">openfl.text</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.ui.html">openfl.ui</a>
</li>
<li class=" tsd-kind-module tsd-parent-kind-module tsd-is-external">
<a href="../modules/openfl.utils.html">openfl.utils</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
<li class=" tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.id3info.html" class="tsd-kind-icon">ID3<wbr>Info</a>
</li>
<li class=" tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.sound.html" class="tsd-kind-icon">Sound</a>
</li>
<li class=" tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.soundchannel.html" class="tsd-kind-icon">Sound<wbr>Channel</a>
</li>
</ul>
<ul class="current">
<li class="current tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.soundloadercontext.html" class="tsd-kind-icon">Sound<wbr>Loader<wbr>Context</a>
<ul>
<li class=" tsd-kind-constructor tsd-parent-kind-class tsd-is-external">
<a href="openfl.media.soundloadercontext.html#constructor" class="tsd-kind-icon">constructor</a>
</li>
<li class=" tsd-kind-property tsd-parent-kind-class tsd-is-external">
<a href="openfl.media.soundloadercontext.html#buffertime" class="tsd-kind-icon">buffer<wbr>Time</a>
</li>
<li class=" tsd-kind-property tsd-parent-kind-class tsd-is-external">
<a href="openfl.media.soundloadercontext.html#checkpolicyfile" class="tsd-kind-icon">check<wbr>Policy<wbr>File</a>
</li>
</ul>
</li>
</ul>
<ul class="after-current">
<li class=" tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.soundtransform.html" class="tsd-kind-icon">Sound<wbr>Transform</a>
</li>
<li class=" tsd-kind-class tsd-parent-kind-module tsd-is-external">
<a href="openfl.media.video.html" class="tsd-kind-icon">Video</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="../assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="../assets/js/search.js"><' + '/script>');</script>
</body>
</html>