EVOLUTION-MANAGER
Edit File: ctl_external_plugins.html
<!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.5"/> <title>ALSA project - the C library reference: External Control Plugin SDK</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="search/search.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="search/search.js"></script> <script type="text/javascript"> $(document).ready(function() { searchBox.OnSelectItem(0); }); </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 style="padding-left: 0.5em;"> <div id="projectname">ALSA project - the C library reference </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.5 --> <script type="text/javascript"> var searchBox = new SearchBox("searchBox", "search",false,'Search'); </script> <div id="navrow1" class="tabs"> <ul class="tablist"> <li><a href="index.html"><span>Main Page</span></a></li> <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> <li><a href="modules.html"><span>Modules</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> <li> <div id="MSearchBox" class="MSearchBoxInactive"> <span class="left"> <img id="MSearchSelect" src="search/mag_sel.png" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()" alt=""/> <input type="text" id="MSearchField" value="Search" accesskey="S" onfocus="searchBox.OnSearchFieldFocus(true)" onblur="searchBox.OnSearchFieldFocus(false)" onkeyup="searchBox.OnSearchFieldChange(event)"/> </span><span class="right"> <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> </span> </div> </li> </ul> </div> <!-- window showing the filter options --> <div id="MSearchSelectWindow" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()" onkeydown="return searchBox.OnSearchSelectKey(event)"> <a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div> <!-- iframe showing the search results (closed by default) --> <div id="MSearchResultsWindow"> <iframe src="javascript:void(0)" frameborder="0" name="MSearchResults" id="MSearchResults"> </iframe> </div> </div><!-- top --> <div class="header"> <div class="headertitle"> <div class="title">External Control Plugin SDK </div> </div> </div><!--header--> <div class="contents"> <div class="textblock"><h1><a class="anchor" id="ctl_externals"></a> External Control Plugins</h1> <p>The external plugins are implemented in a shared object file located at /usr/lib/alsa-lib (the exact location depends on the build option and asoundrc configuration). It has to be the file like libasound_module_ctl_MYPLUGIN.so, where MYPLUGIN corresponds to your own plugin name.</p> <p>The entry point of the plugin is defined via <a class="el" href="group___ctl_plugin___s_d_k.html#ga13e494fe5c6068d6608a974f5a62a430">SND_CTL_PLUGIN_DEFINE_FUNC()</a> macro. This macro defines the function with a proper name to be referred from alsa-lib. The function takes the following 5 arguments: </p> <div class="fragment"><div class="line">int (<a class="code" href="group___control.html#ga06628f38def84a0fe3da74041db9d51f">snd_ctl_t</a> **phandle, <span class="keyword">const</span> <span class="keywordtype">char</span> *name, <a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985">snd_config_t</a> *root,</div> <div class="line"> <a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985">snd_config_t</a> *conf, <span class="keywordtype">int</span> mode)</div> </div><!-- fragment --><p> The first argument, phandle, is the pointer to store the resultant control handle. The arguments name, root and mode are the parameters to be passed to the plugin constructor. The conf is the configuration tree for the plugin. The arguments above are defined in the macro itself, so don't use variables with the same names to shadow parameters.</p> <p>After parsing the configuration parameters in the given conf tree, usually you will call the external plugin API function <a class="el" href="group___ctl_plugin___s_d_k.html#ga317775f9c5e239781e71735ca5ba1ca6" title="Create an external control plugin instance. ">snd_ctl_ext_create()</a>. The control handle must be filled *phandle in return. Then this function must return either a value 0 when succeeded, or a negative value as the error code.</p> <p>Finally, add <a class="el" href="group___ctl_plugin___s_d_k.html#gaa94fc65e8951f16e4b273b0f81e90f7e">SND_CTL_PLUGIN_SYMBOL()</a> with the name of your plugin as the argument at the end. This defines the proper versioned symbol as the reference.</p> <p>The typical code would look like below: </p> <div class="fragment"><div class="line"><span class="keyword">struct </span>myctl_info {</div> <div class="line"> <a class="code" href="structsnd__ctl__ext.html">snd_ctl_ext_t</a> ext;</div> <div class="line"> <span class="keywordtype">int</span> my_own_data;</div> <div class="line"> ...</div> <div class="line">};</div> <div class="line"></div> <div class="line"><a class="code" href="group___ctl_plugin___s_d_k.html#ga13e494fe5c6068d6608a974f5a62a430">SND_CTL_PLUGIN_DEFINE_FUNC</a>(myctl)</div> <div class="line">{</div> <div class="line"> <a class="code" href="group___config.html#ga6c621ab8875a222e1fcb56e9feed6ec6">snd_config_iterator_t</a> i, next;</div> <div class="line"> <span class="keyword">struct </span>myctl_info *myctl;</div> <div class="line"> <span class="keywordtype">int</span> err;</div> <div class="line"></div> <div class="line"> <a class="code" href="group___config.html#gac3f21333e1f9b602cad9b06cb418fa80">snd_config_for_each</a>(i, next, conf) {</div> <div class="line"> <a class="code" href="group___config.html#ga1c20905af775ae77d04d1a5696f67985">snd_config_t</a> *n = <a class="code" href="group___config.html#gaa91fe1d926d88041ed516a6a7293f606">snd_config_iterator_entry</a>(i);</div> <div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *id;</div> <div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group___config.html#gae366751e8ea98aeb69f9ef876f7b949c">snd_config_get_id</a>(n, &<span class="keywordtype">id</span>) < 0)</div> <div class="line"> <span class="keywordflow">continue</span>;</div> <div class="line"> <span class="keywordflow">if</span> (strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"comment"</span>) == 0 || strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"type"</span>) == 0)</div> <div class="line"> <span class="keywordflow">continue</span>;</div> <div class="line"> <span class="keywordflow">if</span> (strcmp(<span class="keywordtype">id</span>, <span class="stringliteral">"my_own_parameter"</span>) == 0) {</div> <div class="line"> ....</div> <div class="line"> <span class="keywordflow">continue</span>;</div> <div class="line"> }</div> <div class="line"> <a class="code" href="group___error.html#ga281420eb1344fe9f01d67d20c92457f0">SNDERR</a>(<span class="stringliteral">"Unknown field %s"</span>, <span class="keywordtype">id</span>);</div> <div class="line"> <span class="keywordflow">return</span> -EINVAL;</div> <div class="line"> }</div> <div class="line"></div> <div class="line"> myctl = calloc(1, <span class="keyword">sizeof</span>(*myctl));</div> <div class="line"> <span class="keywordflow">if</span> (myctl == NULL)</div> <div class="line"> <span class="keywordflow">return</span> -ENOMEM;</div> <div class="line"></div> <div class="line"> myctl->ext.version = <a class="code" href="group___ctl_plugin___s_d_k.html#ga65ea29f84b09ee3e640f88b06d05a1a2">SND_CTL_EXT_VERSION</a>;</div> <div class="line"> myctl->ext.card_idx = 0;</div> <div class="line"> strcpy(myctl->ext.id, <span class="stringliteral">"Myctl"</span>);</div> <div class="line"> strcpy(myctl->ext.name, <span class="stringliteral">"My Control"</span>);</div> <div class="line"> strcpy(myctl->ext.longname, <span class="stringliteral">"My External Control for Foobar"</span>);</div> <div class="line"> strcpy(myctl->ext.mixername, <span class="stringliteral">"My Control"</span>);</div> <div class="line"> myctl->ext.callback = &my_own_callback;</div> <div class="line"> myctl->ext.private_data = myctl;</div> <div class="line"> ....</div> <div class="line"></div> <div class="line"> err = <a class="code" href="group___p_c_m___ext_plug.html#gab0b27889f74c83cd033062981320fd62">snd_pcm_extplug_create</a>(&myctl->ext, name, mode);</div> <div class="line"> <span class="keywordflow">if</span> (err < 0) {</div> <div class="line"> myctl_free(myctl);</div> <div class="line"> <span class="keywordflow">return</span> err;</div> <div class="line"> }</div> <div class="line"></div> <div class="line"> *phandle = myctl->ext.handle;</div> <div class="line"> <span class="keywordflow">return</span> 0;</div> <div class="line">}</div> <div class="line"></div> <div class="line"><a class="code" href="group___ctl_plugin___s_d_k.html#gaa94fc65e8951f16e4b273b0f81e90f7e">SND_CTL_PLUGIN_SYMBOL</a>(myctl);</div> </div><!-- fragment --><p>Read the codes in alsa-plugins package for the real examples.</p> <h1><a class="anchor" id="ctl_ext_impl"></a> Callback Functions of External Control Plugins</h1> <p>The following fields have to be filled in external control record before calling <a class="el" href="group___ctl_plugin___s_d_k.html#ga317775f9c5e239781e71735ca5ba1ca6" title="Create an external control plugin instance. ">snd_ctl_ext_create()</a> : version, card_idx, id, name, longname, mixername, poll_fd and callback. Otherfields are optional and should be initialized with zero.</p> <p>The constant <a class="el" href="group___ctl_plugin___s_d_k.html#ga65ea29f84b09ee3e640f88b06d05a1a2">SND_CTL_EXT_VERSION</a> must be passed to the version field for the version check in alsa-lib. The card_idx field specifies the card index of this control. [FIXME: solve confliction of card index in alsa-lib?]</p> <p>The id, name, longname and mixername fields are the strings shown in the card_info inqurirys. They are the char arrays, so you have to <em>copy</em> strings to these fields.</p> <p>The callback field contains the table of callback functions for this plugin (defined as <a class="el" href="group___ctl_plugin___s_d_k.html#ga8185c9a0e27e9562511a82dda1d20ddf">snd_ctl_ext_callback_t</a>). The poll_fd can be used to specify the poll file descriptor for this control. Set -1 if not available. Alternatively, you can define poll_descriptors_count and poll_descriptors callbacks in the callback table for handling the poll descriptor(s) dynamically after the creation of plugin instance.</p> <p>The driver can set an arbitrary value (pointer) to private_data field to refer its own data in the callbacks.</p> <p>The rest fields are filled by <a class="el" href="group___ctl_plugin___s_d_k.html#ga317775f9c5e239781e71735ca5ba1ca6" title="Create an external control plugin instance. ">snd_ctl_ext_create()</a>. The handle field is the resultant PCM handle. The others are the current status of the PCM.</p> <h1><a class="anchor" id="ctl_ext_impl"></a> Callback Functions of External Control Plugins</h1> <p>The callback functions in <a class="el" href="group___ctl_plugin___s_d_k.html#ga8185c9a0e27e9562511a82dda1d20ddf">snd_ctl_ext_callback_t</a> define the real behavior of the driver. There are many callbacks but many of them are optional.</p> <p>The close callback is called when the PCM is closed. If the plugin allocates private resources, this is the place to release them again. This callback is optional.</p> <p>The elem_count and elem_list callbacks are mandatory. The elem_count returns the total number of control elements. The elem_list returns the control element ID of the corresponding element offset (the offset is from 0 to elem_count - 1). The id field is initialized to all zero in prior to elem_list callback. The callback has to fill the necessary field (typically iface, name and index) in return via the standard control API functions like <a class="el" href="group___control.html#ga33855eaf0261c321cbf0a88baf290418" title="Set interface part for a CTL element identifier. ">snd_ctl_elem_id_set_interface</a>, <a class="el" href="group___control.html#ga813d02a44a9d01a4a2fe81eda7a8670a" title="Set name part for a CTL element identifier. ">snd_ctl_elem_id_set_name</a> and <a class="el" href="group___control.html#ga65af30a51becd092f6da1e357fc46094" title="Set index part for a CTL element identifier. ">snd_ctl_elem_id_set_index</a>, etc. The callbacks should return 0 if successful, or a negative error code.</p> <p>The find_elem callback is used to convert the given control element ID to the certain key value for the faster access to get, read and write callbacks. The key type is alias of unsigned long, so you can assign some static number (e.g. index of the array) to this value of the corresponding element, or assign the pointer (cast to <a class="el" href="group___ctl_plugin___s_d_k.html#gac73a66a3973afb51c4e585177647c693">snd_ctl_ext_key_t</a>). When no key is defined or found, return <a class="el" href="group___ctl_plugin___s_d_k.html#gac1f0737189a30bbb1e4dcbf681df39fd">SND_CTL_EXT_KEY_NOT_FOUND</a>. This callback is (very likely) required if you use get, read and write callbacks as follows. If you need to create a record dynamically (e.g. via malloc) at each find_elem call, the allocated record can be released with the optional free_key callback.</p> <p>The get_attribute is a mandatory callback, which returns the attribute of the control element given via a key value (converted with find_elem callback). It must fill the control element type (<a class="el" href="group___control.html#gac42e0ed6713b62711af5e80b4b3bcfec">snd_ctl_elem_type_t</a>), the access type (<a class="el" href="group___ctl_plugin___s_d_k.html#gaeedd1d7413b3025e9cede1b27e509de5">snd_ctl_ext_access_t</a>), and the count (element array size). The callback returns 0 if successful, or a negative error code, as usual.</p> <p>The get_integer_info, get_integetr64_info and get_enumerated_info callbacks are called to return the information of the given control element for each element type. For integer and integer64 types, the callbacks need to fill the minimal (imin), maximal (imax) and the step (istep) values of the control. For the enumerated type, the number of enum items must be filled. Additionally, the enum control has to define get_enumerated_name callback to store the name of the enumerated item of the given control element. All functions return 0 if successful, or a negative error code.</p> <p>For reading the current values of a control element, read_integer, read_integer64, read_enumerated, read_bytes and read_iec958 callbacks are called depending on the element type. These callbacks have to fill the current values of the element in return. Note that a control element can be an array. If it contains more than one values (i.e. the count value in get_attribute callback is more than 1), <em>all</em> values must be filled on the given value pointer as an array. Also, note that the boolean type is handled as integer here (although boolean type doesn't need to define the corresponding info callback since it's obvious). These callbacks return 0 if successful, or a negative error code.</p> <p>For writing the current values, write_integer, write_integer64, write_bytes, and write_iec958 callbacks are called as well as for read. The callbacks should check the current values and compare with the given values. If they are identical, the callbacks should do nothing and return 0. If they differ, update the current values and return 1, instead. For any errors, return a negative error code.</p> <p>The subscribe_events callback is called when the application subscribes or cancels the event notifications (e.g. through mixer API). The current value of event subscription is kept in the subscribed field. The read_event callback is called for reading a pending notification event. The callback needs to fill the event_mask value, a bit-field defined as SND_CTL_EVENT_MASK_XXX. If no event is pending, return -EAGAIN. These two callbacks are optional.</p> <p>The poll_descriptors_count and poll_descriptors callbacks are used to return the poll descriptor(s) via callbacks. As already mentioned, if the callback cannot set the static poll_fd, you can define these callbacks to return dynamically. Also, when multiple poll descriptors are required, use these callbacks. The poll_revents callback is used for handle poll revents. </p> </div></div><!-- contents --> <!-- start footer part --> <hr class="footer"/><address class="footer"><small> Generated by  <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/> </a> 1.8.5 </small></address> </body> </html>