1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - WXC - include -
3   File:     wxc.h
4 
5   Copyright 2005-2009 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16  *---------------------------------------------------------------------------*/
17 
18 #ifndef	NITRO_WXC_H_
19 #define	NITRO_WXC_H_
20 
21 
22 #include <nitro.h>
23 
24 #include <nitro/wxc/common.h>
25 #include <nitro/wxc/protocol.h>
26 #include <nitro/wxc/driver.h>
27 #include <nitro/wxc/scheduler.h>
28 
29 #include <nitro/wxc/wxc_protocol_impl_wxc.h>
30 
31 
32 /*****************************************************************************/
33 /* Constants */
34 
35 /* Size of internal work memory necessary for the library */
36 #define WXC_WORK_SIZE              0xA000
37 
38 
39 /*****************************************************************************/
40 /* Functions */
41 
42 #ifdef  __cplusplus
43 extern "C" {
44 #endif
45 
46 
47 /*---------------------------------------------------------------------------*
48   Name:         WXC_Init
49 
50   Description:  Initializes the library.
51 
52   Arguments:    work: Work memory used in the library.
53                       The memory must be at least WXC_WORK_SIZE bytes and 32-byte aligned.
54 
55                 callback: Sends notifications for the various library system states
56                           Pointer to the callback
57                 dma: DMA channel used in the library
58 
59   Returns:      None.
60  *---------------------------------------------------------------------------*/
61 void    WXC_Init(void *work, WXCCallback callback, u32 dma);
62 
63 /*---------------------------------------------------------------------------*
64   Name:         WXC_Start
65 
66   Description:  Starts the wireless operation of the library.
67 
68   Arguments:    None.
69 
70   Returns:      None.
71  *---------------------------------------------------------------------------*/
72 void    WXC_Start(void);
73 
74 /*---------------------------------------------------------------------------*
75   Name:         WXC_Stop
76 
77   Description:  Stops the wireless operation of the library.
78 
79   Arguments:    None.
80 
81   Returns:      None.
82  *---------------------------------------------------------------------------*/
83 void    WXC_Stop(void);
84 
85 /*---------------------------------------------------------------------------*
86   Name:         WXC_End
87 
88   Description:  Closes the library.
89 
90   Arguments:    None.
91 
92   Returns:      None.
93  *---------------------------------------------------------------------------*/
94 void    WXC_End(void);
95 
96 /*---------------------------------------------------------------------------*
97   Name:         WXC_GetStateCode
98 
99   Description:  Gets the current status of the library.
100 
101   Arguments:    None.
102 
103   Returns:      WXCStateCode type that shows the current library status.
104  *---------------------------------------------------------------------------*/
105 WXCStateCode WXC_GetStateCode(void);
106 
107 /*---------------------------------------------------------------------------*
108   Name:         WXC_IsParentMode
109 
110   Description:  Determines whether the current wireless state is parent.
111                 Only valid in the WXC_STATE_ACTIVE state.
112 
113   Arguments:    None.
114 
115   Returns:      If the wireless status is parent mode, TRUE. If it is child mode, FALSE.
116  *---------------------------------------------------------------------------*/
117 BOOL    WXC_IsParentMode(void);
118 
119 /*---------------------------------------------------------------------------*
120   Name:         WXC_GetParentParam
121 
122   Description:  Refers to the WMParentParam structure for the current wireless state.
123                 This is only valid in the WXC_STATE_ACTIVE state when the WXC_IsParentMode function returns TRUE.
124 
125 
126   Arguments:    None.
127 
128   Returns:      WMParentParam structure.
129  *---------------------------------------------------------------------------*/
130 const WMParentParam *WXC_GetParentParam(void);
131 
132 /*---------------------------------------------------------------------------*
133   Name:         WXC_GetParentBssDesc
134 
135   Description:  Refers to the WMBssDesc structure for the current connection target.
136                 This is only valid in the WXC_STATE_ACTIVE state when the WXC_IsParentMode function returns FALSE.
137 
138 
139   Arguments:    None.
140 
141   Returns:      WMBssDesc structure
142  *---------------------------------------------------------------------------*/
143 const WMBssDesc *WXC_GetParentBssDesc(void);
144 
145 /*---------------------------------------------------------------------------*
146   Name:         WXC_GetUserBitmap
147 
148   Description:  Gets the currently connected user's status with a bitmap.
149                 If communications are not established, it returns 0.
150 
151   Arguments:    None.
152 
153   Returns:      WMBssDesc structure
154  *---------------------------------------------------------------------------*/
155 u16     WXC_GetUserBitmap(void);
156 
157 /*---------------------------------------------------------------------------*
158   Name:         WXC_GetCurrentGgid
159 
160   Description:  Gets the selected GGID in the current connection.
161                 If communications are not established, it returns 0.
162                 The current communications status can be determined by the WXC_GetUserBitmap function's return value.
163 
164   Arguments:    None.
165 
166   Returns:      The selected GGID in the current connection.
167  *---------------------------------------------------------------------------*/
168 u32     WXC_GetCurrentGgid(void);
169 
170 /*---------------------------------------------------------------------------*
171   Name:         WXC_GetOwnAid
172 
173   Description:  Gets its own AID in the current connection.
174                 If communications are not established, it returns an inconstant value.
175                 The current communications status can be determined by the WXC_GetUserBitmap function's return value.
176 
177   Arguments:    None.
178 
179   Returns:      Its own AID in the current connection.
180  *---------------------------------------------------------------------------*/
181 u16     WXC_GetOwnAid(void);
182 
183 /*---------------------------------------------------------------------------*
184   Name:         WXC_GetUserInfo
185 
186   Description:  Gets the user information of the user currently connected.
187                 You must not change the data indicated by the returned pointer.
188 
189   Arguments:    aid: User AID that gets information
190 
191   Returns:      If the specified AID is valid, user information. Otherwise, NULL.
192  *---------------------------------------------------------------------------*/
193 const WXCUserInfo *WXC_GetUserInfo(u16 aid);
194 
195 /*---------------------------------------------------------------------------*
196   Name:         WXC_SetChildMode
197 
198   Description:  Sets wireless to only run as a child.
199                 This function must be called before the WXC_Start function is called.
200 
201   Arguments:    enable: If it can only be run on the child side, TRUE
202 
203   Returns:      None.
204  *---------------------------------------------------------------------------*/
205 void    WXC_SetChildMode(BOOL enable);
206 
207 /*---------------------------------------------------------------------------*
208   Name:         WXC_SetParentParameter
209 
210   Description:  Specifies wireless connection settings
211                 The configuration contents are only used when in parent mode.
212                 When connected in child mode, the device follows the parent's settings.
213                 This function is optional. Call it before the WXC_Start function only when necessary.
214 
215 
216   Arguments:    sendSize: Parent send size.
217                           It must be at least WXC_PACKET_SIZE_MIN and no more than WXC_PACKET_SIZE_MAX.
218 
219                 recvSize: Parent receive size.
220                           It must be at least WXC_PACKET_SIZE_MIN and no more than WXC_PACKET_SIZE_MAX.
221 
222                 maxEntry: Maximum number of connected players.
223                           The current implementation only supports a specified value of 1.
224 
225   Returns:      If the settings are valid, they are applied internally, and TRUE is returned. Otherwise, a warning message is sent to debug output, and FALSE is returned.
226 
227  *---------------------------------------------------------------------------*/
228 BOOL    WXC_SetParentParameter(u16 sendSize, u16 recvSize, u16 maxEntry);
229 
230 /*---------------------------------------------------------------------------*
231   Name:         WXC_RegisterDataEx
232 
233   Description:  Registers data for exchange
234 
235   Arguments:    ggid: GGID of the registered data
236                 callback: Callback function to the user (invoked when data exchange is complete)
237                 send_ptr: Pointer to registered data
238                 send_size: Size of registered data
239                 recv_ptr: Pointer to the receive buffer
240                 recv_size: Receive buffer size
241                 type: String representing the protocol
242 
243   Returns:      None.
244  *---------------------------------------------------------------------------*/
245 void    WXC_RegisterDataEx(u32 ggid, WXCCallback callback, u8 *send_ptr, u32 send_size,
246                            u8 *recv_ptr, u32 recv_size, const char *type);
247 
248 #define WXC_RegisterData(...) SDK_OBSOLETE_FUNCTION("WXC_RegisterData() is obsolete. use WXC_RegisterCommonData()")
249 
250 /*---------------------------------------------------------------------------*
251   Name:         WXC_RegisterCommonData
252 
253   Description:  Registers the conversion data as a shared chance encounter communication specification.
254 
255   Arguments:    ggid: GGID of the registered data
256                 callback: Callback function to the user (invoked when data exchange is complete)
257                 send_ptr: Pointer to registered data
258                 send_size: Size of registered data
259                 recv_ptr: Pointer to the receive buffer
260                 recv_size: Receive buffer size
261 
262   Returns:      None.
263  *---------------------------------------------------------------------------*/
WXC_RegisterCommonData(u32 ggid,WXCCallback callback,u8 * send_ptr,u32 send_size,u8 * recv_ptr,u32 recv_size)264 static inline void WXC_RegisterCommonData(u32 ggid, WXCCallback callback,
265                                           u8 *send_ptr, u32 send_size,
266                                           u8 *recv_ptr, u32 recv_size)
267 {
268     WXC_RegisterDataEx((u32)(ggid | WXC_GGID_COMMON_BIT), callback, send_ptr,
269                              send_size, recv_ptr, recv_size, "COMMON");
270 }
271 
272 /*---------------------------------------------------------------------------*
273   Name:         WXC_SetInitialData
274 
275   Description:  The data block used for every exchange is set by the first exchange.
276 
277   Arguments:    ggid: GGID of the registered data
278                 send_ptr: Pointer to registered data
279                 send_size: Size of registered data
280                 recv_ptr: Pointer to the receive buffer
281                 recv_size: Receive buffer size
282 
283   Returns:      None.
284  *---------------------------------------------------------------------------*/
285 void    WXC_SetInitialData(u32 ggid, u8 *send_ptr, u32 send_size, u8 *recv_ptr, u32 recv_size);
286 
287 /*---------------------------------------------------------------------------*
288   Name:         WXC_AddData
289 
290   Description:  Data is configured by adding it to a completed block data exchange.
291 
292   Arguments:    send_buf: Send buffer
293                 send_size: Send buffer size
294                 recv_buf: Receive buffer
295                 recv_max: Receive buffer size
296 
297   Returns:      None.
298  *---------------------------------------------------------------------------*/
299 void    WXC_AddData(const void *send_buf, u32 send_size, void *recv_buf, u32 recv_max);
300 
301 /*---------------------------------------------------------------------------*
302   Name:         WXC_UnregisterData
303 
304   Description:  Deletes data for exchange from registration
305 
306   Arguments:    ggid: GGID related to the deleted block
307 
308   Returns:      None.
309  *---------------------------------------------------------------------------*/
310 void    WXC_UnregisterData(u32 ggid);
311 
312 /*---------------------------------------------------------------------------*
313   Name:         WXCi_SetSsid
314 
315   Description:  Configures the SSID as a child when connecting.
316                 Internal function.
317 
318   Arguments:    buffer: SSID data to configure
319                 length: SSID data length
320                         Must be less than WM_SIZE_CHILD_SSID.
321 
322   Returns:      None.
323  *---------------------------------------------------------------------------*/
324 void    WXCi_SetSsid(const void *buffer, u32 length);
325 
326 
327 #ifdef  __cplusplus
328 }       /* extern "C" */
329 #endif
330 
331 
332 #endif /* NITRO_WXC_H_ */
333 
334 /*---------------------------------------------------------------------------*
335   End of file
336  *---------------------------------------------------------------------------*/
337