autodoc.git
/
traditional_manual
/
chapter_9.html
version
»
Context lines:
10
20
40
80
file
none
3
autodoc.git/traditional_manual/chapter_9.html:6740:
<dd class='body--doc'><p>Read a network byte order two:s complement signed number of size n*8 bits, then return it.</p> <p> Will return UNDEFINED if there is not enough buffer space available unless error mode is set to throw errors.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>rewind_on_error</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>UnwindKey</code> <b><span class='method'>rewind_on_error</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Create an object that, when it goes out of scope without having
+
been destructed explicitly, will cause the buffer to rewind to
+
the location it had when this function is called.</p>
+
<p> This will happen if you throw an error or otherwise let the
+
object fall out of scope.</p>
+
<p> Take some care with these objects, if you create multiple ones
+
at once the results might be somewhat confusing if you do not
+
release them in the reverse order they were created in (then
+
again, you almost certainly really only need one)</p>
+
<p> Use <code>destruct</code> or <code>UnwindKey.release</code> to stop the buffer from being rewound.</p>
+
<p> You can call <code>update</code> in the generated object to change where
+
it will be rewound to.</p>
+
<p> The typical usecase of this object is when pasing a packet
+
protocol with variable length packets where the lenght is not
+
immediately known. It saves you from keeping track of how much
+
to rewind if you had not actually gotten the whole packet yet.</p>
+
</dd>
+
<dt class='head--doc'>Example</dt>
+
<dd class='example'><pre><pre><code><span class='type'>void</span> parse_packet<span class='delim'>(</span> <span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer b <span class='delim'>)</span>
+
<span class='delim'>{</span>
+
<span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer<span class='delim'>.</span>UnwindKey rewind <span class='delim'>=</span> b->rewind_on_error<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
+
b->set_error_mode<span class='delim'>(</span>1<span class='delim'>)</span><span class='delim'>;</span>
+
+
<span class='lang'>switch</span><span class='delim'>(</span> b->read_int8<span class='delim'>(</span><span class='delim'>)</span> <span class='delim'>)</span> <span class='comment'>// packet type</span>
+
<span class='delim'>{</span>
+
<span class='lang'>case</span> DATA<span class='delim'>:</span>
+
<span class='type'>int</span> channel <span class='delim'>=</span> b->read_int8<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
+
<span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer data <span class='delim'>=</span> b->read_hbuffer<span class='delim'>(</span> 4 <span class='delim'>)</span><span class='delim'>;</span>
+
<span class='comment'>// we have read the whole packet, so no longer rewind on error.</span>
+
rewind->release<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
+
<span class='lang'>return</span> handle_data_packet<span class='delim'>(</span> chennel<span class='delim'>,</span> data <span class='delim'>)</span><span class='delim'>;</span>
+
<span class='delim'>}</span>
+
<span class='delim'>}</span>
+
</code></pre></pre></dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
<span class='homogen--name'><b>set_error_mode</b></span> </dt> <dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>set_error_mode</span>(</b><code class='datatype'>int</code> <code class='argument'>m</code><b>)</b></code><br> <code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>set_error_mode</span>(</b><code class='datatype'>program</code> <code class='argument'>m</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Set the error mode of this buffer to <code>m</code>.</p> <p> If true operations that would normally return 0 (like trying to read too much) will instead throw an error. If <code>m</code> is a program a clone of it will be thrown on error.</p>
autodoc.git/traditional_manual/chapter_9.html:6877:
</dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>This function returns how many more bytes of buffer is available to rewind, or -1 on error.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Unless you add new data to the buffer using any of the add functions you can always rewind.</p> <p> You can call <code>unread(0)</code> to see how much.</p> </dd></dl>
-
<
/dd></
dl><
dl><
dt><h2 class='header'>Class <b class='ms datatype'>Stdio.
NonblockingStream
</b></h2>
+
<dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.
IOBuffer.UnwindKey
</b></h2>
</dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
-
+
<dd class='body--doc'><p>The return value of unwind_when_released()</p>
+
<p> This object will cause the buffer to unwind to the position it
+
was at when the object was created when it is released
+
(when it falls out of scope, explicit destruct does not count).</p>
+
</dd></dl>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>release</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>release</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Do not rewind if the object is released.</p>
+
<p> This is equivalent to calling destruct() on the object.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>update</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>update</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Update the location the buffer will be rewound to to the current
+
position of the buffer.</p>
+
</dd></dl>
+
</dd></dl></dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.NonblockingStream</b></h2>
+
</dt><dd><dl class='group--doc'>
+
<dt class='head--doc'>Description</dt>
<dd class='body--doc'><p>The Stdio.NonblockingStream API.</p> <p> This class exists purely for typing reasons.</p> <p> Use in types in place of <code>Stdio.File</code> where nonblocking and/or blocking stream-oriented I/O is done with the object.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Stream</code>, <code>BlockFile</code>, <code>File</code>, <code>FILE</code></p> </dd></dl> <hr />