1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
5<META http-equiv="Content-Style-Type" content="text/css">
6<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
7<title>KPADRead</title>
8</head>
9
10<body>
11
12<h1>KPADRead</h1>
13
14<h2>Syntax</h2>
15<dl><dd><pre class="construction">
16#include &lt;revolution/kpad.h&gt;
17
18s32 KPADRead( s32 chan, KPADStatus samplingBufs[], u32 length );
19</pre></dd></dl>
20
21<h2>Arguments</h2>
22<TABLE class="arguments" border="1" >
23  <TBODY>
24    <TR>
25<TH>chan</TH>
26<TD>One of the <code>WPAD_CHAN<i>n</i></code> values.</TD>
27    </TR>
28    <TR>
29<TH>samplingBufs</TH>
30<TD>Pointer to the <a href="./KPADStatus.html"><code>KPADStatus</code></a> structure.</TD>
31    </TR>
32    <TR>
33<TH>length</TH>
34<TD>Maximum number of data sets to store. If you use the <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> function, this number cannot exceed <code>KPAD_RING_BUFS</code>. If you use the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function, this value cannot exceed the sum of <code>KPAD_RING_BUFS</code> and one-quarter the array length passed to the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function.</TD>
35    </TR>
36  </TBODY>
37</TABLE>
38
39<h2>Return Values</h2>
40<p>Returns the number of data sets that are stored.</p>
41<p>
42Note, however, that the buffer specified by <SPAN class="argument">samplingBufs</SPAN> may be used internally as a work area. Contents of the buffer may therefore be rewritten even if the return value is zero, and values stored in the buffer cannot be guaranteed. When the return value is zero, we recommend using the value obtained previously.
43</p>
44<p>
45Because the Wii console and Wii Remote use wireless communication, cases exist where signal interference in the surroundings would block any data being transmitted between prior and current calls, and the function would return zero. Even in these circumstances the Wii console and Wii Remote maintain their connection status, so <font color="red"><b>their connection status cannot be judged from the return value of this function</b></font>. To determine connection status, use the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> or <a href="../wpad/WPADSetConnectCallback.html"><code>WPADSetConnectCallback</code></a> function. It is also possible to use the return value of the <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function. <CODE>KPAD_READ_ERR_NO_DATA</code> is used as the return value when data cannot be received. <CODE>KPAD_READ_ERR_NO_CONTROLLER</code> is used as the return value when not connected.
46</p>
47
48<H2>Description</H2>
49<p>
50This function reads data in the <a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a> structure type for each controller channel. We have assumed that this function will be called for each game frame. The buffer specified by the argument stores, from newest to oldest, the data sampled from the previous call's time to the current call's time. (In other words, the newest data is always stored at the beginning of the buffer.) However, in the case of button information only, if the button processing method obtained using the <CODE>KPADGetButtonProcMode</CODE> function is <CODE>KPAD_BUTTON_PROC_MODE_LOOSE</CODE>, only the most recent values are accessed when the <CODE>KPADRead</CODE> or <CODE>KPADReadEx</CODE> functions are called, and those values are copied into all the current-frame sampling buffers.
51</p>
52<p>
53The buffer specified by <SPAN class="argument">samplingBufs</SPAN> is sometimes used internally as a work area. Because of this, it is possible for buffer contents to be overwritten even when there was no data.
54</p>
55
56<h2>See Also</h2>
57<P>
58<a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a><BR> <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a>
59</p>
60
61<H2>Revision History</H2>
62<P>
632009/01/07 Added a description of <code>KPADReadEx</code>.<br>2008/06/13 Revised the explanation of <SPAN class="argument">length</SPAN>. Added explanation of the differences caused by different button processing methods.<br>2008/06/03 Deleted error codes. <br>2008/04/17 Revised the description of <SPAN class="argument">length</SPAN>. Added error codes.<br> 2007/08/27 Added passages to the effect that this function's return value cannot be used to judge connection status and to use prior obtained values when the return value is zero.<br>2006/10/25 Revised the description to match KPAD version 2.<br>2006/08/xx Added a link under <B>See Also</B>.<br>2006/03/01 Initial version.<br>
64</P>
65
66<hr><p>CONFIDENTIAL</p></body>
67</html>