259 lines
9.1 KiB
HTML
259 lines
9.1 KiB
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 %} |