{% extends "sega.html" %}
{% block title %}libpcp{% endblock %}
{% block body %}
<h1>libpcp</h1>
<p>A download for a precompiled libpcp can be found here: <a href="{{ROOT}}/mice/libpcp.lib">libpcp.lib
        (7b31fa7a5145b6a945655a970022df8d)</a>. The required headers can be found in the micetools source code.
<p>

<h2>Main server section</h2>
<h3>Server setup</h3>

<h4><code>e_pcpa_t pcpaInitStream(pcpa_t *stream)</code></h4>
<p>Initialise a pcp stream, allocating memory as needed.</p>

<h4><code>e_pcpa_t pcpaSetCallbackFuncBuffer(pcpa_t *stream, pcpa_cb_table_t *callback_table, uint callbacks_max)</code>
</h4>
<p>Assign a callback table to the stream in preperation for callback registration.</p>

<h4><code>e_pcpa_t pcpaSetCallbackFunc(pcpa_t *stream, char *keyword, pcpa_callback *callback, void *data)</code>
</h4>
<p>Register a callback. If a command is received where the first keyword matches <code>keyword</code>,
    <code>callback</code> is called to process it. The stream is passed as the first argument to the callback, and
    <code>data</code> as the second.
</p>

<h4><code>e_pcpa_t pcpaOpenServerWithBinary(pcpa_t *stream, int open_mode, u_short port, u_short binary_port,
    undefined4 param_5)</code></h4>
<p>Open the pcp server on <code>port</code>, and prepare to use <code>binary_port</code> for data transfer.</p>
<p>Binds to <code>0.0.0.0</code> if <code>open_mode</code> is <code>0</code>, <code>127.0.0.1</code> if it is
    <code>1</code>.
</p>
<p><code>param_5</code> is currently unknown. Pass <code>300000</code> for now; I think it's some sort of timeout.</p>

<h4>void pcpaClose(pcpa_t *stream)</h4>
<p>Close a pcp stream</p>

<h3>Server mainloop</h3>
<h4><code>e_pcpa_t pcpaServer(pcpa_t *stream, timeout_t timeout_ms)</code></h4>
<p>Perform one tick of the server. If no events occure within <code>timeout_ms</code>, this returns.</p>

<h2>Within callbacks</h2>
<h3>Reading commands</h3>
<h4><code>char* pcpaGetCommand(pcpa_t* pcpa, char* command)</code></h4>
<p>Fetch the value for a given key. Returns <code>NULL</code> if the key is not found.</p>

<h4><code>char* pcpaGetKeyword(pcpa_t* stream, uint keyword_num)</code></h4>
<p>Request the keyword at a given index. Useful for fetching the 0-index keyword when the same callback is registered to
    multiple keywords.</p>

<h3>Sending responses</h3>
<h4><code>pcp_send_data_t *pcpaSetSendPacket(pcpa_t *stream, char *keyword, char *value)</code></h4>
<p>Begin a response, setting the initial key-value pair.</p>

<h4><code>pcp_send_data_t *pcpaAddSendPacket(pcpa_t *stream, char *keyword, char *value)</code></h4>
<p>Add an additional key-value pair onto the packet being generated.</p>

<h4><code>e_pcpa_t pcpaSetBinaryMode(pcpa_t *stream, binary_mode_t binary_mode)</code></h4>
<p>Set the binary mode to either disabled, receiving, or transmitting data.</p>

<h4><code>e_pcpa_t pcpaSetBeforeBinaryModeCallBackFunc(pcpa_t *stream, pcpa_callback *callback, void *data)</code></h4>
<p>Register a callback to be called before a data transfer commences.</p>

<h4><code>e_pcpa_t pcpaSetSendBinaryBuffer(pcpa_t *stream, byte *send_buffer, size_t len)</code></h4>
<p>Set the buffer to transmit from when performing a server->consumer data transfer. Should usually be called in the
    before callback.</p>

<h4><code>e_pcpa_t pcpaSetRecvBinaryBuffer(pcpa_t *stream, byte *recv_buffer, size_t len)</code></h4>
<p>Set the buffer to receive into when performing a consumer->server data transfer. Should usually be called in the
    before callback.</p>

<h4><code>e_pcpa_t pcpaSetAfterBinaryModeCallBackFunc(pcpa_t *stream, pcpa_callback *callback, void *data)</code></h4>
<p>Register a callback to be called after a data transfer completes.</p>

{% endblock %}