Sophie

Sophie

distrib > Mageia > 6 > x86_64 > media > core-updates > by-pkgid > a41e5ac5fb332416cb8019ae392f1f99 > files > 194

lib64pulseaudio-devel-10.0-1.1.mga6.x86_64.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>PulseAudio: Server Query and Control</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>
<script type="text/javascript">
  $(document).ready(initResizable);
</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
   &#160;<span id="projectnumber">10.0.0-1.1.mga6</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',false,false,'search.php','Search');
});
</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">
$(document).ready(function(){initNavTree('introspect.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Server Query and Control </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="overv_sec"></a>
Overview</h1>
<p>Sometimes it is necessary to query and modify global settings in the server. For this, PulseAudio has the introspection API. It can list sinks, sources, samples and other aspects of the server. It can also modify the attributes of the server that will affect operations on a global level, and not just the application's context.</p>
<h1><a class="anchor" id="query_sec"></a>
Querying</h1>
<p>All querying is done through callbacks. This approach is necessary to maintain an asynchronous design. The client will request the information and some time later, the server will respond with the desired data.</p>
<p>Some objects can have multiple instances on the server. When requesting all of these at once, the callback will be called multiple times, once for each object. When the list has been exhausted, the callback will be called without an information structure and the eol parameter set to a positive value.</p>
<p>Note that even if a single object is requested, and not the entire list, the terminating call will still be made.</p>
<p>If an error occurs, the callback will be invoked without an information structure and eol set to a negative value..</p>
<p>Data members in the information structures are only valid during the duration of the callback. If they are required after the callback is finished, a deep copy of the information structure must be performed.</p>
<h2><a class="anchor" id="server_subsec"></a>
Server Information</h2>
<p>The server can be queried about its name, the environment it's running on and the currently active global defaults. Calling <a class="el" href="introspect_8h.html#a6f3bdd9982d9dec70ca5acf6ada3a9a2" title="Get some information about the server. ">pa_context_get_server_info()</a> provides access to a <a class="el" href="structpa__server__info.html" title="Server information. ">pa_server_info</a> structure containing all of these.</p>
<h2><a class="anchor" id="memstat_subsec"></a>
Memory Usage</h2>
<p>Statistics about memory usage can be fetched using <a class="el" href="introspect_8h.html#ae3eab4bd418ed49d639c6d2e62535e34" title="Get daemon memory block statistics. ">pa_context_stat()</a>, giving a <a class="el" href="structpa__stat__info.html" title="Memory block statistics. ">pa_stat_info</a> structure.</p>
<h2><a class="anchor" id="sinksrc_subsec"></a>
Sinks and Sources</h2>
<p>The server can have an arbitrary number of sinks and sources. Each sink and source have both an index and a name associated with it. As such, there are three ways to get access to them:</p>
<ul>
<li>By index - <a class="el" href="introspect_8h.html#ae886cd4bdc06fa98a61d15f818c33c9f" title="Get information about a sink by its index. ">pa_context_get_sink_info_by_index()</a> / <a class="el" href="introspect_8h.html#a55f2fbae1ce6b964e65c82c848280c06" title="Get information about a source by its index. ">pa_context_get_source_info_by_index()</a> </li>
<li>By name - <a class="el" href="introspect_8h.html#a446ffde2b8adea89940adcba40be319c" title="Get information about a sink by its name. ">pa_context_get_sink_info_by_name()</a> / <a class="el" href="introspect_8h.html#a3904ba3fc9d83355cb84aab0d1cd3e91" title="Get information about a source by its name. ">pa_context_get_source_info_by_name()</a> </li>
<li>All - <a class="el" href="introspect_8h.html#a77d4044975898442e53b0686501f5713" title="Get the complete sink list. ">pa_context_get_sink_info_list()</a> / <a class="el" href="introspect_8h.html#aa6663de37d9548ecb057dec5bd542898" title="Get the complete source list. ">pa_context_get_source_info_list()</a></li>
</ul>
<p>All three method use the same callback and will provide a <a class="el" href="structpa__sink__info.html" title="Stores information about sinks. ">pa_sink_info</a> or <a class="el" href="structpa__source__info.html" title="Stores information about sources. ">pa_source_info</a> structure.</p>
<h2><a class="anchor" id="siso_subsec"></a>
Sink Inputs and Source Outputs</h2>
<p>Sink inputs and source outputs are the representations of the client ends of streams inside the server. I.e. they connect a client stream to one of the global sinks or sources.</p>
<p>Sink inputs and source outputs only have an index to identify them. As such, there are only two ways to get information about them:</p>
<ul>
<li>By index - <a class="el" href="introspect_8h.html#aeca4a368510f46dac4313f498583e340" title="Get some information about a sink input by its index. ">pa_context_get_sink_input_info()</a> / <a class="el" href="introspect_8h.html#ae14eaf111465ea7c8aa2a9b746832b19" title="Get information about a source output by its index. ">pa_context_get_source_output_info()</a> </li>
<li>All - <a class="el" href="introspect_8h.html#ac232d88f3fca17d4dc9b9af4924de687" title="Get the complete sink input list. ">pa_context_get_sink_input_info_list()</a> / <a class="el" href="introspect_8h.html#ad57e2d1905a15af524ecccd481abe8e6" title="Get the complete list of source outputs. ">pa_context_get_source_output_info_list()</a></li>
</ul>
<p>The structure returned is the <a class="el" href="structpa__sink__input__info.html" title="Stores information about sink inputs. ">pa_sink_input_info</a> or <a class="el" href="structpa__source__output__info.html" title="Stores information about source outputs. ">pa_source_output_info</a> structure.</p>
<h2><a class="anchor" id="samples_subsec"></a>
Samples</h2>
<p>The list of cached samples can be retrieved from the server. Three methods exist for querying the sample cache list:</p>
<ul>
<li>By index - <a class="el" href="introspect_8h.html#a322e92056dadcf4f5abaa002d6e4034b" title="Get information about a sample by its index. ">pa_context_get_sample_info_by_index()</a> </li>
<li>By name - <a class="el" href="introspect_8h.html#a755c9d2c30fbd10bf18730f3ddfe1c3e" title="Get information about a sample by its name. ">pa_context_get_sample_info_by_name()</a> </li>
<li>All - <a class="el" href="introspect_8h.html#ac8219dea1efd6928edacad423ec6e7a6" title="Get the complete list of samples stored in the daemon. ">pa_context_get_sample_info_list()</a></li>
</ul>
<p>Note that this only retrieves information about the sample, not the sample data itself.</p>
<h2><a class="anchor" id="module_subsec"></a>
Driver Modules</h2>
<p>PulseAudio driver modules are identified by index and are retrieved using either <a class="el" href="introspect_8h.html#ab911f25494051a09e2ab2b01b483f2e5" title="Get some information about a module by its index. ">pa_context_get_module_info()</a> or <a class="el" href="introspect_8h.html#ab4895737ae03a4b37d6d69c5fdcfb365" title="Get the complete list of currently loaded modules. ">pa_context_get_module_info_list()</a>. The information structure is called <a class="el" href="structpa__module__info.html" title="Stores information about modules. ">pa_module_info</a>.</p>
<h2><a class="anchor" id="client_subsec"></a>
Clients</h2>
<p>PulseAudio clients are also identified by index and are retrieved using either <a class="el" href="introspect_8h.html#a824553dc1dcedf3533f0074c78fa22dc" title="Get information about a client by its index. ">pa_context_get_client_info()</a> or <a class="el" href="introspect_8h.html#afe9e2194ddebb06fb46836a93cf4a1df" title="Get the complete client list. ">pa_context_get_client_info_list()</a>. The information structure is called <a class="el" href="structpa__client__info.html" title="Stores information about clients. ">pa_client_info</a>.</p>
<h1><a class="anchor" id="ctrl_sec"></a>
Control</h1>
<p>Some parts of the server are only possible to read, but most can also be modified in different ways. Note that these changes will affect all connected clients and not just the one issuing the request.</p>
<h2><a class="anchor" id="sinksrc_subsec"></a>
Sinks and Sources</h2>
<p>The most common change one would want to apply to sinks and sources is to modify the volume of the audio. Identically to how sinks and sources can be queried, there are two ways of identifying them:</p>
<ul>
<li>By index - <a class="el" href="introspect_8h.html#a22397a278f2e059521800cb94af0e60a" title="Set the volume of a sink device specified by its index. ">pa_context_set_sink_volume_by_index()</a> / <a class="el" href="introspect_8h.html#a3ea6e197db41f97425baffd3d1fce9a1" title="Set the volume of a source device specified by its index. ">pa_context_set_source_volume_by_index()</a> </li>
<li>By name - <a class="el" href="introspect_8h.html#a9f326898ea80a5a41e586e50976bbfbb" title="Set the volume of a sink device specified by its name. ">pa_context_set_sink_volume_by_name()</a> / <a class="el" href="introspect_8h.html#aec3c4fdf61f019b65c710c9563f9a0e5" title="Set the volume of a source device specified by its name. ">pa_context_set_source_volume_by_name()</a></li>
</ul>
<p>It is also possible to mute a sink or source:</p>
<ul>
<li>By index - <a class="el" href="introspect_8h.html#ac2b6b66776211d46e651ae9ce1c5aceb" title="Set the mute switch of a sink device specified by its index. ">pa_context_set_sink_mute_by_index()</a> / <a class="el" href="introspect_8h.html#ad0087f8455adc79943685e777c84af83" title="Set the mute switch of a source device specified by its index. ">pa_context_set_source_mute_by_index()</a> </li>
<li>By name - <a class="el" href="introspect_8h.html#a96f6f68c8db4571238ff9c5d2d243ef3" title="Set the mute switch of a sink device specified by its name. ">pa_context_set_sink_mute_by_name()</a> / <a class="el" href="introspect_8h.html#a94425f4fbee323edb5d143f3fccd91ce" title="Set the mute switch of a source device specified by its name. ">pa_context_set_source_mute_by_name()</a></li>
</ul>
<h2><a class="anchor" id="siso_subsec"></a>
Sink Inputs and Source Outputs</h2>
<p>If an application desires to modify the volume of just a single stream (commonly one of its own streams), this can be done by setting the volume of its associated sink input or source output, using <a class="el" href="introspect_8h.html#a825ccd9e00765c0d397e2341086586ff" title="Set the volume of a sink input stream. ">pa_context_set_sink_input_volume()</a> or <a class="el" href="introspect_8h.html#ac20a29bb1a905718a5d9d28f34c5a48e" title="Set the volume of a source output stream. ">pa_context_set_source_output_volume()</a>.</p>
<p>It is also possible to remove sink inputs and source outputs, terminating the streams associated with them:</p>
<ul>
<li>Sink input - <a class="el" href="introspect_8h.html#af832875e5c5d8a57ef044dc156db73bd" title="Kill a sink input. ">pa_context_kill_sink_input()</a> </li>
<li>Source output - <a class="el" href="introspect_8h.html#afb3c80b1aaafafa846ceacd2d2bb4b39" title="Kill a source output. ">pa_context_kill_source_output()</a></li>
</ul>
<p>It is strongly recommended that all volume changes are done as a direct result of user input. With automated requests, such as those resulting from misguided attempts of crossfading, PulseAudio can store the stream volume at an inappropriate moment and restore it later. Besides, such attempts lead to OSD popups in some desktop environments.</p>
<p>As a special case of the general rule above, it is recommended that your application leaves the task of saving and restoring the volume of its streams to PulseAudio and does not attempt to do it by itself. PulseAudio really knows better about events such as stream moving or headphone plugging that would make the volume stored by the application inapplicable to the new configuration.</p>
<p>Another important case where setting a sink input volume may be a bad idea is related to interpreters that interpret potentially untrusted scripts. PulseAudio relies on your application not making malicious requests (such as repeatedly setting the volume to 100%). Thus, script interpreters that represent a security boundary must sandbox volume-changing requests coming from their scripts. In the worst case, it may be necessary to apply the script-requested volume to the script-produced sounds by altering the samples in the script interpreter and not touching the sink or sink input volume as seen by PulseAudio.</p>
<p>If an application changes any volume, it should also listen to changes of the same volume originating from outside the application (e.g., from the system mixer application) and update its user interface accordingly. Use <a class="el" href="subscribe.html">Event Subscription</a> to get such notifications.</p>
<h2><a class="anchor" id="module_subsec"></a>
Driver Modules</h2>
<p>Server modules can be remotely loaded and unloaded using <a class="el" href="introspect_8h.html#a4956ff4408e939c2b6fae9b76a86f05c" title="Load a module. ">pa_context_load_module()</a> and <a class="el" href="introspect_8h.html#a14a91adee752a5bec98e4846971b4802" title="Unload a module. ">pa_context_unload_module()</a>.</p>
<h2><a class="anchor" id="client_subsec"></a>
Clients</h2>
<p>The only operation supported on clients is the possibility of kicking them off the server using <a class="el" href="introspect_8h.html#ac81ed66b6bb184d1474a12cc2a5debc6" title="Kill a client. ">pa_context_kill_client()</a>. </p>
</div></div><!-- contents -->
</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="navelem"><a class="el" href="async.html">Asynchronous API</a></li>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
  </ul>
</div>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional