blob: b90da16a9a7807537bee338e466fb87c37aa7008 [file] [log] [blame]
<!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.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libguac: guacamole/parser.h File Reference</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/searchdata.js"></script>
<script type="text/javascript" src="search/search.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">libguac
&#160;<span id="projectnumber">1.1.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<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&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</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 id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="dir_6bb9fad85c98b48a11165f494b9f53ce.html">guacamole</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#nested-classes">Data Structures</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">parser.h File Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>Provides functions and structures for parsing the Guacamole protocol.
<a href="#details">More...</a></p>
<p><a href="parser_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structguac__parser.html">guac_parser</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">A Guacamole protocol parser, which reads individual instructions, filling its own internal structure with the most recently read instruction data. <a href="structguac__parser.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a69dc498eb4d71d353bff07b88ec21cad"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#a69dc498eb4d71d353bff07b88ec21cad">guac_parser_alloc</a> ()</td></tr>
<tr class="memdesc:a69dc498eb4d71d353bff07b88ec21cad"><td class="mdescLeft">&#160;</td><td class="mdescRight">Allocates a new parser. <a href="#a69dc498eb4d71d353bff07b88ec21cad">More...</a><br /></td></tr>
<tr class="separator:a69dc498eb4d71d353bff07b88ec21cad"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ab1ca22b7bf9c232cce0d122f03dc183d"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#ab1ca22b7bf9c232cce0d122f03dc183d">guac_parser_append</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser, void *buffer, int length)</td></tr>
<tr class="memdesc:ab1ca22b7bf9c232cce0d122f03dc183d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Appends data from the given buffer to the given parser. <a href="#ab1ca22b7bf9c232cce0d122f03dc183d">More...</a><br /></td></tr>
<tr class="separator:ab1ca22b7bf9c232cce0d122f03dc183d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8899dd607997fcffd78517947b17760b"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#a8899dd607997fcffd78517947b17760b">guac_parser_length</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser)</td></tr>
<tr class="memdesc:a8899dd607997fcffd78517947b17760b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the number of unparsed bytes stored in the given parser's internal buffers. <a href="#a8899dd607997fcffd78517947b17760b">More...</a><br /></td></tr>
<tr class="separator:a8899dd607997fcffd78517947b17760b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a56e7b2a85abdb6cb4ec4bd6e47a92ed3"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#a56e7b2a85abdb6cb4ec4bd6e47a92ed3">guac_parser_shift</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser, void *buffer, int length)</td></tr>
<tr class="memdesc:a56e7b2a85abdb6cb4ec4bd6e47a92ed3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Removes up to length bytes from internal buffer of unparsed bytes, storing them in the given buffer. <a href="#a56e7b2a85abdb6cb4ec4bd6e47a92ed3">More...</a><br /></td></tr>
<tr class="separator:a56e7b2a85abdb6cb4ec4bd6e47a92ed3"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad3b7d4df1ca25c5bced1c08b329f0a0f"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#ad3b7d4df1ca25c5bced1c08b329f0a0f">guac_parser_free</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser)</td></tr>
<tr class="memdesc:ad3b7d4df1ca25c5bced1c08b329f0a0f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Frees all memory allocated to the given parser. <a href="#ad3b7d4df1ca25c5bced1c08b329f0a0f">More...</a><br /></td></tr>
<tr class="separator:ad3b7d4df1ca25c5bced1c08b329f0a0f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8a1169f5040732e4f4b55ee6c1e1fe93"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#a8a1169f5040732e4f4b55ee6c1e1fe93">guac_parser_read</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser, <a class="el" href="structguac__socket.html">guac_socket</a> *socket, int usec_timeout)</td></tr>
<tr class="memdesc:a8a1169f5040732e4f4b55ee6c1e1fe93"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a single instruction from the given <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a> connection. <a href="#a8a1169f5040732e4f4b55ee6c1e1fe93">More...</a><br /></td></tr>
<tr class="separator:a8a1169f5040732e4f4b55ee6c1e1fe93"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac54c94465aead463ce10e9a090b9b701"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="parser_8h.html#ac54c94465aead463ce10e9a090b9b701">guac_parser_expect</a> (<a class="el" href="structguac__parser.html">guac_parser</a> *parser, <a class="el" href="structguac__socket.html">guac_socket</a> *socket, int usec_timeout, const char *opcode)</td></tr>
<tr class="memdesc:ac54c94465aead463ce10e9a090b9b701"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads a single instruction from the given <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a>. <a href="#ac54c94465aead463ce10e9a090b9b701">More...</a><br /></td></tr>
<tr class="separator:ac54c94465aead463ce10e9a090b9b701"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Provides functions and structures for parsing the Guacamole protocol. </p>
</div><h2 class="groupheader">Function Documentation</h2>
<a id="a69dc498eb4d71d353bff07b88ec21cad"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a69dc498eb4d71d353bff07b88ec21cad">&#9670;&nbsp;</a></span>guac_parser_alloc()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structguac__parser.html">guac_parser</a>* guac_parser_alloc </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Allocates a new parser. </p>
<dl class="section return"><dt>Returns</dt><dd>The newly allocated parser, or NULL if an error occurs during allocation, in which case guac_error will be set appropriately. </dd></dl>
</div>
</div>
<a id="ab1ca22b7bf9c232cce0d122f03dc183d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab1ca22b7bf9c232cce0d122f03dc183d">&#9670;&nbsp;</a></span>guac_parser_append()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int guac_parser_append </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>length</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Appends data from the given buffer to the given parser. </p>
<p>The data will be appended, if possible, to the in-progress instruction as a reference and thus the buffer must remain valid throughout the life of the current instruction. This function may modify the contents of the buffer when those contents are part of an element within the instruction being read.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The parser to append data to. </td></tr>
<tr><td class="paramname">buffer</td><td>A buffer containing data that should be appended to this parser. </td></tr>
<tr><td class="paramname">length</td><td>The number of bytes available for appending within the buffer. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The number of bytes appended to this parser, which may be zero if more data is needed. </dd></dl>
</div>
</div>
<a id="ac54c94465aead463ce10e9a090b9b701"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac54c94465aead463ce10e9a090b9b701">&#9670;&nbsp;</a></span>guac_parser_expect()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int guac_parser_expect </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structguac__socket.html">guac_socket</a> *&#160;</td>
<td class="paramname"><em>socket</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>usec_timeout</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>opcode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Reads a single instruction from the given <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a>. </p>
<p>This operates identically to <a class="el" href="parser_8h.html#a8a1169f5040732e4f4b55ee6c1e1fe93" title="Reads a single instruction from the given guac_socket connection. ">guac_parser_read()</a>, except that an error is returned if the expected opcode is not received.</p>
<p>If an error occurs reading the instruction, NULL is returned, and guac_error is set appropriately.</p>
<p>If the instruction read is not the expected instruction, NULL is returned, and guac_error is set to GUAC_STATUS_BAD_STATE.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The <a class="el" href="structguac__parser.html" title="A Guacamole protocol parser, which reads individual instructions, filling its own internal structure ...">guac_parser</a> to read instruction data from. </td></tr>
<tr><td class="paramname">socket</td><td>The <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a> connection to use. </td></tr>
<tr><td class="paramname">usec_timeout</td><td>The maximum number of microseconds to wait before giving up. </td></tr>
<tr><td class="paramname">opcode</td><td>The opcode of the instruction to read. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Zero if an instruction with the given opcode was read, non-zero otherwise. If an instruction was read, but the instruction had a different opcode, non-zero is returned and guac_error is set to GUAC_STATUS_BAD_STATE. </dd></dl>
</div>
</div>
<a id="ad3b7d4df1ca25c5bced1c08b329f0a0f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad3b7d4df1ca25c5bced1c08b329f0a0f">&#9670;&nbsp;</a></span>guac_parser_free()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void guac_parser_free </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Frees all memory allocated to the given parser. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The parser to free. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="a8899dd607997fcffd78517947b17760b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8899dd607997fcffd78517947b17760b">&#9670;&nbsp;</a></span>guac_parser_length()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int guac_parser_length </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the number of unparsed bytes stored in the given parser's internal buffers. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The parser to return the length of. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The number of unparsed bytes stored in the given parser. </dd></dl>
</div>
</div>
<a id="a8a1169f5040732e4f4b55ee6c1e1fe93"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8a1169f5040732e4f4b55ee6c1e1fe93">&#9670;&nbsp;</a></span>guac_parser_read()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int guac_parser_read </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structguac__socket.html">guac_socket</a> *&#160;</td>
<td class="paramname"><em>socket</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>usec_timeout</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Reads a single instruction from the given <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a> connection. </p>
<p>This may result in additional data being read from the <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a>, stored internally within a buffer for future parsing. Future calls to <a class="el" href="parser_8h.html#a8a1169f5040732e4f4b55ee6c1e1fe93" title="Reads a single instruction from the given guac_socket connection. ">guac_parser_read()</a> will read from the interal buffer before reading from the <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a>. Data from the internal buffer can be removed and used elsewhere through <a class="el" href="parser_8h.html#a56e7b2a85abdb6cb4ec4bd6e47a92ed3" title="Removes up to length bytes from internal buffer of unparsed bytes, storing them in the given buffer...">guac_parser_shift()</a>.</p>
<p>If an error occurs reading the instruction, non-zero is returned, and guac_error is set appropriately.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The <a class="el" href="structguac__parser.html" title="A Guacamole protocol parser, which reads individual instructions, filling its own internal structure ...">guac_parser</a> to read instruction data from. </td></tr>
<tr><td class="paramname">socket</td><td>The <a class="el" href="structguac__socket.html" title="The core I/O object of Guacamole. ">guac_socket</a> connection to use. </td></tr>
<tr><td class="paramname">usec_timeout</td><td>The maximum number of microseconds to wait before giving up. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Zero if an instruction was read within the time allowed, or non-zero if no instruction could be read. If the instruction could not be read completely because the timeout elapsed, in which case guac_error will be set to GUAC_STATUS_INPUT_TIMEOUT and additional calls to <a class="el" href="parser_8h.html#a8a1169f5040732e4f4b55ee6c1e1fe93" title="Reads a single instruction from the given guac_socket connection. ">guac_parser_read()</a> will be required. </dd></dl>
</div>
</div>
<a id="a56e7b2a85abdb6cb4ec4bd6e47a92ed3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a56e7b2a85abdb6cb4ec4bd6e47a92ed3">&#9670;&nbsp;</a></span>guac_parser_shift()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int guac_parser_shift </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structguac__parser.html">guac_parser</a> *&#160;</td>
<td class="paramname"><em>parser</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>length</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Removes up to length bytes from internal buffer of unparsed bytes, storing them in the given buffer. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">parser</td><td>The parser to remove unparsed bytes from. </td></tr>
<tr><td class="paramname">buffer</td><td>The buffer to store the unparsed bytes within. </td></tr>
<tr><td class="paramname">length</td><td>The length of the given buffer. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The number of bytes stored in the given buffer. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14
</small></address>
</body>
</html>