<!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"/>
<title>libmpdclient: mpd/async.h File Reference</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.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>File Members</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>mpd/async.h File Reference</h1>
<p>Asynchronous MPD connections.
<a href="#_details">More...</a></p>
<p><a href="async_8h_source.html">Go to the source code of this file.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Enumerations</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a> { <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aaab9a1b22e94b2c93097467cf16e80f636">MPD_ASYNC_EVENT_READ</a> = 1,
<a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aaade6a1053d71150ac75af456455b5d6bd">MPD_ASYNC_EVENT_WRITE</a> = 2,
<a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aaadc6d6ad525d10eaa97bb60a552ec7330">MPD_ASYNC_EVENT_HUP</a> = 4,
<a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aaa0679f1dda176dc265f9d32e37bb20d69">MPD_ASYNC_EVENT_ERROR</a> = 8
}</td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_malloc struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#ab8b241ed7e245ed7f0e959fdd7c46ce1">mpd_async_new</a> (int fd)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#a5a23d22b65d21f9d3c3d1774bf0cd2cd">mpd_async_free</a> (struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_pure enum <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4">mpd_error</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#a79a87b05fecdf2300df9f36868c46876">mpd_async_get_error</a> (const struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_pure const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#afaac426a5cd3a6758c441f5d84eef401">mpd_async_get_error_message</a> (const struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_pure int </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#ab901897ac98ebc68a15378ab3ffba308">mpd_async_get_system_error</a> (const struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_pure int </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#ae77eaceb6b373467845c802ae4dcdd11">mpd_async_get_fd</a> (const struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_pure enum <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#aab289cca9797c1de6563042a9a7f5804">mpd_async_events</a> (const struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#a0fa5fe1f366ebe4228df24c3ad6468db">mpd_async_io</a> (struct <a class="el" href="structmpd__async.html">mpd_async</a> *async, enum <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a> events)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#a9d56fef109795a97ea6fdce0763b6e0c">mpd_async_send_command_v</a> (struct <a class="el" href="structmpd__async.html">mpd_async</a> *async, const char *command, va_list args)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_sentinel bool </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#a96de97eccfc02e05711e060c430a5a9c">mpd_async_send_command</a> (struct <a class="el" href="structmpd__async.html">mpd_async</a> *async, const char *command,...)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mpd_malloc char * </td><td class="memItemRight" valign="bottom"><a class="el" href="async_8h.html#ae2a7e0392645f566d424443eb2e43d4e">mpd_async_recv_line</a> (struct <a class="el" href="structmpd__async.html">mpd_async</a> *async)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Asynchronous MPD connections. </p>
<p>This class provides a very basic interface to MPD connections. It does not know much about the MPD protocol, it does not know any specific MPD command.</p>
<p>The constructor expects a socket descriptor which is already connected to MPD. The first thing it does is read the server's handshake code ("OK MPD 0.15.0"). </p>
<p>Definition in file <a class="el" href="async_8h_source.html">async.h</a>.</p>
<hr/><h2>Enumeration Type Documentation</h2>
<a class="anchor" id="af6cf61aaa6fba1b26e90030b6a0c99aa"></a><!-- doxytag: member="async.h::mpd_async_event" ref="af6cf61aaa6fba1b26e90030b6a0c99aa" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Event bit mask for polling. </p>
<dl><dt><b>Enumerator: </b></dt><dd><table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" id="af6cf61aaa6fba1b26e90030b6a0c99aaab9a1b22e94b2c93097467cf16e80f636"></a><!-- doxytag: member="MPD_ASYNC_EVENT_READ" ref="af6cf61aaa6fba1b26e90030b6a0c99aaab9a1b22e94b2c93097467cf16e80f636" args="" -->MPD_ASYNC_EVENT_READ</em> </td><td>
<p>ready to read from the file descriptor </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="af6cf61aaa6fba1b26e90030b6a0c99aaade6a1053d71150ac75af456455b5d6bd"></a><!-- doxytag: member="MPD_ASYNC_EVENT_WRITE" ref="af6cf61aaa6fba1b26e90030b6a0c99aaade6a1053d71150ac75af456455b5d6bd" args="" -->MPD_ASYNC_EVENT_WRITE</em> </td><td>
<p>ready to write to the file descriptor </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="af6cf61aaa6fba1b26e90030b6a0c99aaadc6d6ad525d10eaa97bb60a552ec7330"></a><!-- doxytag: member="MPD_ASYNC_EVENT_HUP" ref="af6cf61aaa6fba1b26e90030b6a0c99aaadc6d6ad525d10eaa97bb60a552ec7330" args="" -->MPD_ASYNC_EVENT_HUP</em> </td><td>
<p>hangup detected </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="af6cf61aaa6fba1b26e90030b6a0c99aaa0679f1dda176dc265f9d32e37bb20d69"></a><!-- doxytag: member="MPD_ASYNC_EVENT_ERROR" ref="af6cf61aaa6fba1b26e90030b6a0c99aaa0679f1dda176dc265f9d32e37bb20d69" args="" -->MPD_ASYNC_EVENT_ERROR</em> </td><td>
<p>I/O error </p>
</td></tr>
</table>
</dd>
</dl>
<p>Definition at line <a class="el" href="async_8h_source.html#l00053">53</a> of file <a class="el" href="async_8h_source.html">async.h</a>.</p>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="aab289cca9797c1de6563042a9a7f5804"></a><!-- doxytag: member="async.h::mpd_async_events" ref="aab289cca9797c1de6563042a9a7f5804" args="(const struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_pure enum <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a> mpd_async_events </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns a bit mask of events which should be polled for. </p>
</div>
</div>
<a class="anchor" id="a5a23d22b65d21f9d3c3d1774bf0cd2cd"></a><!-- doxytag: member="async.h::mpd_async_free" ref="a5a23d22b65d21f9d3c3d1774bf0cd2cd" args="(struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void mpd_async_free </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Closes the socket and frees memory. </p>
</div>
</div>
<a class="anchor" id="a79a87b05fecdf2300df9f36868c46876"></a><!-- doxytag: member="async.h::mpd_async_get_error" ref="a79a87b05fecdf2300df9f36868c46876" args="(const struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_pure enum <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4">mpd_error</a> mpd_async_get_error </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>After an error has occurred, this function returns the error code. If no error has occurred, it returns <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4af5bf4c717504926cccb975cd555bd561">MPD_ERROR_SUCCESS</a>. </p>
</div>
</div>
<a class="anchor" id="afaac426a5cd3a6758c441f5d84eef401"></a><!-- doxytag: member="async.h::mpd_async_get_error_message" ref="afaac426a5cd3a6758c441f5d84eef401" args="(const struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_pure const char* mpd_async_get_error_message </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>If mpd_async_is_alive() returns false, this function returns the human readable error message which caused this. This message is optional, and may be NULL. The pointer is invalidated by <a class="el" href="async_8h.html#a5a23d22b65d21f9d3c3d1774bf0cd2cd">mpd_async_free()</a>.</p>
<p>For <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4a49122c84c66c5a700e0bfa9d533b1701">MPD_ERROR_SERVER</a>, the error message is encoded in UTF-8. <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4ab53446dd6be580a1ca61bef2b253f707">MPD_ERROR_SYSTEM</a> obtains its error message from the operating system, and thus the locale's character set (and probably language) is used. Keep that in mind when you print error messages. </p>
</div>
</div>
<a class="anchor" id="ae77eaceb6b373467845c802ae4dcdd11"></a><!-- doxytag: member="async.h::mpd_async_get_fd" ref="ae77eaceb6b373467845c802ae4dcdd11" args="(const struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_pure int mpd_async_get_fd </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the file descriptor which should be polled by the caller. Do not use the file descriptor for anything except polling! The file descriptor never changes during the lifetime of this <a class="el" href="structmpd__async.html">mpd_async</a> object. </p>
</div>
</div>
<a class="anchor" id="ab901897ac98ebc68a15378ab3ffba308"></a><!-- doxytag: member="async.h::mpd_async_get_system_error" ref="ab901897ac98ebc68a15378ab3ffba308" args="(const struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_pure int mpd_async_get_system_error </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the error code from the operating system; on most operating systems, this is the errno value. Calling this function is only valid if <a class="el" href="async_8h.html#a79a87b05fecdf2300df9f36868c46876">mpd_async_get_error()</a> returned <a class="el" href="error_8h.html#a89d9378b765eea5f82efd3cbb20b74e4ab53446dd6be580a1ca61bef2b253f707">MPD_ERROR_SYSTEM</a>.</p>
<p>May be 0 if the operating system did not specify an error code. </p>
</div>
</div>
<a class="anchor" id="a0fa5fe1f366ebe4228df24c3ad6468db"></a><!-- doxytag: member="async.h::mpd_async_io" ref="a0fa5fe1f366ebe4228df24c3ad6468db" args="(struct mpd_async *async, enum mpd_async_event events)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool mpd_async_io </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">enum <a class="el" href="async_8h.html#af6cf61aaa6fba1b26e90030b6a0c99aa">mpd_async_event</a> </td>
<td class="paramname"> <em>events</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Call this function when poll() has returned events for this object's file descriptor. libmpdclient will attempt to perform I/O operations.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>false if the connection was closed due to an error </dd></dl>
</div>
</div>
<a class="anchor" id="ab8b241ed7e245ed7f0e959fdd7c46ce1"></a><!-- doxytag: member="async.h::mpd_async_new" ref="ab8b241ed7e245ed7f0e959fdd7c46ce1" args="(int fd)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_malloc struct <a class="el" href="structmpd__async.html">mpd_async</a>* mpd_async_new </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"> <em>fd</em></td>
<td> ) </td>
<td><code> [read]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Creates a new asynchronous MPD connection, based on a stream socket connected with MPD.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>fd</em> </td><td>the socket file descriptor of the stream connection to MPD </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a <a class="el" href="structmpd__async.html">mpd_async</a> object, or NULL on out of memory </dd></dl>
</div>
</div>
<a class="anchor" id="ae2a7e0392645f566d424443eb2e43d4e"></a><!-- doxytag: member="async.h::mpd_async_recv_line" ref="ae2a7e0392645f566d424443eb2e43d4e" args="(struct mpd_async *async)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_malloc char* mpd_async_recv_line </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Receives a line from the input buffer. The result will be null-terminated, without the newline character. The pointer is only valid until the next async function is called.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>async</em> </td><td>the connection </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a line on success, NULL otherwise </dd></dl>
</div>
</div>
<a class="anchor" id="a96de97eccfc02e05711e060c430a5a9c"></a><!-- doxytag: member="async.h::mpd_async_send_command" ref="a96de97eccfc02e05711e060c430a5a9c" args="(struct mpd_async *async, const char *command,...)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mpd_sentinel bool mpd_async_send_command </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>command</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"> <em>...</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Appends a command to the output buffer.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>async</em> </td><td>the connection </td></tr>
<tr><td valign="top"></td><td valign="top"><em>command</em> </td><td>the command name, followed by arguments, terminated by NULL </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>true on success, false if the buffer is full </dd></dl>
</div>
</div>
<a class="anchor" id="a9d56fef109795a97ea6fdce0763b6e0c"></a><!-- doxytag: member="async.h::mpd_async_send_command_v" ref="a9d56fef109795a97ea6fdce0763b6e0c" args="(struct mpd_async *async, const char *command, va_list args)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool mpd_async_send_command_v </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structmpd__async.html">mpd_async</a> * </td>
<td class="paramname"> <em>async</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>command</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">va_list </td>
<td class="paramname"> <em>args</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Appends a command to the output buffer.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>async</em> </td><td>the connection </td></tr>
<tr><td valign="top"></td><td valign="top"><em>command</em> </td><td>the command name, followed by arguments, terminated by NULL </td></tr>
<tr><td valign="top"></td><td valign="top"><em>args</em> </td><td>the argument list </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>true on success, false if the buffer is full </dd></dl>
</div>
</div>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sun Aug 8 15:52:35 2010 for libmpdclient by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
