docs/proto/cardmng.html

232 lines
9.0 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>e-Amusement API</title>
<link rel="stylesheet" href="../styles.css">
</head>
<body>
<table>
<tr>
<td><a href="..">Contents</a></td>
<td><a href="../transport.html">Transport layer</a></td>
<td><a href="../packet.html">Packet format</a></td>
<td><a href="../protocol.html">Application Protocol</a></td>
</tr>
</table>
<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. The number is derrived from your ID using an algorithm
that I'll detail here once I get round to it.</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 class="nocode">
<thead>
<tr>
<td><code>cardtype</code></td>
<td>Meaning</td>
</tr>
</thead>
<tr>
<td><code>1</code></td>
<td>Old style magnetic stripe card</td>
</tr>
<tr>
<td><code>2</code></td>
<td>FeliCa RFID 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>
<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><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="inquire" cardid="" cardtype="" update="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<table class="nocode">
<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><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" refid="" dataid="" pcode="" newflag="" binded="" expired=" ecflag="" useridflag="" extidflag="" lastupdate="" /&gt;
&lt;/response&gt;</code></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 class="nocode">
<tr>
<td><code>refid</code></td>
<td>A reference to this card to be used in other requests</td>
</tr>
<tr>
<td><code>dataid</code></td>
<td>Appears to be set the same as <code>refid</code>; presumably to allow different keys for game state vs
login details.</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 to <code>0</code>.</td>
</tr>
</table>
<h2 id="getrefid"><code>cardmng.getrefid</code></h2>
<p>Register a new card to this server.</p>
<h3>Request:</h3>
<pre><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="getrefid" cardtype="" cardid=" newflag="" passwd="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<table class="nocode">
<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><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" refid="" dataid="" pcode="" /&gt;
&lt;/response&gt;</code></pre>
<table class="nocode">
<tr>
<td><code>refid</code></td>
<td>A reference to this card to be used in other requests</td>
</tr>
<tr>
<td><code>dataid</code></td>
<td>Appears to be set the same as <code>refid</code>; presumably to allow different keys for game state vs
login details.</td>
</tr>
<tr>
<td><code>pcode</code></td>
<td>? Not present in captured data.</td>
</tr>
</table>
<h2 id="bindmodel"><code>cardmng.bindmodel</code></h2>
<h3>Request:</h3>
<pre><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="bindmodel" refid="" newflag="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<h3>Response:</h3>
<pre><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" dataid="" /&gt;
&lt;/response&gt;</code></pre>
<h2 id="bindcard"><code>cardmng.bindcard</code></h2>
<h3>Request:</h3>
<pre><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="bindcard" cardtype="" newid="" refid="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<h3>Response:</h3>
<pre><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" /&gt;
&lt;/response&gt;</code></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><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="authpass" refid="" pass="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<table class="nocode">
<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><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" /&gt;
&lt;/response&gt;</code></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><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="getkeepspan" model*="" /&gt;
&lt;/call&gt;</code></pre>
<h3>Response:</h3>
<pre><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" keepspan="" /&gt;
&lt;/response&gt;</code></pre>
<h2 id="getkeepremain"><code>cardmng.getkeepremain</code></h2>
<h3>Request:</h3>
<pre><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="getkeepremain" refid="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<h3>Response:</h3>
<pre><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>" keepremain="" /&gt;
&lt;/response&gt;</code></pre>
<h2 id="getdatalist"><code>cardmng.getdatalist</code></h2>
<h3>Request:</h3>
<pre><code>&lt;call <i>...</i>&gt;
&lt;cardmng method="getdatalist" refid="" model*="" /&gt;
&lt;/call&gt;</code></pre>
<h3>Response:</h3>
<pre><code>&lt;response&gt;
&lt;cardmng status="<i>status</i>"&gt;
&lt;item[]&gt;
&lt;mcode __type="str" /&gt;
&lt;dataid __type="str" /&gt;
&lt;regtime __type="str" /&gt;
&lt;lasttime __type="str" /&gt;
&lt;exptime __type="str" /&gt;
&lt;expflag __type="u8" /&gt;
&lt;/item[]&gt;
&lt;/cardmng&gt;
&lt;/response&gt;</code></pre>
</body>