nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BMediaRoster.html

636 lines
139 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Media Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheMediaKit.html" title="The Media Kit" /><link rel="prev" href="BMediaNode.html" title="BMediaNode" /><link rel="next" href="BMediaTheme.html" title="BMediaTheme" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMediaNode.html" title="BMediaNode"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BMediaTheme.html" title="BMediaTheme"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Media Kit</div></div><div id="headerB">Prev: <a href="BMediaNode.html">BMediaNode</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BMediaTheme.html">BMediaTheme</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster"></a>BMediaRoster</h2></div></div></div><a id="id1149564" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td>–</td></tr><tr><td>Mix-in Classes:</td><td>–</td></tr><tr><td>Declared In:</td><td><code class="filename">media/MediaRoster.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libmedia.so</code></td></tr><tr><td>Allocation:</td><td>Constructor only</td></tr></tbody></table></td><td>
<a class="link overview" href="BMediaRoster_Overview.html" title="BMediaRoster">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BMediaRoster.html#BMediaRoster_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BMediaRoster.html#BMediaRoster_MemberFunctions">Member Functions</a></span></li><li><span class="section"><a href="BMediaRoster.html#BMediaRoster_Constants">Constants</a></span></li></ul></div>
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_ConstructorDestructor"></a>Constructor and Destructor</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_Constructor"></a>BMediaRoster()</h4></div></div></div><code class="constructorsynopsis cpp"><span class="methodname">BMediaRoster</span>();</code><p>You never construct a <code class="classname">BMediaRoster</code> yourself. Instead, use the static
<a class="link" href="BMediaRoster.html#BMediaRoster_Roster" title="Roster(), CurrentRoster()"><code class="methodname">Roster()</code></a>
function to obtain an instance of the <code class="classname">BMediaRoster</code> class that
you can use.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_Destructor"></a>~BMediaRoster()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BMediaRoster</span>();</code><p>You never delete a <code class="classname">BMediaRoster</code> yourself.
Just let it go away automatically when your application shuts down.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_MemberFunctions"></a>Member Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_AudioBufferSizeFor"></a>AudioBufferSizeFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">ssize_t </span><span class="methodname">AudioBufferSizeFor</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">channelCount</span></span>,<br />                           <span class="methodparam"><span class="type">uint32 </span><span class="parameter">sampleFormat</span></span>,<br />                           <span class="methodparam"><span class="type">float </span><span class="parameter">frameRate</span></span>,<br />                           <span class="methodparam"><span class="type">bus_type </span><span class="parameter">busKind</span></span>);</code><p><code class="methodname">AudioBufferSizeFor()</code> returns the size,
in bytes, that the Media Kit recommends for audio data with
<code class="parameter">channelCount</code> channels, with the specified
<code class="parameter">sampleFormat</code> and <code class="parameter">frameRate</code>.</p><p>The <code class="parameter">busKind</code> argument is a
<span class="type">bus_type</span> value (see
<code class="filename">drivers/config_manager.h</code>)
indicating the type of bus the data is moving across. Specify
<code class="constant">B_UNKNOWN_BUS</code> if you don't know.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_Connect"></a><a id="BMediaRoster_Disconnect"></a>
Connect(), Disconnect()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Connect</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_source&amp; </span><span class="parameter">source</span></span>,<br />                 <span class="methodparam"><span class="modifier">const </span><span class="type">media_destination&amp; </span><span class="parameter">destination</span></span>,<br />                 <span class="methodparam"><span class="type">media_format* </span><span class="parameter">ioFormat</span></span>,<br />                 <span class="methodparam"><span class="type">media_output* </span><span class="parameter">outOutput</span></span>,<br />                 <span class="methodparam"><span class="type">media_input* </span><span class="parameter">outInput</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Connect</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_source&amp; </span><span class="parameter">source</span></span>,<br />                 <span class="methodparam"><span class="modifier">const </span><span class="type">media_destination&amp; </span><span class="parameter">destination</span></span>,<br />                 <span class="methodparam"><span class="type">media_format* </span><span class="parameter">ioFormat</span></span>,<br />                 <span class="methodparam"><span class="type">media_output* </span><span class="parameter">outOutput</span></span>,<br />                 <span class="methodparam"><span class="type">media_input* </span><span class="parameter">outInput</span></span>,<br />                 <span class="methodparam"><span class="type">uint32 </span><span class="parameter">inFlags</span></span>,<br />                 <span class="methodparam"><span class="type">void* </span><span class="parameter">_reserved</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Disconnect</span>(<span class="methodparam"><span class="type">media_node_id </span><span class="parameter">sourceNode</span></span>,<br />                    <span class="methodparam"><span class="modifier">const </span><span class="type">media_source&amp; </span><span class="parameter">source</span></span>,<br />                    <span class="methodparam"><span class="type">media_node_id </span><span class="parameter">destinationNode</span></span>,<br />                    <span class="methodparam"><span class="modifier">const </span><span class="type">media_destination&amp; </span><span class="parameter">destination</span></span>);</code><p><code class="methodname">Connect()</code> negotiates a connection
from the <code class="parameter">source</code> to the <code class="parameter">destination</code>,
using the media format specified in <code class="parameter">ioFormat</code> as a basis for the
negotiation; <code class="parameter">ioFormat</code> is changed to the negotiated format before this
call returns. This describes the format of media data that will flow
across the connection.</p><p>The actual connection is returned as an output and an input in <code class="parameter">outOutput</code>
and <code class="parameter">outInput</code>. These two structures contain the data format as interpreted
by the source and destination. There may be differences among these
formats if wildcard fields were used in the original format.</p><p>The second form of <code class="methodname">Connect()</code> lets you specify connect flags. Currently
the only possible flag is <code class="constant">B_CONNECT_MUTED</code>, which indicates that the
connection should be muted on creation.</p><p>The actual
<a class="link" href="TheMediaKit_DefinedTypes.html#media_source" title="media_source"><span class="type">media_source</span></a> and
<a class="link" href="TheMediaKit_DefinedTypes.html#media_destination" title="media_destination"><span class="type">media_destination</span></a>
used for the connection may vary from those passed into
<code class="methodname">Connect()</code> if the source or the destination
creates new sources or destinations for each connection request; the
<code class="parameter">outOutput</code> and <code class="parameter">outInput</code>
structures contain the actual
<a class="link" href="TheMediaKit_DefinedTypes.html#media_source" title="media_source"><span class="type">media_source</span></a> and
<a class="link" href="TheMediaKit_DefinedTypes.html#media_destination" title="media_destination"><span class="type">media_destination</span></a>
values resulting from the call.</p><p>For more detailed information on the use of wildcards in format
negotiation, see
media_audio_format::wildcard and
media_video_format::wildcard.
A <a class="link" href="TheMediaKit_DefinedTypes.html#media_format" title="media_format"><span class="type">media_format</span></a>
with a type of
<code class="constant">B_MEDIA_UNKNOWN_TYPE</code> matches any media class and format, although without
specific knowledge of the source and destination, this will rarely result
in a useful connection.</p><p><code class="methodname">Disconnect()</code> breaks the
connection established between <code class="parameter">source</code> and
<code class="parameter">destination</code>, which must belong to the
nodes <code class="parameter">sourceNode</code> and
<code class="parameter">destinationNode</code>, repectively.</p><p>The result of breaking a connection that's currently running is
undefined, but is not permitted to crash. Your application should stop
both nodes involved in a connection prior to disconnecting them.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error terminating the connection.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The connection couldn't be made.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>The nodes that are being connected may return other
error codes as they see fit.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetAllInputsFor"></a><a id="BMediaRoster_GetAllOutputsFor"></a>
GetAllInputsFor(), GetAllOutputsFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAllInputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                         <span class="methodparam"><span class="type">media_input* </span><span class="parameter">outInputs</span></span>,<br />                         <span class="methodparam"><span class="type">int32 </span><span class="parameter">bufNumInputs</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">outTotalCount</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAllOutputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                          <span class="methodparam"><span class="type">media_output* </span><span class="parameter">outOutputs</span></span>,<br />                          <span class="methodparam"><span class="type">int32 </span><span class="parameter">bufNumOutputs</span></span>,<br />                          <span class="methodparam"><span class="type">int32* </span><span class="parameter">outTotalCount</span></span>);</code><p><code class="methodname">GetAllInputsFor()</code> fills the array of
<a class="link" href="TheMediaKit_DefinedTypes.html#media_input" title="media_input"><span class="type">media_input</span></a>
structures specified by <code class="parameter">outInputs</code> with information
about all inputs belonging to node; the number
of elements that <code class="parameter">outInputs</code> can hold is passed
in <code class="parameter">bufNumInputs</code>.</p><p>Similarly, <code class="methodname">GetAllOutputsFor()</code> fills the
array <code class="parameter">outOutputs</code> with information
about all outputs from the specified node.</p><p>Both functions return the number of elements actually returned in the
buffer in <code class="parameter">outTotalCount</code>. If this number is less than the number you
requested, your buffer was too small to receive all the results of the
query. In this case, you might want to resize your array and try again.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The node isn't of the correct type for the call you issued.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>An error occurred communicating with the producer or
with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetAudioInput"></a><a id="BMediaRoster_GetVideoInput"></a>
GetAudioInput(), GetVideoInput()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAudioInput</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetVideoInput</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code><p>These functions return the nodes designated by the user as the preferred
nodes for audio and video input. You can then query the returned node,
hook into it, and manipulate it, using the reference returned in
<code class="parameter">outNode</code>.</p><p>Once your application has finished using these nodes (and they've been
stopped and disconnected), you should release them by calling
<code class="methodname">ReleaseNode()</code>.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error locating the default input node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The default node couldn't be identified.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetAudioOutput"></a><a id="BMediaRoster_GetVideoOutput"></a>
<a id="BMediaRoster_GetAudioMixer"></a>
GetAudioOutput(), GetVideoOutput(), GetAudioMixer()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAudioOutput</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAudioOutput</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>,<br />                        <span class="methodparam"><span class="type">int32* </span><span class="parameter">outInputID</span></span>,<br />                        <span class="methodparam"><span class="type"><span class="classname">BString</span>* </span><span class="parameter">outInputName</span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetVideoOutput</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetAudioMixer</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code><p>These functions return the nodes designated by the user as the preferred
nodes for audio and video output. You can then query the returned node,
hook into it, and manipulate it, using the reference returned in
<code class="parameter">outNode</code>.</p><p>The second form of <code class="methodname">GetAudioOutput()</code> returns additional information,
including the input ID of the input used for audio output, and the
input's name.</p><p>You should usually use <code class="methodname">GetAudioMixer()</code> when getting a node for playing
audio instead of using the <code class="methodname">GetAudioOutput()</code> function. <code class="methodname">GetAudioOutput()</code>
returns the lower-level node for audio output, which you would typically
only need access to if you wanted to do some form of processing on all
audio data being played in the system (such as a level meter).</p><p>The <code class="methodname">GetAudioMixer()</code> function returns a reference to the audio mixer,
which will perform audio mixing, format conversion, and sample rate
conversion for you, then pass along the audio to the output node.</p><p>Once your application has finished using these nodes (and they've been
stopped and disconnected), you should release them by calling
<a class="link" href="BMediaRoster.html#BMediaRoster_ReleaseNode" title="ReleaseNode()"><code class="methodname">ReleaseNode()</code></a>.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error locating the default input node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The default node couldn't be identified.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetConnectedInputsFor"></a><a id="BMediaRoster_GetFreeInputsFor"></a>
GetConnectedInputsFor(), GetFreeInputsFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetConnectedInputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                               <span class="methodparam"><span class="type">media_input* </span><span class="parameter">outActiveInputsList</span></span>,<br />                               <span class="methodparam"><span class="type">int32 </span><span class="parameter">numListInputs</span></span>,<br />                               <span class="methodparam"><span class="type">int32* </span><span class="parameter">outNumInputs</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFreeInputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                          <span class="methodparam"><span class="type">media_input* </span><span class="parameter">outFreeInputsList</span></span>,<br />                          <span class="methodparam"><span class="type">int32 </span><span class="parameter">numListInputs</span></span>,<br />                          <span class="methodparam"><span class="type">int32* </span><span class="parameter">outNumInputs</span></span>,<br />                          <span class="methodparam"><span class="type">media_type </span><span class="parameter">filterType</span><span class="initializer"> = <span class="constant">B_MEDIA_UNKNOWN_TYPE</span></span></span>);</code><p><code class="methodname">GetConnectedInputsFor()</code> fills the array of
<a class="link" href="TheMediaKit_DefinedTypes.html#media_input" title="media_input"><span class="type">media_input</span></a>
structures specified by <code class="parameter">outActiveInputsList</code> with
information about all inputs belonging to node that are currently connected
to some output; the number of elements that
<code class="parameter">outActiveInputsList</code> can hold is passed in
<code class="parameter">numListInputs</code>.</p><p>Similarly, <code class="methodname">GetFreeInputsFor()</code> fills
the array <code class="parameter">outFreeInputsList</code> with
information about all inputs that are still available in the specified
node. Specifying a <code class="parameter">filterType</code> other than
<code class="constant">B_MEDIA_NO_TYPE</code> lets you obtain
a list of inputs for a specific media type (or for inputs that can handle
any media type). This is especially useful if you're only interested in a
list of accepted media types your application supports.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Even though a node may report that a specific number of free inputs are
available, it is possible that a node might create more inputs on demand.
There is no way to know if this might happen, so <code class="methodname">GetFreeInputsFor()</code> may
not tell you whether or not a node can accept all the connections you'd
like to make.</p></div></div></div><p>Both functions return the number of elements actually returned in the
buffer in <code class="parameter">outNumInputs</code>. If this number is less
than <code class="parameter">numListInputs</code>, your
buffer was too small to receive all the results of the query. In this
case, you might want to resize your array and try again.</p><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error cloning the node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetConnectedOutputsFor"></a><a id="BMediaRoster_GetFreeOutputsFor"></a>
GetConnectedOutputsFor(), GetFreeOutputsFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetConnectedOutputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                                <span class="methodparam"><span class="type">media_output* </span><span class="parameter">outActiveOutputsList</span></span>,<br />                                <span class="methodparam"><span class="type">int32 </span><span class="parameter">numListOutputs</span></span>,<br />                                <span class="methodparam"><span class="type">int32* </span><span class="parameter">outNumOutputs</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFreeOutputsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                           <span class="methodparam"><span class="type">media_output* </span><span class="parameter">outFreeOutputsList</span></span>,<br />                           <span class="methodparam"><span class="type">int32 </span><span class="parameter">numListOutputs</span></span>,<br />                           <span class="methodparam"><span class="type">int32* </span><span class="parameter">outNumOutputs</span></span>,<br />                           <span class="methodparam"><span class="type">media_type </span><span class="parameter">filterType</span><span class="initializer"> = <span class="constant">B_MEDIA_UNKNOWN_TYPE</span></span></span>);</code><p><code class="methodname">GetConnectedOutputsFor()</code> fills the array of
<a class="link" href="TheMediaKit_DefinedTypes.html#media_output" title="media_output"><span class="type">media_output</span></a>
structures specified by <code class="parameter">outActiveOutputsList</code> with information about all outputs
belonging to node that are currently connected to some input; the number
of elements that <code class="parameter">outActiveOutputsList</code> can hold is passed in
<code class="parameter">numListOutputs</code>.</p><p>Similarly, <code class="methodname">GetFreeOutputsFor()</code> fills the array <code class="parameter">outFreeOutputsList</code> with
information about all outputs that are still available in the specified
node. Specifying a <code class="parameter">filterType</code> other than <code class="constant">B_MEDIA_UNKNOWN_TYPE</code> lets you
obtain a list of outputs for a specific media type (or for outputs that
can handle any media type). This is especially useful if you're only
interested in a list of accepted media types your application supports.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Even though a node may report that a specific number of free outputs
are available, it is possible that a node might create more outputs on
demand. There is no way to know if this might happen, so
<code class="methodname">GetFreeOutputsFor()</code> may not tell you whether or not a node can accept all
the connections you'd like to make.</p></div></div></div><p>Both functions return the number of elements actually returned in the
buffer in <code class="parameter">outNumOutputs</code>. If this number is
less than <code class="parameter">numListOutputs</code>, your
buffer was too small to receive all the results of the query. In this
case, you might want to resize your array and try again.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The node isn't a buffer producer.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>An error occurred communicating with the producer or with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetDormantFlavorInfoFor"></a>GetDormantFlavorInfoFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetDormantFlavorInfoFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">inDormantNode</span></span>,<br />                                 <span class="methodparam"><span class="type">dormant_flavor_info* </span><span class="parameter">outFlavor</span></span>);</code><p>This function returns, in <code class="parameter">outFlavor</code>, information describing the dormant
flavors supported by the dormant node <code class="parameter">inDormantNode</code>.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Messaging errors.</span></p></td><td><p>An error occurred communicating with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetDormantNodes"></a>GetDormantNodes()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetDormantNodes</span>(<span class="methodparam"><span class="type">dormant_node_info* </span><span class="parameter">outDormantNodeList</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">inOutNumNodes</span></span>,<br />                         <span class="methodparam"><span class="modifier">const </span><span class="type">media_format* </span><span class="parameter">hasInputFormat</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                         <span class="methodparam"><span class="modifier">const </span><span class="type">media_format* </span><span class="parameter">hasOutputFormat</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                         <span class="methodparam"><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                         <span class="methodparam"><span class="type">uint64 </span><span class="parameter">requireKinds</span><span class="initializer"> = 0</span></span>,<br />                         <span class="methodparam"><span class="type">uint64 </span><span class="parameter">denyKinds</span><span class="initializer"> = 0</span></span>);</code><p>Queries dormant nodes (those nodes that live in add-ons, rather
than in the application) and returns those who match the specified inputs.
If <code class="parameter">hasInputFormat</code> isn't
<code class="constant">NULL</code>, the node has to be a
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>
and have an input format compatible with the format described in
<code class="parameter">hasInputFormat</code>. Likewise, if
<code class="parameter">hasOutputFormat</code> isn't
<code class="constant">NULL</code>, the node has to be a
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>
that's compatible with the format described in
<code class="parameter">hasOutputFormat.</code></p><p>If name isn't <code class="constant">NULL</code>, the node has to have a
name that equals <code class="parameter">name</code>, or, if the last character
of name is an asterisk ("*"), a name whose initial characters
match name up to, but not including, the asterisk.</p><p>The <code class="parameter">requireKinds</code> and
<code class="parameter">denyKinds</code> arguments specifiy, respectively, the
kinds that must be supported, and the kinds that must not be supported by
the returned nodes.</p><p>Matching nodes are returned in
<code class="parameter">outDormantNodeList</code>. You should pass the size of
the <code class="parameter">outDormantNodeList</code> array (the number of
elements that the array can hold) in
<code class="parameter">inOutNumNodes</code>; when this function returns, the
value in <code class="parameter">inOutNumNodes</code> will be changed to the
actual number of matching nodes found, unless an error occurs.</p><p>Nodes you obtain using
<code class="methodname">GetDormantNodes()</code> must be released when you're
done using them. To do this, be sure they're stopped and disconnected, then
call
<a class="link" href="BMediaRoster.html#BMediaRoster_ReleaseNode" title="ReleaseNode()"><code class="methodname">ReleaseNode()</code></a>.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error cloning the node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetFileFormatsFor"></a>GetFileFormatsFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFileFormatsFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">fileInterface</span></span>,<br />                           <span class="methodparam"><span class="type">media_file_format* </span><span class="parameter">outFormatList</span></span>,<br />                           <span class="methodparam"><span class="type">int32* </span><span class="parameter">inOutFormatCount</span><span class="initializer"> = 0</span></span>);</code><p>Given a
<a class="link" href="BFileInterface.html" title="BFileInterface"><code class="classname">BFileInterface</code></a>
node in <code class="parameter">fileInterface</code>, returns information about
the file formats the file interface can deal with in the array
<code class="parameter">outFormatList</code>. On entry,
<code class="parameter">inOutFormatCount</code> points to the number of
<a class="link" href="TheMediaKit_DefinedTypes.html#media_file_format" title="media_file_format"><span class="type">media_file_format</span></a>
structures that can fit in the array specified by
<code class="parameter">outFormatList</code>. Upon return, it will contain the
actual number of formats returned, unless
<code class="methodname">GetFileFormatsFor()</code> returns an error.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This function will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the set mode request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetFormatFor"></a>GetFormatFor()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFormatFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_output&amp; </span><span class="parameter">output</span></span>,<br />                      <span class="methodparam"><span class="type">media_format* </span><span class="parameter">ioFormat</span></span>,<br />                      <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span><span class="initializer"> = 0</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFormatFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_input&amp; </span><span class="parameter">input</span></span>,<br />                      <span class="methodparam"><span class="type">media_format* </span><span class="parameter">ioFormat</span></span>,<br />                      <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span><span class="initializer"> = 0</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetFormatFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">input</span></span>,<br />                      <span class="methodparam"><span class="type">media_format* </span><span class="parameter">ioFormat</span></span>,<br />                      <span class="methodparam"><span class="type">float </span><span class="parameter">quality</span><span class="initializer"> = <span class="constant">B_MEDIA_ANY_QUALITY</span></span></span>);</code>
</div><p><code class="methodname">GetFormatFor()</code> returns the
<a class="link" href="TheMediaKit_DefinedTypes.html#media_format" title="media_format"><span class="type">media_format</span></a>
being used by the given object, which may be a
<a class="link" href="TheMediaKit_DefinedTypes.html#media_output" title="media_output"><span class="type">media_output</span></a>,
a <a class="link" href="TheMediaKit_DefinedTypes.html#media_input" title="media_input"><span class="type">media_input</span></a>, or
a <a class="link" href="TheMediaKit_DefinedTypes.html#media_node" title="media_node"><span class="type">media_node</span></a>.
Pass in <code class="parameter">ioFormat</code> a pointer to a
<a class="link" href="TheMediaKit_DefinedTypes.html#media_format" title="media_format"><span class="type">media_format</span></a>
object to be filled out with the object's format.</p><p>The <code class="parameter">flags</code> currently must be zero.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>You can't pass <code class="constant">NULL</code> for
<code class="parameter">ioFormat</code>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The node isn't of the correct type for the given
request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_SOURCE</code></span></p></td><td><p>The node's
<a class="link" href="TheMediaKit_DefinedTypes.html#media_source" title="media_source"><span class="type">media_source</span></a>
is invalid.</p></td></tr><tr><td><p><span class="term">Messaging errors.</span></p></td><td><p>An error occurred communicating with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetInitialLatencyFor"></a>GetInitialLatencyFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetInitialLatencyFor</span>(<span class="methodparam"><span class="type">media_node&amp; </span><span class="parameter">producer</span></span>,<br />                              <span class="methodparam"><span class="type">bigtime_t* </span><span class="parameter">outLatency</span></span>,<br />                              <span class="methodparam"><span class="type">uint32* </span><span class="parameter">outFlags</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p>Returns, in <code class="parameter">outLatency</code>, the
additional amount of time in microseconds the
specified producer node requires in order to synchronize to a signal. For
example, a TV capture card that's started while the capture is in the
middle of a field will have to wait until the next field begins before
actually starting to produce buffers.</p><p><code class="parameter">outFlags</code> is set to the flags
returned by the producer. Currently there
aren't any flags defined, so this will be returned as zero for now.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p><code class="parameter">outLatency</code> was specified as
<code class="constant">NULL</code>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p><code class="parameter">producer</code> isn't a valid node.</p></td></tr><tr><td><p><span class="term">Port errors.</span></p></td><td><p>An error occurred communicating with the producer.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetInstancesFor"></a>GetInstancesFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetInstancesFor</span>(<span class="methodparam"><span class="type">media_addon_id </span><span class="parameter">addon</span></span>,<br />                         <span class="methodparam"><span class="type">int32 </span><span class="parameter">flavor</span></span>,<br />                         <span class="methodparam"><span class="type">media_node_id* </span><span class="parameter">outID</span></span>,<br />                         <span class="methodparam"><span class="type">int32* </span><span class="parameter">ioCount</span><span class="initializer"> = 0</span></span>);</code><p>Given the specified <code class="parameter">addon</code> ID and
<code class="parameter">flavor</code>, this function fills the <code class="parameter">outID</code>
list with up to <code class="parameter">ioCount</code> node IDs that were derived from the specified
add-on. If you specify zero for <code class="parameter">ioCount</code>, one node ID will be returned. On
return, <code class="parameter">ioCount</code> is changed to indicate how many nodes have been returned
in the list.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Port errors.</span></p></td><td><p>Communication with the Media Server failed.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetLatencyFor"></a>GetLatencyFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetLatencyFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">producer</span></span>,<br />                       <span class="methodparam"><span class="type">bigtime_t* </span><span class="parameter">outLatency</span></span>);</code><p>Reports in <code class="parameter">outLatency</code> the maximum latency
found downstream from the specified
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>,
<code class="parameter">producer</code>, given the current connections.</p><p>If an error occurs, the value in <code class="parameter">outLatency</code> is unreliable.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This function will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Unable to get the latency.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetLiveNodes"></a>GetLiveNodes()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetLiveNodes</span>(<span class="methodparam"><span class="type">live_node_info* </span><span class="parameter">outLiveNodeList</span></span>,<br />                      <span class="methodparam"><span class="type">int32* </span><span class="parameter">ioTotalCount</span></span>,<br />                      <span class="methodparam"><span class="modifier">const </span><span class="type">media_format* </span><span class="parameter">hasInput</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                      <span class="methodparam"><span class="modifier">const </span><span class="type">media_format* </span><span class="parameter">hasOutput</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                      <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                      <span class="methodparam"><span class="type">uint64 </span><span class="parameter">nodeKinds</span><span class="initializer"> = 0</span></span>);</code><p>Queries the Media Server for a list of all currently active nodes
(whether they're running or not), and fills the array specified by
<code class="parameter">outLiveNodeList</code> with information about the nodes. The size of the array
should be specified—in terms of how many elements it can
contain—by the <code class="parameter">ioTotalCount</code> argument; the actual number of entries
in the returned list will be stored in <code class="parameter">ioTotalCount</code> before the call
returns.</p><p>An active node is a node that is preloaded by the system and is always
available for use, as opposed to a dormant node, which resides in an
add-on and is only loaded when instantiated using
<a class="link" href="BMediaRoster.html#BMediaRoster_InstantiateDormantNode" title="InstantiateDormantNode()"><code class="methodname">InstantiateDormantNode()</code></a>.</p><p>You can obtain a more specific result list by specifying one or
more of the <code class="parameter">hasInput</code>,
<code class="parameter">hasOutput</code>, <code class="parameter">name</code>, and
<code class="parameter">nodeKinds</code> arguments.
<code class="parameter">hasInput</code> and
<code class="parameter">hasOutput</code> let you restrict the resulting list to
containing nodes that accept as input (or output) the specified
format.</p><p>You should always specify 0 for <code class="parameter">nodeKinds</code>;
this parameter is currently not used.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Unable to get the list of live nodes.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetNodeAttributesFor"></a>GetNodeAttributesFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">ssize_t </span><span class="methodname">GetNodeAttributesFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                             <span class="methodparam"><span class="type">media_node_attributes* </span><span class="parameter">outArray</span></span>,<br />                             <span class="methodparam"><span class="type">size_t </span><span class="parameter">inMaxCount</span></span>);</code><p>Fills the array <code class="parameter">outArray</code> with up
to <code class="parameter">inMaxCount</code> attributes of the given
node. Returns the number of attributes returned. If the result is less
than zero, an error occurred.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetNodeFor"></a>GetNodeFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetNodeFor</span>(<span class="methodparam"><span class="type">media_node_id </span><span class="parameter">nodeID</span></span>,<br />                    <span class="methodparam"><span class="type">media_node* </span><span class="parameter">clonedNode</span></span>);</code><p>Given a node specified by <code class="parameter">node_id</code>,
<code class="methodname">GetNodeFor()</code> returns in <code class="parameter">clonedNode</code> a
<a class="link" href="TheMediaKit_DefinedTypes.html#media_node" title="media_node"><span class="type">media_node</span></a>
reference to a clone of the node. You can then use the
<code class="parameter">clonedNode</code> to query the node for available
inputs, outputs, and so forth.</p><p>Once your application has finished using the returned node (and it's been
stopped and disconnected), you should release it by calling
<a class="link" href="BMediaRoster.html#BMediaRoster_ReleaseNode" title="ReleaseNode()"><code class="methodname">ReleaseNode()</code></a>.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error cloning the node.</p></td></tr><tr><td><p><span class="term"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> errors.</span></p></td><td><p>Unable to get the list of live nodes.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetParameterWebFor"></a>GetParameterWebFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetParameterWebFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                            <span class="methodparam"><span class="type"><a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>** </span><span class="parameter">outWeb</span></span>);</code><p>Instantiates a
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>
that describes the internal layout of a
specific controllable node and stores a pointer to the
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a> in
<code class="parameter">outWeb</code>. You can then walk the various
<a class="link" href="BParameter.html" title="BParameter"><code class="classname">BParameter</code></a>s
within the web to figure out what there is to control, and to present a user interface to
the node's parameters. Delete the web pointed to by <code class="parameter">outWeb</code> when you're
done with it.</p><p>Note that the
<a class="link" href="BMediaRoster.html#BMediaRoster_StartControlPanel" title="StartControlPanel()"><code class="methodname">StartControlPanel()</code></a>
function provides an easy, painless way
to automatically present user interface for configuring nodes.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This function will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error obtaining the
<a class="link" href="BParameterWeb.html" title="BParameterWeb"><code class="classname">BParameterWeb</code></a>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The requested node is invalid.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetReadFileFormatListFor"></a><a id="BMediaRoster_GetWriteFileFormatListFor"></a>
GetReadFileFormatListFor(), GetWriteFileFormatListFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetReadFileFormatList</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">inNode</span></span>,<br />                               <span class="methodparam"><span class="type">media_file_format* </span><span class="parameter">outReadFormats</span></span>,<br />                               <span class="methodparam"><span class="type">int32 </span><span class="parameter">inReadCount</span></span>,<br />                               <span class="methodparam"><span class="type">int32* </span><span class="parameter">outReadCount</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetWriteFileFormatList</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">inNode</span></span>,<br />                                <span class="methodparam"><span class="type">media_file_format* </span><span class="parameter">outWriteFormats</span></span>,<br />                                <span class="methodparam"><span class="type">int32 </span><span class="parameter">inWriteCount</span></span>,<br />                                <span class="methodparam"><span class="type">int32* </span><span class="parameter">outWriteCount</span></span>);</code><p>These two functions return lists of file formats that the dormant node
described by <code class="parameter">inNode</code> can read or write.</p><p><code class="methodname">GetReadFileFormatList()</code> returns in the
array specified by <code class="parameter">outReadFormats</code> a list of file
formats the node can read. Specify in
<code class="parameter">inReadCount</code> the number of formats that can be
held by the <code class="parameter">outReadFormats</code> array. On exit,
<code class="parameter">outReadCount</code> indicates how many formats are
being returned in the array.</p><p><code class="methodname">GetWriteFileFormatList()</code> returns in
the array specified by <code class="parameter">outWriteFormats</code> a list of
file formats the node can write. Specify in
<code class="parameter">inWriteCount</code> the number of formats that can be
held by the <code class="parameter">outWriteFormats</code> array. On exit,
<code class="parameter">outWriteCount</code> indicates how many formats are
being returned in the array.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>The list was returned without error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p><code class="parameter">outReadFormats</code> or
<code class="parameter">outWriteFormats</code> is <code class="constant">NULL</code>.</p></td></tr><tr><td><p><span class="term"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> errors.</span></p></td><td><p>An error occurred communicating with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetRealtimeFlags"></a><a id="BMediaRoster_SetRealtimeFlags"></a>
GetRealtimeFlags(), SetRealtimeFlags()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetRealtimeFlags</span>(<span class="methodparam"><span class="type">uint32* </span><span class="parameter">outEnabled</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetRealtimeFlags</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">inEnabled</span></span>);</code><p><code class="methodname">GetRealtimeFlags()</code> returns flags that
the Media Server uses to determine whether or not memory needs to be locked
down. <code class="methodname">SetRealtimeFlags()</code> sets these flags, and
is generally only called by the Media preference application.</p><p>Any or all of these flags can be set, in combination.</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_MEDIA_REALTIME_ALLOCATOR</code></span></p></td><td><p> When set,
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_alloc" title="rtm_alloc(), rtm_realloc()"><code class="function">rtm_alloc()</code></a>
will return locked memory.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_REALTIME_AUDIO</code></span></p></td><td><p>Audio add-ons in the Media Server are locked in
memory, and should lock their thread stacks using
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_thread" title="media_realtime_init_thread()"><code class="function">media_realtime_init_thread()</code></a>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_REALTIME_VIDEO</code></span></p></td><td><p>Video add-ons are locked in memory, and should
lock their thread stacks using
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_thread" title="media_realtime_init_thread()"><code class="function">media_realtime_init_thread()</code></a>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_REALTIME_ANYKIND</code></span></p></td><td><p>All Media add-ons are locked in memory, and
should lock their thread stacks using
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_thread" title="media_realtime_init_thread()"><code class="function">media_realtime_init_thread()</code></a>.</p></td></tr></tbody></table><p>See the
<a class="link" href="BMediaNode_Overview.html" title="BMediaNode"><code class="classname">BMediaNode</code> overview</a>
for a discussion of realtime allocation and thread stack locking.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Unable to set or retrieve the realtime flags.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetStartLatencyFor"></a>GetStartLatencyFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetStartLatencyFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">timeSource</span></span>,<br />                            <span class="methodparam"><span class="type">bigtime_t* </span><span class="parameter">outLatency</span></span>);</code><p>Reports in <code class="parameter">outLatency</code> the maximum
latency found downstream from the time source specified by
<code class="parameter">timeSource</code>, given the current
connections.</p><p>If an error occurs, the value in
<code class="parameter">outLatency</code> is unreliable.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This function will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No errors.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Unable to get the latency.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetSystemTimeSource"></a>GetSystemTimeSource()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetSystemTimeSource</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">clonedTimeSource</span></span>);</code><p>This function returns, in <code class="parameter">clonedTimeSource</code>, a reference to a clone of the
system time source. The system time source is the fallback time source
used when no other source is available; its time is derived from the
<a class="link" href="TheKernelKit_Time.html#system_time" title="system_time()"><code class="function">system_time()</code></a>
real-time clock. As such, it's quite accurate, but has no
relevant relationship to the timing of the hardware devices being used
for media input and output. Thus it's not a good choice for a master
clock—but it's there if nothing else is available.</p><p>By default, new nodes are slaved to the system time source.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error cloning the node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The time source couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_GetTimeSource"></a><a id="BMediaRoster_MakeTimeSourceFor"></a>
GetTimeSource(), MakeTimeSourceFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetTimeSource</span>(<span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code><code class="methodsynopsis cpp"><span class="type"><a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>* </span><span class="methodname">MakeTimeSourceFor</span>(<span class="methodparam"><span class="type">media_node&amp; </span><span class="parameter">node</span></span>);</code><p><code class="methodname">GetTimeSource()</code> returns, in
<code class="parameter">outNode</code>, the preferred master clock to which
other nodes can be slaved. By slaving all nodes to a single master clock,
good synchronization can be ensured.</p><p>Typically, the preferred master clock will be the same node as the
default audio output (assuming that the audio output node is also a
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>,
which should be the case). The sound circuitry's <acronym class="acronym">DAC</acronym> is then
used as a timing reference. Although this may be less accurate than the
system clock (as defined by the global
<a class="link" href="TheKernelKit_Time.html#system_time" title="system_time()"><code class="function">system_time()</code></a>
function),
glitch-free audio performance is best ensured by using the audio output
to synchronize media operations.</p><p>By default, nodes are slaved to the system time source (see
<a class="link" href="BMediaRoster.html#BMediaRoster_GetSystemTimeSource" title="GetSystemTimeSource()"><code class="methodname">GetSystemTimeSource()</code></a>
above). Usually you'll want to use this function to
obtain a more accurate time source, then slave your nodes to it:</p><pre class="programlisting example cpp"><span class="type">media_node</span> <code class="varname">timeSource</code>;
<code class="varname">roster</code>-&gt;<code class="methodname">GetTimeSource</code>(&amp;<code class="varname">media_node</code>);
<code class="varname">roster</code>-&gt;<code class="methodname">SetTimeSourceFor</code>(<code class="varname">myNode</code>, <code class="varname">timeSource</code>.<code class="varname">node</code>);</pre><p>This will slave the previously-created node myNode to the preferred time
source.</p><p><code class="methodname">MakeTimeSourceFor()</code> returns a
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>
object corresponding to the
specified node's time source. This object can then be used to issue
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>
calls to determine and adjust timing issues (for instance, to
determine the current performance time). When you're done with the
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>,
you should call
<a class="link" href="BMediaRoster.html#BMediaRoster_ReleaseNode" title="ReleaseNode()"><code class="methodname">ReleaseNode()</code></a>
on it.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error locating the default input node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The default node couldn't be identified.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_InstantiateDormantNode"></a>InstantiateDormantNode()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">InstantiateDormantNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">inInfo</span></span>,<br />                                <span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">InstantiateDormantNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">inInfo</span></span>,<br />                                <span class="methodparam"><span class="type">media_node* </span><span class="parameter">outNode</span></span>,<br />                                <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>);</code>
</div><p>These functions instantiate a node from an add-on, given the information
specified in the <span class="type">dormant_node_info</span> structure.</p><p>The <code class="varname">addon</code> field should be filled out to contain the add-on ID of the
add-on from which the node should be instantiated, and the <code class="varname">flavor_id</code>
should be the flavor ID number the node should be instantiated to
process. Typically you'll use a function such as
<a class="link" href="BMediaRoster.html#BMediaRoster_GetDormantNodes" title="GetDormantNodes()"><code class="methodname">GetDormantNodes()</code></a>
to find a <span class="type">dormant_node_info</span> structure that describes a suitable node.</p><p>When you're done using the node, and have stopped and disconnected it,
you should always call
<a class="link" href="BMediaRoster.html#BMediaRoster_ReleaseNode" title="ReleaseNode()"><code class="methodname">ReleaseNode()</code></a>
to let the Media Server know you're
finished with it. This lets the Media Server track whether or not the
node's add-on can be unloaded, based on the number of applications still
using it.</p><p>The difference between these two functions is that the second form lets
you specify flags controlling how the node is instantiated. The
<code class="constant">B_FLAVOR_IS_GLOBAL</code> flag instantiates the node in the Media Add-on
Server's memory space, while the <code class="constant">B_FLAVOR_IS_LOCAL</code> flag instantiates the
node in your application's memory. Using <code class="constant">B_FLAVOR_IS_LOCAL</code> protects other
applications—not to mention the Media Server—from being
derailed if the node crashes. Whenever possible, you should instantiate
nodes locally. You should only use <code class="constant">B_FLAVOR_IS_GLOBAL</code> if you need the
node to stay around after your application exits.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error instantiating the node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be instantiated.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_MediaFlags"></a>MediaFlags()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type">ssize_t </span><span class="methodname">MediaFlags</span>(<span class="methodparam"><span class="type">media_flags </span><span class="parameter">flag</span></span>,<br />                          <span class="methodparam"><span class="type">void* </span><span class="parameter">buffer</span></span>,<br />                          <span class="methodparam"><span class="type">size_t </span><span class="parameter">bufferSize</span></span>);</code><p>Asks the Media Server about its support for specific features and
capabilities.</p><p>The specified buffer will be filled with the data indicating the
value of the specified <code class="parameter">flag</code>. If the buffer is
too small (as indicated by <code class="parameter">bufferSize</code>), only the
first <code class="parameter">bufferSize</code> bytes of the result data will
be stored in the buffer, but no error will occur.</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_MEDIA_FLAGS_VERSION</code></span></p></td><td><p>Returns the Media Kit version as an <span class="type">int32</span> value.</p></td></tr></tbody></table><p>If the result is negative, an error occurred, or the Media Server isn't
running.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_NodeIDFor"></a>NodeIDFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">media_node_id </span><span class="methodname">NodeIDFor</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">sourceOrDestinationPort</span></span>);</code><p>Given a source or destination port, this function returns the
corresponding node's ID number.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_PrerollNode"></a>PrerollNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">PrerollNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>);</code><p>Calling <code class="methodname">PrerollNode()</code> sends a preroll
message to the specified <code class="parameter">node</code>; the node's
<a class="link" href="BMediaNode.html#BMediaNode_Preroll" title="Preroll()"><code class="methodname">Preroll()</code></a>
hook function will be called. When that hook returns,
<code class="methodname">PrerollNode()</code> will also return. A node that's been prerolled should
respond very quickly to a
<a class="link" href="BMediaRoster.html#BMediaRoster_StartNode" title="StartNode(), StopNode()"><code class="methodname">StartNode()</code></a>
call, because the time-consuming setup operations should have been done already by the
<a class="link" href="BMediaNode.html#BMediaNode_Preroll" title="Preroll()"><code class="methodname">Preroll()</code></a>
hook.</p><p>While it's not mandatory for an application to call
<code class="methodname">PrerollNode()</code> before calling
<a class="link" href="BMediaRoster.html#BMediaRoster_StartNode" title="StartNode(), StopNode()"><code class="methodname">StartNode()</code></a>,
it's recommended, because doing so may improve
real-time performance once the node is started.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This function will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the set mode request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_RegisterNode"></a><a id="BMediaRoster_UnregisterNode"></a>
RegisterNode(), UnregisterNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">RegisterNode</span>(<span class="methodparam"><span class="type"><a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>* </span><span class="parameter">node</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">UnregisterNode</span>(<span class="methodparam"><span class="type"><a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>* </span><span class="parameter">node</span></span>);</code><p><code class="methodname">RegisterNode()</code> registers an object of a class derived from
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>
with the media roster and assigns it a node_id. This function should be
called once a <code class="classname">BMediaNode</code>-derived object is fully-constructed and before
any attempt is made to connect the node to some other participant in the
Media Server.</p><p><code class="methodname">RegisterNode()</code> is called automatically for nodes instantiated from
add-ons, but your application will have to call it for any nodes it
creates itself.</p><p>If you create your own subclass of
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>,
its constructor can call <code class="methodname">RegisterNode()</code> itself just before returning (it must be the last thing
the constructor does).</p><p><code class="methodname">UnregisterNode()</code> unregisters a node
from the Media Server. It's called automatically by the
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>
destructor, but it might be convenient to call it sometime before you
delete your node instance, depending on your implementation and
circumstances.</p><p>These functions are generally only used if you're creating your own node
class.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the seek request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>Invalid <a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>
specified.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_ReleaseNode"></a>ReleaseNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">ReleaseNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>);</code><p>Releases the specified node, which has previously been obtained by using
the <a class="link" href="BMediaRoster.html#BMediaRoster_InstantiateDormantNode" title="InstantiateDormantNode()"><code class="methodname">InstantiateDormantNode()</code></a>,
<a class="link" href="BMediaRoster.html#BMediaRoster_GetNodeFor" title="GetNodeFor()"><code class="methodname">GetNodeFor()</code></a>,
or default node functions (such as
<a class="link" href="BMediaRoster.html#BMediaRoster_GetVideoOutput"><code class="methodname">GetVideoOutput()</code></a> or
<a class="link" href="BMediaRoster.html#BMediaRoster_GetAudioMixer"><code class="methodname">GetAudioMixer()</code></a>).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error releasing the node.</p></td></tr><tr><td><p><span class="term"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> errors.</span></p></td><td><p>The node couldn't be released.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_RollNode"></a>RollNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">RollNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">startPerformanceTime</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">stopPerformanceTime</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atMediaTime</span><span class="initializer"> = -<span class="constant">B_INFINITE_TIMEOUT</span></span></span>);</code><p>Atomically queues a start and stop for the given node. The node will
start playing at the performance time indicated by <code class="parameter">startPerformanceTime</code>,
and will stop playing at the performance time indicated by
<code class="parameter">stopPerformanceTime</code>.</p><p>If the <code class="parameter">atMediaTime</code> argument is given, a seek to that media time is also
queued.</p><p>This function is especially useful for the offline rendering case (the
<code class="constant">B_OFFLINE</code> run mode). It lets you render a certain time range without
accidentally going too far; if you queue up a start and stop using
<a class="link" href="BMediaNode.html#BMediaNode_Start" title="Start()"><code class="methodname">Start()</code></a> and
<a class="link" href="BMediaNode.html#BMediaNode_Stop" title="Stop()"><code class="methodname">Stop()</code></a>,
the node may have already rendered past your desired stop time before your
<a class="link" href="BMediaNode.html#BMediaNode_Stop" title="Stop()"><code class="methodname">Stop()</code></a>
call occurs.
<a class="link" href="BMediaRoster.html#BMediaRoster_RollNode" title="RollNode()"><code class="methodname">RollNode()</code></a>
avoids that problem.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The node isn't valid.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_Roster"></a><a id="BMediaRoster_CurrentRoster"></a>
Roster(), CurrentRoster()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type"><span class="classname">BMediaRoster</span>* </span><span class="methodname">Roster</span>(<span class="methodparam"><span class="type">status_t* </span><span class="parameter">outError</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type"><span class="classname">BMediaRoster</span>* </span><span class="methodname">CurrentRoster</span>();</code><p><code class="methodname">Roster()</code> returns a pointer to the
default <code class="classname">BMediaRoster</code> instance, or creates the
<code class="classname">BMediaRoster</code> instance if it doesn't exist yet,
then returns a pointer to it. If you don't want to create the roster if it
doesn't already exist, use the <code class="methodname">CurrentRoster()</code>
function (it returns <code class="constant">NULL</code> if there's no
roster).</p><p>Since <code class="methodname">CurrentRoster()</code> doesn't create a
media roster, you obviously must use <code class="methodname">Roster()</code>
at least once in your application to create one.</p><p>These static member functions should be called by explicit scope,
and never by dereference; this is how you get the
<code class="classname">BMediaRoster</code> through which all other media
roster functions are called. For example:</p><pre class="programlisting example cpp"><span class="type"><code class="classname">BMediaRoster</code>*</span> <code class="varname">r</code> = <code class="classname">BMediaRoster</code>::<code class="methodname">Roster</code>();
<span class="type">status_t</span> <code class="varname">err</code> = <code class="varname">r</code>-&gt;<code class="methodname">GetFreeOutputsFor</code>(<code class="varname">some_node</code>, <code class="varname">some_array</code>, 3, &amp;<code class="varname">n</code>);</pre><p>On return, <code class="parameter">outError</code> is set to
<code class="constant">B_OK</code> if the default
<code class="classname">BMediaRoster</code> was successfully returned, or a
negative error code if something went wrong (for example, if the Media
Server isn't running). If <code class="parameter">outError</code> is
<code class="constant">NULL</code>, no error code is returned.</p><p>In any case, <code class="methodname">Roster()</code> returns
<code class="constant">NULL</code> if an error occurs.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SeekNode"></a>SeekNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SeekNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">newMediaTime</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atPerformanceTime</span><span class="initializer"> = 0</span></span>);</code><p>Sends the specified <code class="parameter">node</code> a request that
it change its playing location to the media time
<code class="parameter">newMediaTime</code> once the performance time
<code class="parameter">atPerformanceTime</code> is reached.</p><p>If the node isn't running, the seek request is processed immediately, and
the <code class="parameter">atPerformanceTime</code> argument is ignored.</p><p>The error returned by this function only indicates whether or not the
request was sent successfully; the node may later run into problems
trying to perform the seek operation.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>If the node is a time source, and you want to operate on the time
source aspect of the node (to seek all slaved nodes), you should call
<a class="link" href="BMediaRoster.html#BMediaRoster_SeekTimeSource" title="SeekTimeSource()"><code class="methodname">SeekTimeSource()</code></a>
instead.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the seek request.</p></td></tr><tr><td><p><span class="term">Other errors</span></p></td><td><p>Are node specific</p></td></tr></tbody></table><p>See also:
<a class="link" href="BMediaRoster.html#BMediaRoster_StartNode" title="StartNode(), StopNode()"><code class="methodname">StartNode()</code></a>,
<a class="link" href="BMediaRoster.html#BMediaRoster_StopNode"><code class="methodname">StopNode()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SeekTimeSource"></a>SeekTimeSource()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SeekTimeSource</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">timeSource</span></span>,<br />                        <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">newPerformanceTime</span></span>,<br />                        <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atRealTime</span></span>);</code><p>Sends the specified timeSource a request that it change the performance
time it outputs to its slaved nodes to the time <code class="parameter">newPerformanceTime</code> once
the performance time <code class="parameter">atRealTime</code> is reached.</p><p>If the <code class="parameter">timeSource</code> isn't running, the seek request is processed
immediately, and the atRealTime argument is ignored.</p><p>The error returned by this function only indicates whether or not the
request was sent successfully; the node may later run into problems
trying to perform the seek operation.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the seek request.</p></td></tr><tr><td><p><span class="term">Other errors</span></p></td><td><p>Are node specific</p></td></tr></tbody></table><p>See also:
<a class="link" href="BMediaRoster.html#BMediaRoster_StartTimeSource" title="StartTimeSource(), StopTimeSource()"><code class="methodname">StartTimeSource()</code></a>,
<a class="link" href="BMediaRoster.html#BMediaRoster_StopTimeSource"><code class="methodname">StopTimeSource()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetAudioInput"></a><a id="BMediaRoster_SetVideoInput"></a>
SetAudioInput(), SetVideoInput()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetAudioInput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">defaultNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetAudioInput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">defaultNodeInfo</span></span>);</code>
</div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetVideoInput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">defaultNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetVideoInput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">defaultNodeInfo</span></span>);</code>
</div><p>These functions set the preferred nodes for audio and video input. If the
specified node isn't capable of being the system default, an error will
be returned (for example, nodes defined by an application can't be the
system default—only nodes defined by Media Kit add-ons can be
system defaults).</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>In general, you shouldn't call these functions unless you're writing
software that reimplements the functionality of the BeOS Audio or Video
preference panels.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error setting the default input node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The default node couldn't be changed.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetAudioOutput"></a><a id="BMediaRoster_SetVideoOutput"></a>
SetAudioOutput(), SetVideoOutput()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetAudioOutput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">defaultNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetAudioOutput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">defaultNodeInfo</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetAudioOutput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_input&amp; </span><span class="parameter">inputToOutput</span></span>);</code>
</div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetVideoOutput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">defaultNode</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetVideoOutput</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">dormant_node_info&amp; </span><span class="parameter">defaultNodeInfo</span></span>);</code>
</div><p>These functions set the preferred nodes for audio and video output. If
the specified node isn't capable of being the system default, an error
will be returned (for example, nodes defined by an application can't be
the system default—only nodes defined by Media Kit add-ons can be
system defaults).</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>In general, you shouldn't call these functions unless you're writing
software that reimplements the functionality of the BeOS Audio or Video
preference panels.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error setting the default output node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The default node couldn't be changed.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetProducerRate"></a>SetProducerRate()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetProducerRate</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                         <span class="methodparam"><span class="type">int32 </span><span class="parameter">numerator</span></span>,<br />                         <span class="methodparam"><span class="type">int32 </span><span class="parameter">demominator</span></span>);</code><p>This function is called to tell the producer to resample the data rate by
the specified factor. Specifying a value of 1 (ie,
<code class="parameter">numerator</code>/<code class="parameter">denominator</code>
= 1) indicates that the data should be output at the same playback rate
that it comes into the node at. The format of the data should be
unchanged.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Nodes are not required to support this mechanism for controlling their
data rate, so this call may have no effect.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Returned by
<a class="link" href="BBufferProducer.html#BBufferProducer_SetPlayRate" title="SetPlayRate()"><code class="methodname">BBufferProducer::SetPlayRate()</code></a>.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetProducerRunModeDelay"></a>SetProducerRunModeDelay()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetProducerRunModeDelay</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                                 <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">delay</span></span>,<br />                                 <span class="methodparam"><span class="type"><a class="link" href="BMediaNode.html#Enums_run_mode" title="run_mode">BMediaNode::run_mode</a> </span><span class="parameter">mode</span><span class="initializer"> = <span class="constant">B_RECORDING</span></span></span>);</code><p>Sets the run mode for the given producer node to <code class="parameter">mode</code>. Also sets the
specified <code class="parameter">delay</code> to be added to each buffer sent by the producer node.
This function should only be called for <code class="constant">B_RECORDING</code> mode; it's provided
to compensate when you connect a node that's in recording mode to a node
that isn't.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The node is invalid.</p></td></tr><tr><td><p><span class="term">Port errors.</span></p></td><td><p>An error occurred communicating with the Media Server.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetRefFor"></a><a id="BMediaRoster_GetRefFor"></a>
SetRefFor(), GetRefFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetRefFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">fileInterface</span></span>,<br />                   <span class="methodparam"><span class="type">entry_ref&amp; </span><span class="parameter">file</span></span>,<br />                   <span class="methodparam"><span class="type">bool </span><span class="parameter">createAndTruncate</span></span>,<br />                   <span class="methodparam"><span class="type">bigtime_t* </span><span class="parameter">outDuration</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetRefFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">fileInterface</span></span>,<br />                   <span class="methodparam"><span class="type">entry_ref* </span><span class="parameter">outFile</span></span>,<br />                   <span class="methodparam"><span class="type"><a class="link" href="BMimeType.html" title="BMimeType"><code class="classname">BMimeType</code></a>* </span><span class="parameter">outMimeType</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p><code class="methodname">SetRefFor()</code> tells the
<a class="link" href="BFileInterface.html" title="BFileInterface"><code class="classname">BFileInterface</code></a>
<code class="parameter">fileInterface</code> to work on the file
whose <span class="type">entry_ref</span> is specified by <code class="parameter">file</code>.
If <code class="parameter">createAndTruncate</code> is <code class="constant">true</code>, any
previous file with that reference is deleted and the file will be
prepared for new output. If <code class="parameter">createAndTruncate</code> is
<code class="constant">false</code>, <code class="parameter">outDuration</code> will,
on return, contain the duration of the performance data found in the file.</p><p><code class="methodname">GetRefFor()</code> fills out the specified
<span class="type">entry_ref</span>, <code class="parameter">outFile</code>, to reference the
file with which the specified <code class="parameter">fileInterface</code> node is working. If
<code class="parameter">outMimeType</code> isn't <code class="constant">NULL</code>, it'll contain a
<a class="link" href="BMimeType.html" title="BMimeType"><code class="classname">BMimeType</code></a>
object describing the file's type, unless an error occurs.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The specified node doesn't exist, or isn't a file interface.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetRunModeNode"></a>SetRunModeNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetRunModeNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                        <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">delay</span></span>,<br />                        <span class="methodparam"><span class="type"><a class="link" href="BMediaNode.html#Enums_run_mode" title="run_mode">BMediaNode::run_mode</a> </span><span class="parameter">newMode</span></span>);</code><p>Sends the specified <code class="parameter">node</code> a request that it change its policy for handling
situations where it falls behind during real-time processing.</p><p>The error returned by this function only indicates whether or not the
request was sent successfully.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the set mode request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_NODE</code></span></p></td><td><p>The specified node is invalid.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SetTimeSourceFor"></a>SetTimeSourceFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetTimeSourceFor</span>(<span class="methodparam"><span class="type">media_node_id </span><span class="parameter">node</span></span>,<br />                          <span class="methodparam"><span class="type">media_node_id </span><span class="parameter">timeSource</span></span>);</code><p>Tells the specified <code class="parameter">node</code> to slave its
timing to <code class="parameter">timeSource</code>. Once this is
done, the node will receive its notion of the passage of time from
<code class="parameter">timeSource</code>. As such, it will pause whenever timeSource is stopped, and so
forth.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>By default, nodes are slaved to the system time source, so you only
need to call this function if you need to slave a node to a different
time source.</p></div></div></div><p>The node will take whatever precautions are necessary to remain faithful
to the notion of time presented by <code class="parameter">timeSource</code> without causing glitches in
the presentation of its media. For example, if a sound card node has a
<acronym class="acronym">DAC</acronym> that drifts from <code class="parameter">timeSource</code>, it might try to fix the problem by
varying the sampling rate slightly, or by dropping or doubling buffers
occasionally. This is why you should usually use the preferred time
source—rather than the system time source—as your master time
source. The preferred time source will usually be derived directly from
the <acronym class="acronym">DAC</acronym> being used to produce the media output.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> errors.</span></p></td><td><p>Unable to set the time source.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SniffRef"></a><a id="BMediaRoster_SniffRefFor"></a>
SniffRef(), SniffRefFor()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SniffRef</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref&amp; </span><span class="parameter">node</span></span>,<br />                  <span class="methodparam"><span class="type">uint64 </span><span class="parameter">requireNodeKinds</span></span>,<br />                  <span class="methodparam"><span class="type">dormant_node_info* </span><span class="parameter">outNode</span></span>,<br />                  <span class="methodparam"><span class="type"><a class="link" href="BMimeType.html" title="BMimeType"><code class="classname">BMimeType</code></a>* </span><span class="parameter">outMimeType</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SniffRefFor</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">fileInterface</span></span>,<br />                     <span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref&amp; </span><span class="parameter">node</span></span>,<br />                     <span class="methodparam"><span class="type">uint64 </span><span class="parameter">requireNodeKinds</span></span>,<br />                     <span class="methodparam"><span class="type">dormant_node_info* </span><span class="parameter">outNode</span></span>,<br />                     <span class="methodparam"><span class="type"><a class="link" href="BMimeType.html" title="BMimeType"><code class="classname">BMimeType</code></a>* </span><span class="parameter">outMimeType</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p><code class="methodname">SniffRef()</code> asks all
<a class="link" href="BMediaAddOn.html" title="BMediaAddOn"><code class="classname">BMediaAddOn</code></a>
instances that satisfy the
<code class="parameter">requireNodeKinds</code> restraint to identify the file. The <code class="parameter">requireNodeKinds</code>
argument should contain flags composited from the
<a class="link" href="TheMediaKit_Constants.html#Enums_node_kind" title="node_kind">node_kind</a>
constants.</p><p>The node that returns the greatest
<code class="parameter">outCapability</code> value will be chosen, and a
reference to it put in <code class="parameter">outNode</code>. The
<acronym class="acronym">MIME</acronym> type of the file will be put into
<code class="parameter">outMimeType</code>.</p><p>In simpler terms: <code class="methodname">SniffRef()</code> returns the node that can best handle the
media data in the specified file.</p><p><code class="methodname">SniffRefFor()</code>, on the other hand,
asks the specified <code class="parameter">fileInterface</code> node
to examine the file. If the node recognizes the file, the <acronym class="acronym">MIME</acronym> type of
the file is stored in the buffer <code class="parameter">outMimeType</code>, and the node's capability
to handle the file is returned in <code class="parameter">outCapability</code>.</p><p>If the node doesn't recognize the file, an error is returned. If the node
recognizes the file format but finds no recognizable data within the
file, <code class="parameter">outCapability</code> is set to 0.0 and no error is returned.</p><p>In either case, the higher the <code class="parameter">outCapability</code> value returned, the more
appropriate the node is for handling the media data in the file.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No errors.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The specified node is invalid, or isn't a file interface.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_StartControlPanel"></a>StartControlPanel()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartControlPanel</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">node</span></span>,<br />                           <span class="methodparam"><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">Messenger</code></a>* </span><span class="parameter">outMessenger</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p>Tells the specified node to start its custom control panel, which is
started outside your application. There's no way to tell when the user
has closed the control panel, other than by indirectly detecting possible
changes to the node, such as a renegotiation of the format of data being
output by the node.</p><p>If a <a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>
is provided as input to <code class="methodname">StartControlPanel()</code>,
the function returns in <code class="parameter">outMessenger</code> a
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">Messenger</code></a>
that can be used to communicate with the control panel.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>These functions will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error starting the control panel.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The specified node is invalid.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_StartNode"></a><a id="BMediaRoster_StopNode"></a>
StartNode(), StopNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">node</span></span>,<br />                   <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atPerformanceTime</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">node</span></span>,<br />                   <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atPerformanceTime</span></span>,<br />                   <span class="methodparam"><span class="type">bool </span><span class="parameter">immediate</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code><p><code class="methodname">StartNode()</code> sends the specified node a request to start streaming data at
the performance time specified by the <code class="parameter">atPerformanceTime</code> argument,
according to that node's time source.</p><p>By default, nodes are in a stopped state upon creation, so you have to
call <code class="methodname">StartNode()</code> once you have a reference to it before anything will
happen. Starting a node that's already running has no effect.</p><p><code class="methodname">StopNode()</code> sends node a request to
stop streaming data once the specified performance time
<code class="parameter">atPerformanceTime</code> is reached, according to that
node's time source. Stopping a node that's already stopped has no effect.
If <code class="parameter">immediate</code> is <code class="constant">true</code>,
the node is instructed to stop immediately and the
<code class="parameter">atPerformanceTime</code> argument is ignored; if
<code class="parameter">immediate</code> is <code class="constant">false</code>, the
node is stopped at the specified performance time.</p><p>In either case, the requested change will occur at the time specified by
<code class="parameter">atPerformanceTime</code>.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>If the node is a time source, and you want to operate on the time
source aspect of the node (to start or stop all slaved nodes), you should
call
<a class="link" href="BMediaRoster.html#BMediaRoster_SeekTimeSource" title="SeekTimeSource()"><code class="methodname">SeekTimeSource()</code></a>
instead.</p></div></div></div><p>The error returned by these functions only indicates whether or not the
request was sent successfully; the node may later run into problems
trying to start or stop its media and you won't know it based on the
result of these functions.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p><code class="methodname">StopNode()</code> will deadlock if called from a node's control thread or
while the control thread is blocked.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the start or stop request.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Are node specific.</p></td></tr></tbody></table><p>See also:
<a class="link" href="BMediaRoster.html#BMediaRoster_SeekNode" title="SeekNode()"><code class="methodname">SeekNode()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_StartTimeSource"></a><a id="BMediaRoster_StopTimeSource"></a>
StartTimeSource(), StopTimeSource()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartTimeSource</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">timeSource</span></span>,<br />                         <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atRealTime</span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StopTimeSource</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">timeSource</span></span>,<br />                        <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atRealTime</span></span>,<br />                        <span class="methodparam"><span class="type">bool </span><span class="parameter">immediate</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code><p><code class="methodname">StartTimeSource()</code> sends the
specified <code class="parameter">timeSource</code> a request to start
running at the real time specified by the <code class="parameter">atRealTime</code> argument.</p><p><code class="methodname">StopTimeSource()</code> sends node a request
to stop the specified <code class="parameter">timeSource</code> once the
specified real time <code class="parameter">atRealTime</code> is reached.
Stopping a time source that's already stopped has no effect. If
<code class="parameter">immediate</code> is <code class="constant">true</code>, the
time source is instructed to stop immediately and the
<code class="parameter">atRealTime</code> argument is ignored; if
<code class="parameter">immediate</code> is <code class="constant">false</code>, the
time source is stopped at the specified real time.</p><p>In either case, the requested change will occur at the time specified by
<code class="parameter">atRealTime</code>.</p><p>The error returned by these functions only indicates whether or not the
request was sent successfully; the node may later run into problems
trying to start or stop and you won't know it based on the result of
these functions.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error sending the start or stop request.</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>Are node specific.</p></td></tr></tbody></table><p>See also:
<a class="link" href="BMediaRoster.html#BMediaRoster_SeekTimeSource" title="SeekTimeSource()"><code class="methodname">SeekTimeSource()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_StartWatching"></a><a id="BMediaRoster_StopWatching"></a>
StartWatching(), StopWatching()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>,<br />                       <span class="methodparam"><span class="type">int32 </span><span class="parameter">notificationType</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StartWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>,<br />                       <span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                       <span class="methodparam"><span class="type">int32 </span><span class="parameter">notificationType</span></span>);</code>
</div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StopWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StopWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>,<br />                      <span class="methodparam"><span class="type">int32 </span><span class="parameter">notificationType</span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">StopWatching</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>&amp; </span><span class="parameter">notifyHandler</span></span>,<br />                      <span class="methodparam"><span class="modifier">const </span><span class="type">media_node&amp; </span><span class="parameter">node</span></span>,<br />                      <span class="methodparam"><span class="type">int32 </span><span class="parameter">notificationType</span></span>);</code>
</div><p><code class="methodname">StartWatching()</code> registers the specified
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> or
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>
as a recipient of notification messages from the Media Server.
<code class="methodname">StopWatching()</code>
cancels this registration so that no further notifications will be sent.</p><p>If you're only interested in a particular notification type, you can
specify that code in the <code class="parameter">notificationType</code> argument. If you don't specify
a notification type, <code class="constant">B_MEDIA_WILDCARD</code> is assumed; this matches all
notification types. You can also specify that you want to watch a
specific node; if you don't specify a node, you'll receive notifications
for all nodes.</p><p>Events are sent to registered
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>s and
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>s
when certain events
happen, such as nodes being created or deleted, or connections being made
or broken.</p><p>See
"<a class="link" href="TheMediaKit_MessageConstants.html" title="Message Constants">Notification Messages</a>"
for a list of the notifications you can
receive, and the formats of the corresponding messages.</p><p>Although the Media Server will automatically cancel notifications to
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>s
and <a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>s
that go away without explicitly calling
<code class="methodname">StopWatching()</code>, this detection is expensive and may briefly interrupt the
media system, so you should always call <code class="methodname">StopWatching()</code> before allowing a
<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a> or
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>
to go away.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error cloning the node.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code></span></p></td><td><p>The requested node couldn't be cloned.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_SyncToNode"></a>SyncToNode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SyncToNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_node </span><span class="parameter">node</span></span>,<br />                    <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atPerformanceTime</span></span>,<br />                    <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">timeout</span><span class="initializer"> = <span class="constant">B_INFINITE_TIMEOUT</span></span></span>);</code><p>If you want to detect the arrival of a specific performance time on
a given node, you can do that by calling
<code class="methodname">SyncToNode()</code>. Specify the node you want to
monitor in <code class="parameter">node</code>, and the time you want to be
notified of in <code class="parameter">atPerformanceTime</code>. You can,
optionally, specify a <code class="parameter">timeout</code>; if the sync
hasn't occurred in <code class="parameter">timeout</code> microseconds, the
request will time out.</p><p>This function doesn't return until either the specified performance time
arrives, or the sync operation times out.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>All's well.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_MEDIA_BAD_NODE</code></span></p></td><td><p>The specified node is invalid.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TIMED_OUT</code></span></p></td><td><p>The request timed out.</p></td></tr><tr><td><p><span class="term">Port errors.</span></p></td><td><p>An error occurred communicating with the Media Server.</p></td></tr></tbody></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_Constants"></a>Constants</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaRoster_connect_flags"></a>connect_flags</h4></div></div></div><p>Declared in: <code class="filename">media/MediaRoster.h</code></p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_CONNECT_MUTED</code></span></p></td><td><p>The connection should be muted on creation.</p></td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMediaNode.html">BMediaNode</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BMediaTheme.html">BMediaTheme</a> </div><div id="footerB"><div id="footerBL"><a href="BMediaNode.html" title="BMediaNode"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BMediaTheme.html" title="BMediaTheme"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink