docs/templates/pages/proto/cardmng.html

{% extends "konami.html" %}
{% block title %}cardmng{% endblock %}
{% block body %}
<h1><code>cardmng</code></h1>
<p>As the name might imply, this service is responsible for handling interactions with physical e-Amusement cards.
    e-Amusement currently has two different types of cards in circulation. There are classic e-Amusement cards
    making use of a magnetic stripe, and the newer RFID cards using FeliCa (these are probably what you have). They
    are identified in requests using the <code>cardtype</code> attribute as in the below table.
</p>
<p>e-Amusement cards have a "card number" and a "card id". Confusingly, neither is a number. The card number is the
    one printed on your card. The card ID is your KONAMI ID. You can (and should) read about the algorithm used for
    these IDs on <a href="../cardid.html">the Card IDs page</a>.</p>
<p>In the interest of not wasting space, <code>cardid</code> and <code>cardtype</code> will be omitted from
    individual breakdowns where their meaning is obvious.</p>

<h4>Card types:</h4>
<table>
    <thead>
        <tr>
            <td><code>cardtype</code></td>
            <td>Meaning</td>
        </tr>
    </thead>
    <tr>
        <td><code>1</code></td>
        <td>Old style grey cards</td>
    </tr>
    <tr>
        <td><code>2</code></td>
        <td>FeliCa RFID card</td>
    </tr>
    <tr>
        <td><code>3</code></td>
        <td><i>Unknown</i></td>
    </tr>
    <tr>
        <td><code>4</code></td>
        <td>Virtual card</td>
    </tr>
</table>

<ul>
    <li><code><a href="#inquire">cardmng.inquire</a></code></li>
    <li><code><a href="#getrefid">cardmng.getrefid</a></code></li>
    <li><code><a href="#bindmodel">cardmng.bindmodel</a></code></li>
    <li><code><a href="#bindcard">cardmng.bindcard</a></code></li>
    <li><code><a href="#authpass">cardmng.authpass</a></code></li>
    <li><code><a href="#getkeepspan">cardmng.getkeepspan</a></code></li>
    <li><code><a href="#getkeepremain">cardmng.getkeepremain</a></code></li>
    <li><code><a href="#getdatalist">cardmng.getdatalist</a></code></li>
</ul>

<h4>dataid? refid?</h4>
<p>Some requests use <code>refid</code>, some use <code>dataid</code>, and some use both. What exactly you use these
    values for is largely left up to the server implementer, as the game will echo them back verbatim, however here are
    three suggestions:</p>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>An ID that references the user</td>
    </tr>
    <tr>
        <td><code>data</code></td>
        <td>An ID that references the game specific data for this user/game combination</td>
    </tr>
</table>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>A session token issued during card auth</td>
    </tr>
    <tr>
        <td><code>data</code></td>
        <td>An ID that references the game specific data for this user/game combination</td>
    </tr>
</table>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>An ID that references the user</td>
    </tr>
    <tr>
        <td><code>data</code></td>
        <td>The same as refid; we can use database joins for accessing game data</td>
    </tr>
</table>

<h2 id="inquire"><code>cardmng.inquire</code></h2>
<p>Request information about a card that has been inserted or touched against a reader.</p>

<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="inquire" cardid="" cardtype="" update="" model*="" />
</call>{% endhighlight %}</pre>
<table>
    <tr>
        <td><code>update</code></td>
        <td>Should the tracked last play time be updated by this inquiry? (Just a guess)</td>
    </tr>
</table>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" refid="" dataid="" pcode=""  newflag="" binded="" expired="" ecflag="" useridflag="" extidflag="" lastupdate="" />
</response>{% endhighlight %}</pre>
<p>To handle this request, we first must lookup if this <code>cardid</code> has ever been seen by our servers
    before. If not, we abort with a <code>112</code> status. Otherwise, we proceeed to check if this card has been
    seen for this specific game. If we have never seen this card used on this game, it is possible this card was
    used with an older version of this game, and migration is supported, in which case we report as if we had found
    a profile for this game.</p>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>See section about refid and dataid</td>
    </tr>
    <tr>
        <td><code>dataid</code></td>
        <td>See section about refid and dataid</td>
    </tr>
    <tr>
        <td><code>newflag</code></td>
        <td>Inverse of <code>binded</code></td>
    </tr>
    <tr>
        <td><code>binded</code></td>
        <td>Has a profile ever been created for this game (or an older version, requiring a migration)
            (<code>1</code> or <code>0</code>)</td>
    </tr>
    <tr>
        <td><code>expired</code></td>
        <td>? Just set it to <code>0</code>.</td>
    </tr>
    <tr>
        <td><code>newflag</code></td>
        <td>? Just set it to <code>0</code>.</td>
    </tr>
</table>

<h2 id="getrefid"><code>cardmng.getrefid</code></h2>
<p>Register a new card to this server. In the process, we're also going to create a game profile.</p>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="getrefid" cardtype="" cardid="" newflag="" passwd="" model*="" />
</call>{% endhighlight %}</pre>
<table>
    <tr>
        <td><code>newflag</code></td>
        <td>?</td>
    </tr>
    <tr>
        <td><code>passwd</code></td>
        <td>The pin for this new user. <i>Should</i> always be a four digit number (and that's worth validating),
            but it's passed as a string so could feasibly be anything desired.</td>
    </tr>
</table>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" refid="" dataid="" pcode="" />
</response>{% endhighlight %}</pre>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>See section about refid and dataid</td>
    </tr>
    <tr>
        <td><code>dataid</code></td>
        <td>See section about refid and dataid</td>
    </tr>
    <tr>
        <td><code>pcode</code></td>
        <td>? Just omit this</td>
    </tr>
</table>

<h2 id="bindmodel"><code>cardmng.bindmodel</code></h2>
<p>Create a data profile for this card on the current game. Request and response should be fairly self-explanatory.</p>

<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="bindmodel" refid="" newflag="" model*="" />
</call>{% endhighlight %}</pre>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" dataid="" />
</response>{% endhighlight %}</pre>

<h2 id="bindcard"><code>cardmng.bindcard</code></h2>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="bindcard" cardtype="" newid="" refid="" model*="" />
</call>{% endhighlight %}</pre>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" />
</response>{% endhighlight %}</pre>

<h2 id="authpass"><code>cardmng.authpass</code></h2>
<p>Test a pin for a card. This request notably uses the <code>refid</code>, so required a
    <code>cardmng.inquire</code> call to be made first.
</p>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="authpass" refid="" pass="" model*="" />
</call>{% endhighlight %}</pre>
<table>
    <tr>
        <td><code>refid</code></td>
        <td>The reference we received either during <code>cardmng.inquire</code> or <code>cardmng.getrefid</code>
            (the latter for new cards)</td>
    </tr>
    <tr>
        <td><code>pass</code></td>
        <td>The pin to test. See <code>cardmng.getrefid</code>.</td>
    </tr>
</table>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" />
</response>{% endhighlight %}</pre>
<p>If the pin is valid, status should be <code>0</code>. Otherwise, <code>116</code>.</p>

<h2 id="getkeepspan"><code>cardmng.getkeepspan</code></h2>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="getkeepspan" model*="" />
</call>{% endhighlight %}</pre>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" keepspan="" />
</response>{% endhighlight %}</pre>

<h2 id="getkeepremain"><code>cardmng.getkeepremain</code></h2>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="getkeepremain" refid="" model*="" />
</call>{% endhighlight %}</pre>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status" keepremain="" />
</response>{% endhighlight %}</pre>

<h2 id="getdatalist"><code>cardmng.getdatalist</code></h2>
<h3>Request:</h3>
<pre>{% highlight "cxml" %}<call ...>
    <cardmng method="getdatalist" refid="" model*="" />
</call>{% endhighlight %}</pre>
<h3>Response:</h3>
<pre>{% highlight "cxml" %}<response>
    <cardmng status="??status">
        <item[]>
            <mcode __type="str" />
            <dataid __type="str" />
            <regtime __type="str" />
            <lasttime __type="str" />
            <exptime __type="str" />
            <expflag __type="u8" />
        </item[]>
    </cardmng>
</response>{% endhighlight %}</pre>
{% endblock %}