1 /*---------------------------------------------------------------------------*
2 Project: Horizon
3 File: uds_Api.h
4
5 Copyright (C)2009 Nintendo Co., Ltd. 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 $Rev: 26639 $
14 *---------------------------------------------------------------------------*/
15
16 #ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_
17 #define INCLUDE_NN_UDS_CTR_UDS_API_H_
18
19 /*! @file
20 @brief UDS ライブラリの API 群です。
21 */
22
23 #include <nn/uds/CTR/uds_Type.h>
24 #include <nn/uds/CTR/uds_Result.h>
25 #include <nn/uds/CTR/uds_NetworkDescription.h>
26
27 namespace nn {
28 namespace uds {
29 namespace CTR {
30
31 /*!
32 @name 初期化/終了処理関連
33 @{
34 */
35
36 /*!
37 @brief UDS ライブラリを初期化します。他の通信機能を使用中には成功しません。
38 なお、バックグラウンドでの通信処理を終了させ、 @ref Finalize を実行するまで UDS ライブラリが通信デバイスを
39 占有するための処理を行うため、長時間ブロックする可能性があります。
40
41 @param[out] pStatusUpdateEvent 接続状態の更新通知用イベントです。ライブラリ内で自動リセットイベントとして Initialize されます。
42 @param[in] receiveBuffer UDS ライブラリが使用する受信バッファの先頭を指すポインタです。UDS ライブラリは内部で、実際に無線通信による
43 データ受信をしてからアプリが取得するまで受信したデータを格納しておくバッファを必要とします。
44 4096 バイト整合されたバッファを指定してください。デバイスメモリは使用できません。
45 @param[in] bufferSize 受信バッファのサイズです。4096 の倍数を指定してください。
46 @return 関数の実行結果を返します。
47 */
48 nn::Result Initialize( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize );
49
50 /*!
51 @brief UDS ライブラリを終了します。 @ref Initialize で指定した受信バッファは本 API が完了するまで UDS ライブラリが使用します。
52 また、 @ref Initialize で受け取る接続状態の更新通知用イベントはここで Finalize されます。
53 @return 無し
54 */
55 void Finalize ();
56
57 /*!
58 @}
59 */
60 /*!
61 @name ネットワークの構築/破棄、およびネットワークの接続/切断
62 @{
63 */
64
65 /*!
66 @brief 業務部から割り当てられた 20bit のユニーク ID から UDS 通信で使用する
67 32bit 値 (ローカル通信 ID) を生成します。
68
69 @param[in] id 業務部から割り当てられた 20bit の ユニークID です。複数タイトル間で通信したい場合はどちらか片方のユニーク ID を指定してください。
70 @param[in] isTrial ユニークID が製品版と体験版で共通であるための対応です。製品版-体験版間での通信を行いたくない場合に true を指定してください。
71 */
72 bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isTrial = false);
73
74 /*!
75 @brief 新規にローカルネットワークを構築します。
76
77 @param[in] subId 通信モード識別用 ID です。アプリが自由に設定可能です。
78 @param[in] maxEntry ネットワークに接続できるノードの最大数です。自身を含み、最大 12 まで指定可能です。
79 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
80 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。
81 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
82 @param[in] passphraseLength passphrase の長さです。255(暫定) 未満を指定してください。
83 @param[in] channel 通信に使用するチャンネルです。0(自動), 1,6,11ch のいずれかを指定してください。製品実機で実行した場合は常にチャンネルを自動で選択します。
84 @return 関数の実行結果を返します。成功した場合、ネットワークが構築されます。
85 */
86 nn::Result CreateNetwork(
87 u8 subId,
88 u8 maxEntry,
89 bit32 localId,
90 const char passphrase[],
91 size_t passphraseLength,
92 u8 channel = 0 );
93
94 /*!
95 @brief 周囲のネットワークを探索します。
96
97 @param[out] pBuffer 発見したネットワークの情報の格納先です。
98 @param[in] bufferSize バッファの大きさです。ネットワーク 1つあたり 1KB 程度とお見積もりください。
99 @param[in] subId アプリが自由に設定可能な通信モード識別用 ID です。0xff を指定するとあらゆる SubID を検索します。
100 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
101 @param[in] channel UDS が使用する全てのチャンネルをスキャンします。特定のチャンネルのみスキャンしたい場合にのみセットしてください。
102 (0: UDS が使用する全チャンネル (1,6,11ch) をスキャン)
103 @param[in] scanTime 1チャンネルあたりのスキャン時間です。通常指定する必要はありません(0: 110ミリ秒)
104 @return 関数の実行結果を返します。
105 */
106 nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel = 0, u16 scanTime = 0 );
107
108 /*!
109 @brief 既存のネットワークに接続します。
110
111 @param[in] networkDescription ネットワーク情報です。スキャン結果から取得します。
112 @param[in] type 接続タイプです。
113 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵です。
114 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
115 @param[in] passphraseLength passphrase の長さです。255(暫定) 未満を指定してください。
116 @return 関数の実行結果を返します。成功した場合、ネットワークに接続されます。
117 */
118 nn::Result ConnectNetwork(
119 const NetworkDescription& networkDescription,
120 ConnectType type,
121 const char passphrase[],
122 size_t passphraseLength );
123
124 /*!
125 @brief 指定したノードをネットワークから追放します。 Master のみ実行可能です。
126
127 @param[in] nodeId 追放したいノードID です。BROADCAST_NODE_ID を指定した場合、接続中の全ての Client を追放します。
128 @return 関数の実行結果を返します。
129 */
130 nn::Result EjectClient ( u16 nodeId );
131
132 /*!
133 @brief 接続している全ての Spectator をネットワークから追放します。
134 本 API を実行後は新規に Spectator が接続することは出来ない状態になります。
135 再度 Spectator の接続を許可したい場合は @ref AllowToSpectate を実行してください。
136 Master のみ実行可能です。
137
138 @return 関数の実行結果を返します。
139 */
140 nn::Result EjectSpectator ( void );
EjectAudience(void)141 inline nn::Result EjectAudience ( void ){ return EjectSpectator(); }
142
143 /*!
144 @brief Spectator のネットワークへの接続を許可します。
145 デフォルトでは許可された状態になっているため、 @ref EjectSpectator を使用後に
146 再度 Spectator をネットワークに接続させたい場合にご使用下さい。
147 Master のみ実行可能です。
148
149 @return 関数の実行結果を返します。
150 */
151 nn::Result AllowToSpectate();
152
153 /*!
154 @brief 接続中の Client 全てを追放してローカルネットワークを終了します。
155 Master のみ実行可能です。
156
157 @return 関数の実行結果を返します。
158 */
159 nn::Result DestroyNetwork ( void );
160
161 /*!
162 @brief 接続中のネットワークから離脱します。意図しない切断が発生した場合も、再接続前に実行することが望ましいです。
163 Client および Spectator のみ実行可能です。
164
165 @return 関数の実行結果を返します。
166 */
167 nn::Result DisconnectNetwork ( void );
168
169 /*!
170 @}
171 */
172 /*!
173 @name データ送受信関連
174 @{
175 */
176
177 /*!
178 @brief ネットワークの端点 (endpoint) を生成し、対応する descriptor を返します。
179 [暫定仕様] endpoint は現在 16 個生成可能です。
180
181 @param[out] pEndpointDesc 生成する endpoint を示す descriptor です。
182 @return 関数の実行結果を返します。
183 */
184 nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc );
185
186 /*!
187 @brief 指定した相手の指定したポートにデータを送信します。
188 送信処理が完了するまでブロックします。
189
190 @param[in] endpointDesc 使用する endpoint を示す descriptor です。
191 @param[in] data 送信するデータのポインタです。
192 @param[in] dataSize 送信するデータのサイズです。最大送信サイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byte です。
193 @param[in] destNodeId 送信先です。 BROADCAST_NODE_ID を指定するとデータはブロードキャストされます。
194 @param[in] port 使用するポートです。ポート番号0x00はシステム側で予約されているため使用できません。
195 @param[in] option 送信オプションです。 @ref NO_WAIT を指定すると UDS 内部の送信バッファに貯めずに即時無線送信を行います。
196 @return 関数の実行結果を返します。
197 */
198 nn::Result SendTo ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 );
199
200
201 /*!
202 @brief descriptor とポート、ノードID を結びつけます。その際システムは受信用バッファを作成し、以降データを受信できるようになります。
203
204 @param[in] pEndpointDesc 使用する Endpoint を示す descriptor です。
205 @param[in] srcNodeId 結びつけるノード ID です。BROADCAST_NODE_ID を指定すると全てのノードと結びつけられます。
206 @param[in] port 結びつけるポート番号です。ポート番号0x00はシステム側で予約されているため使用できません。
207 @param[in] receiveBufferSize 確保する受信バッファのサイズです。@ref Initialize で確保したメモリブロックから確保されますので、受信バッファの合計が
208 確保したメモリブロックのサイズよりも大きくならないよう注意してください。
209 デフォルトでは @ref UDS_PACKET_PAYLOAD_MAX_SIZE のデータの8倍を確保します。
210 データサイズを指定する場合は内部で32バイト毎にメモリを確保しているため、32の倍数を指定すると効率的です。
211 @return 関数の実行結果を返します。
212 */
213 nn::Result Attach ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize =(UDS_PACKET_PAYLOAD_MAX_SIZE*8) );
214
215 /*!
216 @brief データを受信します。(送信元アドレス取得機能なし)
217
218 @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
219 @param[out] pBuffer 受信データの格納先です。4 バイト整合されたバッファを指定してください。
220 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
221 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。
222 @param[in] option 受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。
223 指定しないとデータを受信、もしくはエラーが発生するまで終了しません。
224 @return 関数の実行結果を返します。
225 */
226 nn::Result Receive ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 );
227
228 /*!
229 @brief データを受信します。(送信元アドレス取得機能付き)
230
231 @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
232 @param[out] pBuffer 受信データの格納先です。4 バイト整合されたバッファを指定してください。
233 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
234 @param[out] pSrcNodeId 送信元ノードIDです。
235 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。
236 @param[in] option 受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。
237 指定しないとデータを受信、もしくはエラーが発生するまで終了しません。
238 @return 関数の実行結果を返します。
239 */
240 nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 );
241
242 /*!
243 @brief endpoint を破棄します。同時に @ref Attach で作成した受信用バッファを解放します。
244
245 @param[in] pEndpoint endpoint を示す descriptor です。
246 @return 関数の実行結果を返します。
247 */
248 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc );
249
250 /*!
251 @}
252 */
253
254 /*!
255 @brief 自身の MAC アドレスを取得します。
256
257 @param[out] pMacAddress 自身の MAC アドレスです。
258 @return 関数の実行結果を返します。
259 */
260 nn::Result GetMacAddress( bit8 pMacAddress[MAC_ADDRESS_SIZE] );
261
262 /*!
263 @brief 現在の接続状態を返します。
264
265 @param[out] pStatus 現在の接続状態です。
266 @return 関数の実行結果を返します。
267 */
268 nn::Result GetConnectionStatus( ConnectionStatus* pStatus );
269
270 /*!
271 @brief 現在のリンクレベルを取得します。
272
273 @param[out] pLinkLevel 現在のリンクレベルです。
274 @return 関数の実行結果を返します。
275 */
276 nn::Result GetLinkLevel( LinkLevel* pLinkLevel );
277
278 /*!
279 @brief 現在のリンクレベルを取得します。
280
281 @return 現在のリンクレベルです。
282 */
283 LinkLevel GetLinkLevel();
284
285 /*!
286 @brief 指定したノードの情報を取得します。
287
288 @param[out] pNodeInfo ノードの情報です。将来、格納するデータに対応した構造体を用意する予定です。
289 @param[in] nodeId 対象となるノードのノードIDです。
290 @return 関数の実行結果を返します。
291 */
292 nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId );
293
294 /*!
295 @brief 省電力モードを変更します。(通信開始前、もしくは通信中に変更することが出来ます)
296 この設定は Master でのみ変更可能で、Client / Spectator は Master の設定に従います。
297 現在未実装で、実行すると必ず失敗します。
298
299 @param[in] mode 省電力モードです。省電力モードを有効にすると若干接続性が悪くなる場合があります。
300 @return 関数の実行結果を返します。
301 */
302 nn::Result SetPowerSaveMode(PowerSaveMode mode);
303
304 /*!
305 @brief ネットワークの属性を変更します。
306 現在未実装で、実行すると必ず失敗します。
307
308 @param[in] flag ネットワークの属性です。複数の属性を OR で指定します。
309 @return 関数の実行結果を返します。
310 */
311 nn::Result SetNetworkAttribute( bit16 flag );
312
313 /*!
314 @brief ビーコンに任意データ (最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte) をセットします。Master でのみ実行可能です。
315 このデータは他の機器が Scan した際、 Client/Spectator として接続中に取得可能です。
316
317 @param[in] pData セットしたいデータのポインタです。
318 @param[in] dataSize セットしたいデータのサイズです。@ref NET_DESC_APPDATA_SIZE_MAX 未満の数値を指定してください。
319 @return 関数の実行結果を返します。
320 */
321 nn::Result SetApplicationDataToBeacon ( const void* pData, size_t dataSize );
322
323 /*!
324 @brief ビーコンにセットされたデータ (最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte) を取得します。
325 ネットワークに接続中にのみ実行可能です。 Client/Spectator として通信中にデータが更新されてもアプリには
326 通知されませんのでご注意下さい。
327
328 @param[out] pBuffer データの格納先です。
329 @param[out] pDataSize データのサイズです。
330 @param[in] bufferSize バッファの大きさです。受け取るデータのサイズは送信側が自由に変更できますので、基本的には @ref NET_DESC_APPDATA_SIZE_MAX Byte を指定してください。
331 @return 関数の実行結果を返します。
332 */
333 nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize );
334
335 namespace detail{
336 /*!
337 :private
338 @brief endpoint を破棄します。同時に @ref Attach で作成した受信用バッファを解放します。
339 ( 無線による受信は成功したものの、UDS の受信バッファ溢れによってロストしたパケットについての情報を取得できるデバッグ用 API です)
340
341 @param[in] pEndpoint endpoint を示す descriptor です。
342 @param[out] pReport 破棄した Endpoint に到達したパケットに関する情報です。
343 @return 関数の実行結果を返します。
344 */
345 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport );
346
347
348 /*!
349 :private
350 @brief システムプロセス用 Initialize()
351 */
352 nn::Result InitializeCore( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize );
353
354 /*!
355 :private
356 @brief システムプロセス用 Finalize()
357 */
358 void FinalizeCore();
359
360
361 } // end of namespace detail
362
363 } // end of namespace CTR
364 } // end of namespace uds
365 } // end of namespace nn
366
367
368
369 #endif // ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_
370