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

325 lines
57 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="BMediaFormats.html" title="BMediaFormats" /><link rel="next" href="BMediaRoster.html" title="BMediaRoster" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMediaFormats.html" title="BMediaFormats"><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="BMediaRoster.html" title="BMediaRoster"><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="BMediaFormats.html">BMediaFormats</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BMediaRoster.html">BMediaRoster</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="BMediaNode"></a>BMediaNode</h2></div></div></div><a id="id1146238" 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/MediaNode.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="BMediaNode_Overview.html" title="BMediaNode">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BMediaNode.html#BMediaNode_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BMediaNode.html#BMediaNode_MemberFunctions">Member Functions</a></span></li><li><span class="section"><a href="BMediaNode.html#BMediaNode_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="BMediaNode_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="BMediaNode_Constructor"></a>BMediaNode()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="constructorsynopsis cpp"><span class="modifier">explicit </span><span class="methodname">BMediaNode</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span></span>);</code><p>Call this from your derived node's constructor.</p><p>The node is created with a reference count of 1; the count is incremented
each time the
<a class="link" href="BMediaNode.html#BMediaNode_Acquire" title="Acquire(), Release()"><code class="methodname">Acquire()</code></a>
call is issued, and decremented each time
<a class="link" href="BMediaNode.html#BMediaNode_Release"><code class="methodname">Release()</code></a>
is called. When the reference count becomes zero, the node is deleted.</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="BMediaNode_Destructor"></a>~BMediaNode()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">~BMediaNode</span>();</code><p>You may never delete a <code class="classname">BMediaNode</code> because you don't know for certain when
the Media Server is done with it. Instead, the Media Server maintains a
reference count for the node, and when it is no longer in use, the node
will be deleted automatically.</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="BMediaNode_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="BMediaNode_Acquire"></a><a id="BMediaNode_Release"></a>
Acquire(), Release()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type"><span class="classname">BMediaNode</span>* </span><span class="methodname">Acquire</span>();</code><code class="methodsynopsis cpp"><span class="type"><span class="classname">BMediaNode</span>* </span><span class="methodname">Release</span>();</code><p><code class="methodname">Acquire()</code> returns a pointer to the
node, after incrementing the node's reference count.</p><p><code class="methodname">Release()</code> releases the node by
decrementing its reference count. If the count reaches zero, the node
is deleted and <code class="constant">NULL</code> is returned; otherwise,
a pointer to the node is returned.</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>Although you usually can't call node member functions directly from
within an application, you can call <code class="methodname">Acquire()</code>
and <code class="methodname">Release()</code> directly if
the node is subclassed within the application itself (rather than in an
add-on).</p></div></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="BMediaNode_AddNodeKind"></a>AddNodeKind()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">AddNodeKind</span>(<span class="methodparam"><span class="type">uint64 </span><span class="parameter">kind</span></span>);</code><p>Adds a kind to the set of kinds supported by the node. This lets the
system know what types of node interfaces are supported by the node's
implementation. Possible values include <code class="constant">B_BUFFER_PRODUCER</code> (which
indicates that the node implements the
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>
protocol) and <code class="constant">B_PHYSICAL_INPUT</code> (which indicates that the node implements a physical
input, such as a sound digitizing input device). For a complete list of
kind values, see
<a class="link" href="TheMediaKit_Constants.html#Enums_node_kind" title="node_kind"><span class="type">node_kind</span></a>.</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 don't need to call this function. The base system
classes call <code class="methodname">AddNodeKind()</code> automatically
to set up the node type flags; for example, a
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>
automatically calls
<span class="code"><code class="methodname">AddNodeKind</code>(<code class="constant">B_BUFFER_PRODUCER</code>)</span>.
The only time it's necessary go call
<code class="methodname">AddNodeKind()</code> is if the node you're implementing is a physical device or
a mixer, in which case you need to add the <code class="constant">B_PHYSICAL_INPUT</code>,
<code class="constant">B_PHYSICAL_OUTPUT</code>, or <code class="constant">B_SYSTEM_MIXER</code> flag.</p></div></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="BMediaNode_AddOn"></a>AddOn()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type"><span class="classname">BMediaAddOn</span>* </span><span class="methodname">AddOn</span>(<span class="methodparam"><span class="type">int32* </span><span class="parameter">outInternalID</span></span>) <span class="modifier">const = 0</span>;</code><p>Implement this function to return a pointer to the
<a class="link" href="BMediaAddOn.html" title="BMediaAddOn"><code class="classname">BMediaAddOn</code></a> that
instantiated the node. If the node lives in an application (rather than
in an add-on), return <code class="constant">NULL</code>. If the node is in
an add-on, <code class="parameter">outInternalID</code>
should be changed to contain the internal ID number of the node within
the add-on.</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="BMediaNode_AddTimer"></a><a id="BMediaNode_TimerExpired"></a>
AddTimer(), TimerExpired()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">AddTimer</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">toPerformanceTime</span></span>,<br />                          <span class="methodparam"><span class="type">int32 </span><span class="parameter">cookie</span></span>);</code><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">TimerExpired</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">notifyPoint</span></span>,<br />                  <span class="methodparam"><span class="type">int32 </span><span class="parameter">cookie</span></span>,<br />                  <span class="methodparam"><span class="type">status_t </span><span class="parameter">error</span><span class="initializer"> = <span class="constant">B_OK</span></span></span>);</code><p>Your node should implement the <code class="methodname">AddTimer()</code>
function to remember the <code class="parameter">cookie</code>
and time given. When the time <code class="parameter">toPerformanceTime</code> is reached, your node
should call <code class="methodname">TimerExpired()</code> with the
corresponding <code class="parameter">cookie</code> value, passing
the recorded <code class="parameter">toPerformanceTime</code> value as
the <code class="parameter">notifyPoint</code> argument. This
will, in turn, cause the
<a class="link" href="BMediaRoster.html#BMediaRoster_SyncToNode" title="SyncToNode()"><code class="methodname">BMediaRoster::SyncToNode()</code></a>
call that instigated the timer to return to the caller.</p><p>Your implementation of <code class="methodname">AddTimer()</code>
should return <code class="constant">B_OK</code> if all is well;
otherwise it should return an appropriate error code.</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="BMediaNode_ControlPort"></a>ControlPort()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">port_id </span><span class="methodname">ControlPort</span>() <span class="modifier"> const = 0</span>;</code><p>Returns the <span class="type"></span>port_id of the port to which the node listens for requests.
Your node must implement this to return a valid Kernel Kit port.</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="BMediaNode_DeleteHook"></a>DeleteHook()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">DeleteHook</span>(<span class="methodparam"><span class="type"><span class="classname">BMediaNode</span>* </span><span class="parameter">node</span></span>);</code><p>The <code class="methodname">DeleteHook()</code> function is called
to delete the <code class="classname">BMediaNode</code> object. You
may augment this if you need to perform additional work before the node
is deleted, but you should always either include the line:</p><pre class="programlisting example cpp">delete this;</pre><p>or you should call through to the inherited form of the function. Return
<code class="constant">B_OK</code> if the node was deleted successfully, otherwise return an
appropriate error code.</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="BMediaNode_GetNodeAttributes"></a>GetNodeAttributes()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">GetNodeAttributes</span>(<span class="methodparam"><span class="type">media_node_attribute* </span><span class="parameter">outAttributes</span></span>,<br />                                   <span class="methodparam"><span class="type">size_t </span><span class="parameter">inMaxCount</span></span>);</code><p>Implement this function to fill the <code class="parameter">outAttributes</code>
array (which has room for <code class="parameter">inMaxCount</code> attributes) with
your node's attributes.</p><p>Return <code class="constant">B_OK</code> if all is well, or return an
appropriate error code.</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="BMediaNode_HandleBadMessage"></a>HandleBadMessage()</h4></div></div></div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">HandleBadMessage</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">message</span></span>,<br />                      <span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">data</span></span>,<br />                      <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><p>If your node receives a message that neither the node, nor any interface
from which the node is derived, understands the message, pass the message
along to this function, which will work magic to deal with the problem
one way or another. All arguments received by the
<a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">HandleMessage()</code></a>
function should be passed directly through to
<code class="methodname">HandleBadMessage()</code>.</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="BMediaNode_HandleMessage"></a>HandleMessage()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">HandleMessage</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">message</span></span>,<br />                               <span class="methodparam"><span class="modifier">const </span><span class="type">void* </span><span class="parameter">data</span></span>,<br />                               <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><p>Given a message received on the control port, this function dispatches
the message to the appropriate <code class="classname">BMediaNode</code> hook function. If the message
doesn't correspond to a hook function, <code class="constant">B_ERROR</code> is returned.</p><p>When you implement a media node of your own (derived from
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>,
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>,
etc), you always need to call through to
<code class="methodname">BMediaNode::HandleMessage()</code> from your node's implementation of
<code class="methodname">HandleMessage()</code>. This is crucial, to be sure that every ancestor of your
node gets to look at the message and attempt to process it.</p><p>For example, if your node inherits from both
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a> and
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>,
you should call
<a class="link" href="BBufferProducer.html#BBufferProducer_HandleMessage" title="HandleMessage()"><code class="methodname">BBufferProducer::HandleMessage()</code></a> and
<a class="link" href="BBufferConsumer.html#BBufferConsumer_HandleMessage" title="HandleMessage()"><code class="methodname">BBufferConsumer::HandleMessage()</code></a>,
<code class="methodname">then BMediaNode::HandleMessage()</code>, like
this:</p><pre class="programlisting example cpp">virtual <span class="type">status_t</span> <code class="classname">MyBufferProducerConsumer</code>::<code class="methodname">HandleMessage</code>(<span class="type">int32</span> <code class="parameter">message</code>,
<span class="type">const void*</span> <code class="parameter">data</code>, <span class="type">size_t</span> <code class="parameter">size</code>) {
if (<code class="parameter">message</code> == <code class="constant">SOME_THING_I_DO</code>) {
<code class="methodname">DoWhatever</code>();
}
else if (<code class="classname">BBufferConsumer</code>::<code class="methodname">HandleMessage</code>(<code class="parameter">message</code>, <code class="parameter">data</code>, <code class="parameter">size</code>) &amp;&amp;
<code class="classname">BBufferProducer</code>::<code class="methodname">HandleMessage</code>(<code class="parameter">message</code>, <code class="parameter">data</code>, <code class="parameter">size</code>) &amp;&amp;
<code class="classname">BMediaNode</code>::<code class="methodname">HandleMessage</code>(<code class="parameter">message</code>, <code class="parameter">data</code>, <code class="parameter">size</code>)) {
<code class="classname">BMediaNode</code>::<code class="methodname">HandleBadMessage</code>(<code class="parameter">message</code>, <code class="parameter">data</code>, <code class="parameter">size</code>);
}
}</pre><p>Note that
<a class="link" href="BMediaNode.html#BMediaNode_HandleBadMessage" title="HandleBadMessage()"><code class="methodname">BMediaNode::HandleBadMessage()</code></a>
is called if none of the
<code class="methodname">HandleMessage()</code> implementations accept the message.</p><p>Values of message between 0x60000000 and 0x7FFFFFFF are available for use
by applications. Values below 0x60000000 are reserved for use by the
Media Kit, and typically correspond to specific virtual hook functions
within your node. If you can show just cause for needing to know the
message value for a particular hook, you can try emailing
devsupport@be.com and see if we agree with you, in which case we may
share that information.</p><p>Don't reverse-engineer the message values; if you really need to know,
ask us. Otherwise, we won't know that a particular message code number
shouldn't be changed. In general, it's a bad idea to rely on specific
values, although there may be cases in which it's necessary.</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 message was dispatched.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code></span></p></td><td><p>The message couldn't be dispatched, possibly because it
doesn't correspond to a hook function.</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="BMediaNode_ID"></a>ID()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">media_node_id </span><span class="methodname">ID</span>() <span class="modifier">const</span>;</code><p>Returns the
<a class="link" href="TheMediaKit_DefinedTypes.html#media_node_id" title="media_node_id"><span class="type">media_node_id</span></a>
assigned to the node by the Media Server. The
result is 0 if the node hasn't been registered yet, and negative if an
error occurred while attempting to register the node.</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="BMediaNode_Kinds"></a>Kinds()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">uint64 </span><span class="methodname">Kinds</span>() <span class="modifier">const</span>;</code><p>Returns a bit mask indicating what interfaces the node implements. See
<a class="link" href="TheMediaKit_Constants.html#Enums_node_kind" title="node_kind">node_kind</a> for a list of valid
interface kinds.</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="BMediaNode_Name"></a>Name()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">const </span><span class="type">char* </span><span class="methodname">Name</span>() <span class="modifier">const</span>;</code><p>Returns a human-readable string specifying the node's name. This pointer
is only valid until you
<a class="link" href="BMediaNode.html#BMediaNode_Release"><code class="methodname">Release()</code></a>
the node; after that, the pointer may point into empty space.</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="BMediaNode_NewChangeTag"></a>NewChangeTag()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type">int32 </span><span class="methodname">NewChangeTag</span>();</code><p>This function, intended primarily for use by
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>
nodes, creates and returns a new change tag value.</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="BMediaNode_Node"></a>Node()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">media_node </span><span class="methodname">Node</span>() <span class="modifier">const</span>;</code><p>Returns the
<a class="link" href="TheMediaKit_DefinedTypes.html#media_node" title="media_node"><span class="type">media_node</span></a>
structure that will be used by an application when
accessing this node via the media roster.</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="BMediaNode_NodeRegistered"></a>NodeRegistered()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">NodeRegistered</span>();</code><p>The Media Server calls this hook function after the node has been
registered.</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="BMediaNode_NodeStopped"></a>NodeStopped()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">NodeStopped</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">whenPerformanceTime</span></span>) <span class="modifier">const</span>;</code><p>When you've finished handling a stop request (buffers will no longer be
flowing), call this function. If anyone is listening for stop
notifications from you, they'll be notified. The <code class="parameter">whenPerformanceTime</code>
argument should be the performance time of the stop command that was
handled.</p><p>Anyone listening for node stop messages will be notified; this lets
applications running in offline (rendering) mode know when the node has
actually completed its work.</p><p>If your node is a
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>,
downstream consumers will be notified
that your node stopped (automatically, no less) through the
<span class="code"><code class="classname">BBufferConsumer</code>::<code class="methodname">ProducerDataStatus</code>(<code class="constant">B_PRODUCER_STOPPED</code>)</span>
call. This lets offline rendering nodes know when each of their inputs have
no more data to send for the current roll.</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 is especially important for nodes that can be run
in <code class="constant">B_OFFLINE</code> mode.</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 communicate with the Media Server, or an
error occurred communicating with other 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="BMediaNode_Preroll"></a>Preroll()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">void </span><span class="methodname">Preroll</span>();</code><p>This hook function may be called before your node receives a
<a class="link" href="BMediaNode.html#BMediaNode_Start" title="Start()"><code class="methodname">Start()</code></a>
message if the application using the node calls
<a class="link" href="BMediaRoster.html#BMediaRoster_PrerollNode" title="PrerollNode()"><code class="methodname">BMediaRoster::PrerollNode()</code></a>.
This gives the node a chance to prepare the
media so that when the media is started, the response is as fast as
possible.</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="BMediaNode_ReportError"></a>ReportError()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">ReportError</span>(<span class="methodparam"><span class="type">node_error </span><span class="parameter">whichError</span></span>,<br />                     <span class="methodparam"><span class="modifier">const </span><span class="type"><span class="classname">BMessage</span>* </span><span class="parameter">info</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p>Transmits the error code specified by <code class="parameter">whichError</code> to anyone that's
receiving notifications from this node (see
<a class="link" href="BMediaRoster.html#BMediaRoster_StartWatching" title="StartWatching(), StopWatching()"><code class="methodname">BMediaRoster::StartWatching()</code></a>
and <a class="link" href="BMediaRoster.html#BMediaRoster_StopWatching"><code class="methodname">BMediaRoster::StopWatching()</code></a>
on ). If <code class="parameter">info</code> isn't <code class="constant">NULL</code>, it's used as
a model message for the error notification message.</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 error report was sent without 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>The message couldn't be sent.</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="BMediaNode_RequestCompleted"></a>RequestCompleted()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">RequestCompleted</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">media_request_info&amp; </span><span class="parameter">info</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><p>This function is called whenever a request issued by the node is
completed. The <code class="parameter">info</code> structure describes the results
of the request.</p><p>The <code class="varname">change_tag</code> field in the
<code class="parameter">info</code> structure identifies the request that has
been completed; this is the same value passed into the function that
initiated the request.</p><p>Return <code class="constant">B_OK</code> if you're happy, otherwise return
an appropriate error code.</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="BMediaNode_RunMode"></a><a id="BMediaNode_SetRunMode"></a>
RunMode(), SetRunMode()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="type">run_mode </span><span class="methodname">RunMode</span>() <span class="modifier">const</span>;</code><p><code class="methodname">RunMode()</code> returns the node's current
<a class="link" href="BMediaNode.html#Enums_run_mode" title="run_mode">run_mode</a>
setting.</p><p>The <code class="methodname">SetRunMode()</code> hook function is called
when someone requests that your node's run mode be changed.</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="BMediaNode_Seek"></a>Seek()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Seek</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">mediaTime</span></span>,<br />                  <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">performanceTime</span></span>);</code><p>This hook function is called when a node is asked to seek to the
specified <code class="parameter">mediaTime</code> by a call to the
<a class="link" href="BMediaRoster.html" title="BMediaRoster"><code class="classname">BMediaRoster</code></a>.</p><p>The specified <code class="parameter">performanceTime</code>, the time at
which the node should begin the seek operation, may be in the future.</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>Your node is required to queue at least one each of start, stop, and
seek requests, so that applications can establish, for example, both the
start and stop time without having to monitor your node's progress. The
actual size of these three queues is up to you. When the specified time
arrives, the request should be filled.</p></div></div></div><p>A <code class="parameter">mediaTime</code> value of 0 indicates the
beginning of the media data.</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="BMediaNode_SetTimeSource"></a><a id="BMediaNode_TimeSource"></a>
SetTimeSource(), TimeSource()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">SetTimeSource</span>(<span class="methodparam"><span class="type"><span class="classname">BTimeSource</span>* </span><span class="parameter">timeSource</span></span>);</code><code class="methodsynopsis cpp"><span class="type"><span class="classname">BTimeSource</span>* </span><span class="methodname">TimeSource</span>() <span class="modifier">const</span>;</code><p>The <code class="methodname">SetTimeSource()</code> hook function
is called when someone has requested
that the node be slaved to a new time source. Augment this function to
make whatever adjustments you need to make to operate at the new time
scale.</p><p><code class="methodname">TimeSource()</code> returns a pointer to the
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>
to which the node is
currently slaved. If no time source has been explicitly requested, the
system time source is in use, and that's what gets returned.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>The
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>
object returned by <code class="methodname">TimeSource()</code> is only valid
until the next call to
<a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">HandleMessage()</code></a>
on that object. Therefore, if your node runs more than one thread, you need
to serialize calls to <code class="methodname">TimeSource()</code> (as
well as usage of the returned objects) with calls to
<a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">HandleMessage()</code></a>
This isn't a problem if you follow the recommended policy of running a
single thread that monitors the service port with
<a class="link" href="TheKernelKit_Ports.html#read_port_etc"><code class="function">read_port_etc()</code></a>
and calls
<a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">HandleMessage()</code></a>
only when a message is actually received.</p></div></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="BMediaNode_Start"></a>Start()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Start</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">performanceTime</span></span>);</code><p>This hook function is called when a node is started by a call to the
<a class="link" href="BMediaRoster.html" title="BMediaRoster"><code class="classname">BMediaRoster</code></a>.</p><p>The specified <code class="parameter">performanceTime</code>, the time
at which the node should start running, may be in the future.</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>Your node is required to queue at least one each of start, stop, and
seek requests, so that applications can establish, for example, both the
start and stop time without having to monitor your node's progress. The
actual size of these three queues is up to you. When the specified time
arrives, the request should be filled.</p></div></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="BMediaNode_Stop"></a>Stop()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">Stop</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">performanceTime</span></span>,<br />                  <span class="methodparam"><span class="type">bool </span><span class="parameter">immediate</span></span>);</code><p>This hook function is called when a node is stopped by a call to the
<a class="link" href="BMediaRoster.html" title="BMediaRoster"><code class="classname">BMediaRoster</code></a>.</p><p>The specified <code class="parameter">performanceTime</code>, the time at
which the node should stop, may be in the future.</p><p>If <code class="parameter">immediate</code> is <code class="constant">true</code>,
your node should ignore the <code class="parameter">performanceTime</code> value
and synchronously stop performance. When <code class="methodname">Stop()</code>
returns, you're promising not to write into any
<a class="link" href="BBuffer.html" title="BBuffer"><code class="classname">BBuffer</code></a>s
you may have received from your downstream
consumers, and you promise not to send any more buffers until
<a class="link" href="BMediaNode.html#BMediaNode_Start" title="Start()"><code class="methodname">Start()</code></a>
is called 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>Your node is required to queue at least one each of start, stop, and
seek requests, so that applications can establish, for example, both the
start and stop time without having to monitor your node's progress. The
actual size of these three queues is up to you. When the specified time
arrives, the request should be filled.</p></div></div></div><p>Nodes must recycle all buffers they may be holding onto when they're
stopped.</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="BMediaNode_TimeWarp"></a>TimeWarp()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">TimeWarp</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">atRealTime</span></span>,<br />                      <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">newPerformanceTime</span></span>);</code><p>This hook function is called when the time source to which the node
is slaved is repositioned (via a seek operation) such that there will be a
sudden jump in the performance time progression as seen by the node. The
<code class="parameter">newPerformanceTime</code> argument indicates the new
performance time; the change should occur at the real time specified by the
<code class="parameter">atRealTime</code> argument.</p><p>The node should respond to this call by preparing for this change, so a
serious stutter, failure, or acceleration in performance doesn't occur.
Appropriate measures should be taken to minimize the impact on the
performance quality; for example, a segment of the sound could be looped
or skipped smoothly.</p><p>Your implementation of <code class="methodname">TimeWarp()</code> should call through to
<code class="methodname">BMediaNode::TimeWarp()</code>
as well as all other inherited forms of <code class="methodname">TimeWarp()</code>.</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="BMediaNode_WaitForMessage"></a>WaitForMessage()</h4></div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="subtitle">protected</h5></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">WaitForMessage</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">waitUntil</span></span>,<br />                        <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span><span class="initializer"> = 0</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><p>This function waits until either real time specified by
<code class="parameter">waitUntil</code> or a
message is received on the control port.. The <code class="parameter">flags</code> are currently unused
and should be 0.</p><p>When a message is received, the appropriate
<a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">HandleMessage()</code></a>
calls are made given the class derivation of the node:</p><ul class="itemizedlist"><li><p><a class="link" href="BMediaNode.html#BMediaNode_HandleMessage" title="HandleMessage()"><code class="methodname">BMediaNode::HandleMessage()</code></a>
is always called first.</p></li><li><p>If the node is derived from
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a>,
and the message hasn't been handled yet,
<a class="link" href="BBufferProducer.html#BBufferProducer_HandleMessage" title="HandleMessage()"><code class="methodname">BBufferProducer::HandleMessage()</code></a>
is called.</p></li><li><p>If the node is derived from
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>,
and the message hasn't been handled yet,
<a class="link" href="BBufferConsumer.html#BBufferConsumer_HandleMessage" title="HandleMessage()"><code class="methodname">BBufferConsumer::HandleMessage()</code></a>
is called.</p></li><li><p>If the node is derived from
<a class="link" href="BFileInterface.html" title="BFileInterface"><code class="classname">BFileInterface</code></a>,
and the message hasn't been handled yet,
<a class="link" href="BFileInterface.html#BFileInterface_HandleMessage" title="HandleMessage()"><code class="methodname">BFileInterface::HandleMessage()</code></a>
is called.</p></li><li><p>If the node is derived from
<a class="link" href="BControllable.html" title="BControllable"><code class="classname">BControllable</code></a>,
and the message hasn't been handled yet,
<a class="link" href="BControllable.html#BControllable_HandleMessage" title="HandleMessage()"><code class="methodname">BControllable::HandleMessage()</code></a>
is called.</p></li><li><p>If the node is derived from
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>,
and the message hasn't been handled yet,
<a class="link" href="BTimeSource.html#BTimeSource_HandleMessage" title="HandleMessage()"><code class="methodname">BTimeSource::HandleMessage()</code></a>
is called.</p></li><li><p>If the message still hasn't been handled, the most-derived
interface's <code class="methodname">HandleMessage()</code> function is called.</p></li><li><p>If the message hasn't been handled,
<a class="link" href="BMediaNode.html#BMediaNode_HandleBadMessage" title="HandleBadMessage()"><code class="methodname">HandleBadMessage()</code></a>
is called.</p></li></ul><p>Once this has been done, <code class="methodname">WaitForMessage()</code>
returns. As you can see, this can be called from your control port to handle much of the work of
processing received messages.</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>A message has occurred within the given time period.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TIMED_OUT</code></span></p></td><td><p>The time <code class="parameter">waitUntil</code> has arrived without
a message being received.</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="BMediaNode_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="Enums_node_error"></a><a id="B_NODE_FAILED_START"></a>
<a id="B_NODE_FAILED_STOP"></a>
<a id="B_NODE_FAILED_SEEK"></a>
<a id="B_NODE_FAILED_SET_RUN_MODE"></a>
<a id="B_NODE_FAILED_TIME_WARP"></a>
<a id="B_NODE_FAILED_PREROLL"></a>
<a id="B_NODE_FAILED_SET_TIME_SOURCE_FOR"></a>
<a id="B_NODE_IN_DISTRESS"></a>
node_error</h4></div></div></div><p>Declared in: <code class="filename">media/MediaNode.h</code></p><p>The <span class="type">node_error</span> type defines the errors a node
can transmit to
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>s
that have registered to watch the node.</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_NODE_FAILED_START</code></span></p></td><td><p>The node failed on a
<a class="link" href="BMediaNode.html#BMediaNode_Start" title="Start()"><code class="methodname">Start()</code></a>
request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_STOP</code></span></p></td><td><p>The node failed on a
<a class="link" href="BMediaNode.html#BMediaNode_Stop" title="Stop()"><code class="methodname">Stop()</code></a>
request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_SEEK</code></span></p></td><td><p>The node failed on a
<a class="link" href="BMediaNode.html#BMediaNode_Seek" title="Seek()"><code class="methodname">Seek()</code></a>
request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_SET_RUN_MODE</code></span></p></td><td><p>The node's
<a class="link" href="BMediaNode.html#Enums_run_mode" title="run_mode">run_mode</a>
couldn't be set.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_TIME_WARP</code></span></p></td><td><p>The node couldn't fulfill a time warp request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_PREROLL</code></span></p></td><td><p>The node failed on a
<a class="link" href="BMediaNode.html#BMediaNode_Preroll" title="Preroll()"><code class="methodname">Preroll()</code></a>
request.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_FAILED_SET_TIME_SOURCE_FOR</code></span></p></td><td><p>The node's time source couldn't be changed.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NODE_IN_DISTRESS</code></span></p></td><td><p>The node is suffering in general.</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="Enums_run_mode"></a><a id="B_OFFLINE"></a>
<a id="B_RECORDING"></a>
<a id="B_DECREASE_PRECISION"></a>
<a id="B_INCREASE_LATENCY"></a>
<a id="B_DROP_DATA"></a>
run_mode</h4></div></div></div><p>Declared in: <code class="filename">media/MediaNode.h</code></p><p>The <span class="type">run_mode</span> type indicates how a node should cope if its performance
rate deviates from the desired rate.</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_OFFLINE</code></span></p></td><td><p>Keep data accurate, even if the performance lags or runs too
fast. This is typically used when rendering to disk.</p><p>When in offline mode the node doesn't need to worry about
processing buffers at any particular time. Each buffer's performance time
should be derived from the time stamped on the buffer, rather than from a
<a class="link" href="BTimeSource.html" title="BTimeSource"><code class="classname">BTimeSource</code></a>.
In fact, you'll usually want to call
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#set_thread_priority" title="set_thread_priority(), suggest_thread_priority()"><code class="function">set_thread_priority()</code></a>
to set your node's processing threads to a low priority while the node is
in offline mode. This lets software render media to disk in an efficient
manner, letting the user continue to work while the render occurs in the
background.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_RECORDING</code></span></p></td><td><p>Time-stamped buffers are being received from a node capturing
them from the real world; these buffers are guaranteed to have a time
stamp in the past (they're always "late").</p><p>Recording mode should be used when data is being sampled
from a physical input device. These devices always deliver buffers whose
time stamps are in the past (they're stamped with the time at which they
were sampled, which is of course in the past, unless you've stolen a time
machine from a professor from the 27th century, in which case you're
probably running BeOS R127.1 and this book is woefully obsolete).</p><p>Using <code class="constant">B_RECORDING</code> mode serves to warn
other nodes that the time stamps will be in the past.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_DECREASE_PRECISION</code></span></p></td><td><p>If the performance starts to lag, try to catch up.</p><p>In <code class="constant">B_DECREASE_PRECISION</code> mode,
your node should attempt to catch up if it
falls behind, by playing buffers of media data faster than normal. For
audio, this might mean playing back at a higher sampling rate; for video,
the frame rate might be temporarily boosted.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_INCREASE_LATENCY</code></span></p></td><td><p>If the performance starts to lag, increase playout
delay so buffers are delivered with less time to spare before they're
needed.</p><p>If your node gets behind in the
<code class="constant">B_INCREASE_LATENCY</code> run mode, your node should
increase its internal latency measurement and send call the
<a class="link" href="BBufferProducer.html#BBufferProducer_LateNoticeReceived" title="LateNoticeReceived()"><code class="methodname">LateNoticeReceived()</code></a>
function in anyone above your node in the media stream.</p><p>Your node should then try to produce each buffer earlier before the
buffer's performance time from that point on, so there's more time for
the buffers to reach their destination.</p><p>This mode is intended to compensate for data streams in which throughput
can vary over time. For example, if media data is being streamed over a
network, traffic fluctuations may require your node to adapt by adding
more buffering (latency).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_DROP_DATA</code></span></p></td><td><p>If the performance starts to lag, skip data.</p><p>When in <code class="constant">B_DROP_DATA</code> mode, your node should simply skip buffers if if
falls behind. Note that you still receive the buffers, but you should
ignore any that you must in order to keep playing as many buffers as
possible at the correct performance times.</p></td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMediaFormats.html">BMediaFormats</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="BMediaRoster.html">BMediaRoster</a> </div><div id="footerB"><div id="footerBL"><a href="BMediaFormats.html" title="BMediaFormats"><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="BMediaRoster.html" title="BMediaRoster"><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