<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>PulseAudio: Simple API</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="main.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="main.html">main</a>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="simple">Simple API </a></h1><h2><a class="anchor" name="overv_sec">
Overview</a></h2>
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 handling of complex features like events, channel mappings and volume control. It is, however, very simple to use and quite sufficent for many programs.<h2><a class="anchor" name="conn_sec">
Connecting</a></h2>
The first step before using the sound system is to connect to the server. This is normally done this way:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="structpa__simple.html" title="An opaque simple connection object.">pa_simple</a> *s;
<a class="code" href="structpa__sample__spec.html" title="A sample format and attribute specification.">pa_sample_spec</a> ss;
ss.<a class="code" href="structpa__sample__spec.html#6f37954f1b7ac9d9bff4683171a10a99" title="The sample format.">format</a> = <a class="code" href="sample_8h.html#292c1d8ebd4ca0de1d5d5379ee7be38a" title="Signed 16 Bit PCM, native endian.">PA_SAMPLE_S16NE</a>;
ss.<a class="code" href="structpa__sample__spec.html#625155d20d7e50a3808b889e314d25fa" title="Audio channels.">channels</a> = 2;
ss.<a class="code" href="structpa__sample__spec.html#4fd5a1ef48c1cbea95a94b20a5cc02b0" title="The sample rate.">rate</a> = 44100;
s = <a class="code" href="simple_8h.html#dd9a7dce4e15955d4296726c26206689" title="Create a new connection to the server.">pa_simple_new</a>(NULL, <span class="comment">// Use the default server.</span>
<span class="stringliteral">"Fooapp"</span>, <span class="comment">// Our application's name.</span>
<a class="code" href="def_8h.html#7311932553b3f7962a092906576bc347cf403563d8f87f59f73c9674fee5a166" title="Playback stream.">PA_STREAM_PLAYBACK</a>,
NULL, <span class="comment">// Use the default device.</span>
<span class="stringliteral">"Music"</span>, <span class="comment">// Description of our stream.</span>
&ss, <span class="comment">// Our sample format.</span>
NULL, <span class="comment">// Use default channel map</span>
NULL, <span class="comment">// Use default buffering attributes.</span>
NULL, <span class="comment">// Ignore error code.</span>
);
</pre></div><p>
At this point a connected object is returned, or NULL if there was a problem connecting.<h2><a class="anchor" name="transfer_sec">
Transferring Data</a></h2>
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 call <a class="el" href="simple_8h.html#7d4d4e332b03f6525969241def7f822f" title="Read some data from the server.">pa_simple_read()</a> and <a class="el" href="simple_8h.html#f40711a9181c003b71074678c11372af" title="Write some data to the server.">pa_simple_write()</a>. Note that these operations always block.<h2><a class="anchor" name="ctrl_sec">
Control</a></h2>
If a playback stream is used then a few other operations are available:<p>
<ul>
<li><a class="el" href="simple_8h.html#28d1c33441b1bd6e7486cf299cf98233" 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>
<li><a class="el" href="simple_8h.html#d236fee060a54fce375dbc444b385f59" title="Flush the playback buffer.">pa_simple_flush()</a> - Will throw away all data currently in buffers. </li>
<li>pa_simple_get_playback_latency() - Will return the total latency of the playback pipeline.</li>
</ul>
<h2><a class="anchor" name="cleanup_sec">
Cleanup</a></h2>
Once playback or capture is complete, the connection should be closed and resources freed. This is done through:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="simple_8h.html#d66a88bc23d2a54542df441ff472c389" title="Close and free the connection to the server.">pa_simple_free</a>(s);
</pre></div> </div>
<hr size="1"><address style="text-align: right;"><small>Generated on Wed Sep 2 04:18:20 2009 for PulseAudio by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
distrib
>
Mandriva
>
2009.1
>
x86_64
>
media
>
main-testing
>
by-pkgid
>
187676b5433787923dfa2cdd6900c6cd
>
files
>
149
