| Current File : //proc/self/root/kunden/kunden/usr/share/doc/pulseaudio-libs-devel/html/simple.html |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>PulseAudio: Simple API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">PulseAudio
 <span id="projectnumber">15.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('simple.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Simple API </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="overv_sec"></a>
Overview</h1>
<p>The simple API is designed for applications with very basic sound playback or capture needs. It can only support a single stream per connection and has no support for handling of complex features like events, channel mappings and volume control. It is, however, very simple to use and quite sufficient for many programs.</p>
<h1><a class="anchor" id="conn_sec"></a>
Connecting</h1>
<p>The first step before using the sound system is to connect to the server. This is normally done this way:</p>
<div class="fragment"><div class="line"><a class="code" href="structpa__simple.html">pa_simple</a> *s;</div>
<div class="line"><a class="code" href="structpa__sample__spec.html">pa_sample_spec</a> ss;</div>
<div class="line"> </div>
<div class="line">ss.<a class="code" href="structpa__sample__spec.html#a6f37954f1b7ac9d9bff4683171a10a99">format</a> = <a class="code" href="sample_8h.html#a292c1d8ebd4ca0de1d5d5379ee7be38a">PA_SAMPLE_S16NE</a>;</div>
<div class="line">ss.<a class="code" href="structpa__sample__spec.html#a625155d20d7e50a3808b889e314d25fa">channels</a> = 2;</div>
<div class="line">ss.<a class="code" href="structpa__sample__spec.html#a4fd5a1ef48c1cbea95a94b20a5cc02b0">rate</a> = 44100;</div>
<div class="line"> </div>
<div class="line">s = <a class="code" href="simple_8h.html#add9a7dce4e15955d4296726c26206689">pa_simple_new</a>(NULL, <span class="comment">// Use the default server.</span></div>
<div class="line"> <span class="stringliteral">"Fooapp"</span>, <span class="comment">// Our application's name.</span></div>
<div class="line"> <a class="code" href="def_8h.html#a7311932553b3f7962a092906576bc347acf403563d8f87f59f73c9674fee5a166">PA_STREAM_PLAYBACK</a>,</div>
<div class="line"> NULL, <span class="comment">// Use the default device.</span></div>
<div class="line"> <span class="stringliteral">"Music"</span>, <span class="comment">// Description of our stream.</span></div>
<div class="line"> &ss, <span class="comment">// Our sample format.</span></div>
<div class="line"> NULL, <span class="comment">// Use default channel map</span></div>
<div class="line"> NULL, <span class="comment">// Use default buffering attributes.</span></div>
<div class="line"> NULL, <span class="comment">// Ignore error code.</span></div>
<div class="line"> );</div>
<div class="ttc" id="adef_8h_html_a7311932553b3f7962a092906576bc347acf403563d8f87f59f73c9674fee5a166"><div class="ttname"><a href="def_8h.html#a7311932553b3f7962a092906576bc347acf403563d8f87f59f73c9674fee5a166">PA_STREAM_PLAYBACK</a></div><div class="ttdeci">@ PA_STREAM_PLAYBACK</div><div class="ttdoc">Playback stream.</div><div class="ttdef"><b>Definition:</b> def.h:160</div></div>
<div class="ttc" id="asample_8h_html_a292c1d8ebd4ca0de1d5d5379ee7be38a"><div class="ttname"><a href="sample_8h.html#a292c1d8ebd4ca0de1d5d5379ee7be38a">PA_SAMPLE_S16NE</a></div><div class="ttdeci">#define PA_SAMPLE_S16NE</div><div class="ttdoc">Signed 16 Bit PCM, native endian.</div><div class="ttdef"><b>Definition:</b> sample.h:209</div></div>
<div class="ttc" id="asimple_8h_html_add9a7dce4e15955d4296726c26206689"><div class="ttname"><a href="simple_8h.html#add9a7dce4e15955d4296726c26206689">pa_simple_new</a></div><div class="ttdeci">pa_simple * pa_simple_new(const char *server, const char *name, pa_stream_direction_t dir, const char *dev, const char *stream_name, const pa_sample_spec *ss, const pa_channel_map *map, const pa_buffer_attr *attr, int *error)</div><div class="ttdoc">Create a new connection to the server.</div></div>
<div class="ttc" id="astructpa__sample__spec_html"><div class="ttname"><a href="structpa__sample__spec.html">pa_sample_spec</a></div><div class="ttdoc">A sample format and attribute specification.</div><div class="ttdef"><b>Definition:</b> sample.h:252</div></div>
<div class="ttc" id="astructpa__sample__spec_html_a4fd5a1ef48c1cbea95a94b20a5cc02b0"><div class="ttname"><a href="structpa__sample__spec.html#a4fd5a1ef48c1cbea95a94b20a5cc02b0">pa_sample_spec::rate</a></div><div class="ttdeci">uint32_t rate</div><div class="ttdoc">The sample rate.</div><div class="ttdef"><b>Definition:</b> sample.h:256</div></div>
<div class="ttc" id="astructpa__sample__spec_html_a625155d20d7e50a3808b889e314d25fa"><div class="ttname"><a href="structpa__sample__spec.html#a625155d20d7e50a3808b889e314d25fa">pa_sample_spec::channels</a></div><div class="ttdeci">uint8_t channels</div><div class="ttdoc">Audio channels.</div><div class="ttdef"><b>Definition:</b> sample.h:259</div></div>
<div class="ttc" id="astructpa__sample__spec_html_a6f37954f1b7ac9d9bff4683171a10a99"><div class="ttname"><a href="structpa__sample__spec.html#a6f37954f1b7ac9d9bff4683171a10a99">pa_sample_spec::format</a></div><div class="ttdeci">pa_sample_format_t format</div><div class="ttdoc">The sample format.</div><div class="ttdef"><b>Definition:</b> sample.h:253</div></div>
<div class="ttc" id="astructpa__simple_html"><div class="ttname"><a href="structpa__simple.html">pa_simple</a></div><div class="ttdoc">An opaque simple connection object.</div></div>
</div><!-- fragment --><p>At this point a connected object is returned, or NULL if there was a problem connecting.</p>
<h1><a class="anchor" id="transfer_sec"></a>
Transferring data</h1>
<p>Once the connection is established to the server, data can start flowing. Using the connection is very similar to the normal read() and write() system calls. The main difference is that they're called <a class="el" href="simple_8h.html#a7d4d4e332b03f6525969241def7f822f" title="Read some data from the server.">pa_simple_read()</a> and <a class="el" href="simple_8h.html#af40711a9181c003b71074678c11372af" title="Write some data to the server.">pa_simple_write()</a>. Note that these operations always block.</p>
<h1><a class="anchor" id="ctrl_sec"></a>
Control</h1>
<ul>
<li><a class="el" href="simple_8h.html#a613419d24e0fd8909dd4d01897d2fa49" title="Return the playback or record latency.">pa_simple_get_latency()</a> - Will return the total latency of the playback or record pipeline, respectively. </li>
<li><a class="el" href="simple_8h.html#ad236fee060a54fce375dbc444b385f59" title="Flush the playback or record buffer.">pa_simple_flush()</a> - Will throw away all data currently in buffers.</li>
</ul>
<p>If a playback stream is used then the following operation is available:</p>
<ul>
<li><a class="el" href="simple_8h.html#a28d1c33441b1bd6e7486cf299cf98233" title="Wait until all data already written is played by the daemon.">pa_simple_drain()</a> - Will wait for all sent data to finish playing.</li>
</ul>
<h1><a class="anchor" id="cleanup_sec"></a>
Cleanup</h1>
<p>Once playback or capture is complete, the connection should be closed and resources freed. This is done through:</p>
<div class="fragment"><div class="line"><a class="code" href="simple_8h.html#ad66a88bc23d2a54542df441ff472c389">pa_simple_free</a>(s);</div>
<div class="ttc" id="asimple_8h_html_ad66a88bc23d2a54542df441ff472c389"><div class="ttname"><a href="simple_8h.html#ad66a88bc23d2a54542df441ff472c389">pa_simple_free</a></div><div class="ttdeci">void pa_simple_free(pa_simple *s)</div><div class="ttdoc">Close and free the connection to the server.</div></div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
</ul>
</div>
</body>
</html>