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: 33748 $
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
39 バックグラウンドでの通信処理を終了させ、 @ref Finalize を実行するまで UDS ライブラリが通信デバイスを
40 占有する処理を行うため、長時間ブロックする可能性があります。
41
42 @param[out] pStatusUpdateEvent 接続状態の更新通知用イベントです。ライブラリ内で自動リセットイベントとして Initialize されます。
43 @param[in] receiveBuffer UDS ライブラリが使用する受信バッファの先頭を指すポインタです。
44 4096 Byte整合されたバッファを指定してください。デバイスメモリは使用できません。
45 バッファに指定したメモリ領域は @ref Finalize が実行完了するまでアクセスが禁止されます。
46 @param[in] bufferSize 受信バッファのサイズです。4096 の倍数を指定してください。
47 @return 関数の実行結果を返します。以下に挙げる Result を返します。
48 @retval ResultSuccess 初期化に成功しました。
49 @retval ResultAlreadyOccupiedWirelessDevice 既に別の通信が行われていて、新規に UDS 通信を開始できない状態です。
50 @retval ResultOutOfResource システムリソースが足りません。
51 @retval ResultWirelessOff 無線 OFF モードです。
52 */
53 nn::Result Initialize( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize);
54
55 /*!
56 @brief UDS ライブラリを終了します。実行後、他の通信機能を利用可能になります。
57
58 @ref Initialize で指定した受信バッファは本 API が実行完了した以降はアプリからアクセス可能になります。
59
60 @ref Initialize で受け取る接続状態の更新通知用イベントはここで Finalize されます。
61 @return 無し
62 */
63 void Finalize ();
64
65 /*!
66 @}
67 */
68 /*!
69 @name ネットワークの構築/破棄、およびネットワークの接続/切断
70 @{
71 */
72
73 /*!
74 @brief ユニーク ID からローカル通信 ID を生成します。
75
76 業務部から割り当てられた 20bit のユニーク ID から UDS 通信で使用する 32bit 値 (ローカル通信 ID) を生成します。
77
78 @param[in] uniqueId ユニークID です。複数タイトル間で通信したい場合はどちらか片方のユニーク ID を指定してください。
79 @param[in] isTrial ユニークID が製品版と体験版で共通だった場合の対処用フラグです。製品版-体験版間での通信を行いたくない場合、
80 体験版側を true を指定してください。製品版は常に false が指定されるようご注意下さい。
81 @return ローカル通信 IDです。
82 */
83 bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isTrial = false);
84
85 /*!
86 @brief 新規にネットワークを構築します。
87
88 @param[in] subId 通信モード識別用 ID です。アプリが自由に設定可能です。
89 @param[in] maxEntry ネットワークに接続できるノードの最大数です。自身を含み、最大 12 まで指定可能です。
90 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
91 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。
92 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
93 @param[in] passphraseLength passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。
94
95 @return 関数の実行結果を返します。以下に挙げる Result を返します。
96 @retval ResultSuccess ローカル通信の構築に成功し Master として動作を開始しました。
97 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
98 @retval ResultInvalidState 実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
99 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
100 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
101 @retval 上記以外 上記以外の理由で失敗しました。
102 */
103 nn::Result CreateNetwork(
104 u8 subId,
105 u8 maxEntry,
106 bit32 localId,
107 const char passphrase[],
108 size_t passphraseLength );
109
110 /*!
111 @brief 新規にネットワークを構築します。 本関数は、開発時に無線通信に使用するチャンネルを指定したい場合を考慮して用意されたデバッグ用関数です。
112 製品実機では channel 引数は無視される点に注意してご利用下さい。
113
114 @param[in] subId 通信モード識別用 ID です。アプリが自由に設定可能です。
115 @param[in] maxEntry ネットワークに接続できるノードの最大数です。自身を含み、最大 12 まで指定可能です。
116 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
117 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。
118 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
119 @param[in] passphraseLength passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。
120 @param[in] channel 通信に使用するチャンネルです。0(自動), 1,6,11ch のいずれかを指定してください。製品実機で実行した場合は常にチャンネルを自動で選択します。
121
122 @return 関数の実行結果を返します。以下に挙げる Result を返します。
123 @retval ResultSuccess ローカル通信の構築に成功し Master として動作を開始しました。
124 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
125 @retval ResultInvalidState 実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
126 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
127 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
128 @retval 上記以外 上記以外の理由で失敗しました。
129 */
130 nn::Result CreateNetwork(
131 u8 subId,
132 u8 maxEntry,
133 bit32 localId,
134 const char passphrase[],
135 size_t passphraseLength,
136 u8 channel );
137
138 /*!
139 @brief 周囲のネットワークを探索します。
140
141 @param[out] pBuffer 発見したネットワークの情報の格納先です。
142 @param[in] bufferSize バッファの大きさです。ネットワーク 1つあたり 1KB 程度とお見積もりください。
143 @param[in] subId アプリが自由に設定可能な通信モード識別用 ID です。0xff を指定するとあらゆる SubID を検索します。
144 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
145
146 @return 関数の実行結果を返します。以下に挙げる Result を返します。
147 @retval ResultSuccess ローカル通信の構築に成功し バッファに見つかったネットワークの情報が格納されます。
148 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
149 @retval ResultInvalidState 実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
150 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
151 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
152 @retval 上記以外 上記以外の理由で失敗しました。
153 */
154 nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId );
155
156 /*!
157 :private
158 @brief 周囲のネットワークを探索します。 スキャンチャンネルを指定しなければならない場合などの特殊な場合にのみ使用する機能です。
159
160 @param[out] pBuffer 発見したネットワークの情報の格納先です。
161 @param[in] bufferSize バッファの大きさです。ネットワーク 1つあたり 1KB 程度とお見積もりください。
162 @param[in] subId アプリが自由に設定可能な通信モード識別用 ID です。0xff を指定するとあらゆる SubID を検索します。
163 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
164 @param[in] channel UDS が使用する全てのチャンネルをスキャンします。特定のチャンネルのみスキャンしたい場合にのみセットしてください。
165 (0: UDS が使用する全チャンネル (1,6,11ch) をスキャン)
166 @param[in] scanTime 1チャンネルあたりのスキャン時間です。通常指定する必要はありません(0: 110ミリ秒)
167
168 @return 関数の実行結果を返します。以下に挙げる Result を返します。
169 @retval ResultSuccess ローカル通信の構築に成功し バッファに見つかったネットワークの情報が格納されます。
170 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
171 @retval ResultInvalidState 実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
172 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
173 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
174 @retval 上記以外 上記以外の理由で失敗しました。
175 */
176 nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel, u16 scanTime = 0 );
177
178 /*!
179 @brief 既存のネットワークに接続します。
180
181 @param[in] networkDescription ネットワーク情報です。スキャン結果から取得します。
182 @param[in] type 接続タイプです。
183 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵です。
184 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
185 @param[in] passphraseLength passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。
186
187 @return 関数の実行結果を返します。以下に挙げる Result を返します。
188 @retval ResultSuccess 接続に成功し、指定した接続タイプとして動作を開始しました。
189 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
190 @retval ResultNotFoundNetwork 接続対象のネットワークが見つかりませんでした。ネットワークが既に破棄されている、もしくは通信範囲から外れた場合に返ります。
191 @retval ResultAlreadyNetworkIsFull 既にネットワークのノード数が最大接続数に達していました。ノード数が減少しない限り接続できません。
192 @retval ResultDeniedFromMaster Master に接続を拒否されました。Master が接続を拒否している場合に返ります。passphrase が間違っている場合も返ります。
193 @retval ResultConnectionTimeout 一定時間以内に接続が成立しませんでした。電波状況が悪い場合や、Master に過度の通信負荷がかかっている場合に返ります。
194 @retval ResultInvalidState 実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
195 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
196 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
197 @retval 上記以外 上記以外の理由で失敗しました。
198 */
199 nn::Result ConnectNetwork(
200 const NetworkDescription& networkDescription,
201 ConnectType type,
202 const char passphrase[],
203 size_t passphraseLength );
204
205 /*!
206 @brief 指定したノードをネットワークから追放します。 Master のみ実行可能です。
207
208 @param[in] nodeId 追放したいノードID です。BROADCAST_NODE_ID を指定した場合、接続中の全ての Client を追放します。
209
210 @return 関数の実行結果を返します。以下に挙げる Result を返します。
211 @retval ResultSuccess 対象の Client はネットワークから追放されました。
212 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
213 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
214 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
215 @retval 上記以外 上記以外の理由で失敗しました。
216 */
217 nn::Result EjectClient ( u16 nodeId );
218
219 /*!
220 @brief Client のネットワークへの接続を不許可にします。現在接続中の Client には影響しません。
221
222 通信対戦中は新規に Client が接続することを拒否したい、と言うような用途を想定した接続拒否機能です。
223 再び接続を許可したい場合は @ref AllowToConnect を実行してください。
224 Master のみ実行可能です。
225
226 @param[in] isDisallowToReconnect false の場合、一度 Master に接続したことのある Client の再接続が可能になります。
227
228 @return 関数の実行結果を返します。以下に挙げる Result を返します。
229 @retval ResultSuccess 処理に成功しました。
230 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
231 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
232 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
233 @retval 上記以外 上記以外の理由で失敗しました。
234 */
235 nn::Result DisallowToConnect(bool isDisallowToReconnect = false);
236
237 /*!
238 @brief Client のネットワークへの接続を許可します。
239
240 @ref DisallowToConnect で拒否した、Client の接続を再開するための関数です。
241 この関数では @ref EjectSpectator による Spectator の接続拒否状態は解除されません。
242 Master のみ実行可能です。
243
244 @return 関数の実行結果を返します。以下に挙げる Result を返します。
245 @retval ResultSuccess 処理に成功しました。
246 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
247 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
248 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
249 @retval 上記以外 上記以外の理由で失敗しました。
250 */
251 nn::Result AllowToConnect();
252
253 /*!
254 @brief 接続している全ての Spectator をネットワークから追放します。
255
256 実行後は新規に Spectator が接続することは出来ない状態になります。
257 再度 Spectator の接続を許可したい場合は @ref AllowToSpectate を実行してください。
258 Master のみ実行可能です。
259
260 @return 関数の実行結果を返します。以下に挙げる Result を返します。
261 @retval ResultSuccess 処理に成功しました。
262 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
263 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
264 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
265 @retval 上記以外 上記以外の理由で失敗しました。
266 */
267 nn::Result EjectSpectator ( void );
EjectAudience(void)268 inline nn::Result EjectAudience ( void ){ return EjectSpectator(); }
269
270 /*!
271 @brief Spectator のネットワークへの接続を許可します。
272
273 @ref EjectSpectator 実行後に再度 Spectator をネットワークに接続させたい場合にご使用下さい。
274 Master のみ実行可能です。
275
276 @return 関数の実行結果を返します。以下に挙げる Result を返します。
277 @retval ResultSuccess 処理に成功しました。
278 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
279 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
280 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
281 @retval 上記以外 上記以外の理由で失敗しました。
282 */
283 nn::Result AllowToSpectate();
284
285 /*!
286 @brief ネットワークを破棄します。
287
288 接続中の全ての Client、Spectator を追放し、ネットワークを破棄します。
289 Master のみ実行可能です。
290
291 @return 関数の実行結果を返します。以下に挙げる Result を返します。
292 @retval ResultSuccess ネットワークを破棄し、STATE_DISCONNECTED ステートに遷移しました。
293 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
294 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
295 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
296 @retval 上記以外 上記以外の理由で失敗しました。
297 */
298 nn::Result DestroyNetwork ( void );
299
300 /*!
301 @brief 接続中のネットワークから離脱します。
302
303 Client および Spectator のみ実行可能です。
304 披切断 (外的要因でネットワークから切断された) を考慮し、ネットワークに接続していない状態でも成功します。
305
306 @return 関数の実行結果を返します。以下に挙げる Result を返します。
307 @retval ResultSuccess ネットワークを破棄し、STATE_DISCONNECTED ステートに遷移しました。
308 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
309 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
310 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
311 @retval 上記以外 上記以外の理由で失敗しました。
312 */
313 nn::Result DisconnectNetwork ( void );
314
315 /*!
316 @}
317 */
318 /*!
319 @name データ送受信関連
320 @{
321 */
322
323 /*!
324 @brief ネットワークの端点 (endpoint) を生成し、対応する descriptor を返します。
325
326 [暫定仕様] endpoint は現在 16 個生成可能です。
327
328 @param[out] pEndpointDesc 生成する endpoint を示す descriptor です。
329
330 @return 関数の実行結果を返します。以下に挙げる Result を返します。
331 @retval ResultSuccess 処理に成功しました。
332 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
333 @retval ResultOutOfResource 既に規定数以上の endpoint が生成されています。既存の endpoint を破棄してください。
334 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
335 @retval 上記以外 上記以外の理由で失敗しました。
336 */
337 nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc );
338
339 /*!
340 @brief 最大送信遅延時間を指定します。
341
342 システムは物理レイヤの効率を良くするために、サイズの小さなパケットはまとめて送信するようにしています。
343 そのため、最大で @ref SendTo で送信したデータは最大で、この関数でセットした期間送信を待つ可能性があります。
344 回線効率よりもレイテンシを重視したい場合は @ref SendTo で @ref NO_WAIT を指定することで、この送信遅延を回避する事が出来ます。
345
346 ネットワークに接続していない状態でのみ実行可能です。
347
348 @param[in] maxDelay 最大送信遅延時間です。5ミリ秒～100ミリ秒の範囲で指定してください。デフォルトでは 10 ミリ秒となっています。
349
350 @return 関数の実行結果を返します。以下に挙げる Result を返します。
351 @retval ResultSuccess 処理に成功しました。
352 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
353 @retval ResultInvalidState 実行可能なステートではありません。通信中に実行した場合に返ります。
354 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
355 @retval 上記以外 上記以外の理由で失敗しました。
356 */
357 nn::Result SetMaxSendDelay ( nn::fnd::TimeSpan maxDelay );
358
359 /*!
360 @brief 指定した相手の指定したポートにデータを送信します。
361
362 送信処理が完了するまでブロックします。
363 option に @ref NO_WAIT , @ref FORCE_DIRECT_BC , @ref FORCE_UNICAST を指定することで、送信方法を指定できます。
364 複数のオプションを指定したい場合には OR による複数指定を行ってください。
365
366 @param[in] endpointDesc 使用する endpoint を示す descriptor です。
367 @param[in] data 送信するデータのポインタです。
368 @param[in] dataSize 送信するデータのサイズです。最大送信サイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byte です。
369 @param[in] destNodeId 送信先です。 BROADCAST_NODE_ID を指定するとデータはブロードキャストされます。
370 @param[in] port 使用するポートです。ポート番号0x00はシステム側で予約されているため使用できません。
371 @param[in] option 送信オプションです。
372
373 @return 関数の実行結果を返します。以下に挙げる Result を返します。
374 @retval ResultSuccess 処理に成功しました。
375 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
376 @retval ResultInvalidState 実行可能なステートではありません。Master もしくは Client 状態以外で実行した場合に返ります。
377 @retval ResultInvalidNode 対象のノードはネットワーク上に存在しません。切断されている可能性があります。
378 @retval ResultTooLarge dataSize が nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE を超えています。
379 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
380 @retval ResultBufferIsFull NO_WAIT オプションを指定している場合に、無線デバイス内の送信処理能力を超えるパケット送信をした場合に発生します。電波状況が悪い場合には発生頻度が上がります。
381 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
382 @retval 上記以外 上記以外の理由で失敗しました。
383 */
384 nn::Result SendTo ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 );
385
386
387 /*!
388 @brief endpoint とパケット受信可能な状態にします。
389
390 endpoint とポート、ノードID を結びつけます。
391 システムは受信用バッファを作成し、以降指定したポートへ送信されたパケットを受信できるようになります。
392
393 @param[in] pEndpointDesc 使用する Endpoint を示す descriptor です。
394 @param[in] srcNodeId 結びつけるノード ID です。BROADCAST_NODE_ID を指定すると全てのノードと結びつけられます。
395 @param[in] port 結びつけるポート番号です。ポート番号0x00はシステム側で予約されているため使用できません。
396 @param[in] receiveBufferSize 確保する受信バッファのサイズです。@ref Initialize で確保したメモリブロックから確保されますので、受信バッファの合計が
397 確保したメモリブロックのサイズよりも大きくならないよう注意してください。
398 @ref ATTACH_BUFFER_SIZE_MIN Byte以上を指定する必要があり、デフォルトでは @ref ATTACH_BUFFER_SIZE_DEFAULT Byteを確保します。
399 データサイズを指定する場合は内部で32Byte毎にメモリを確保しているため、32の倍数を指定すると効率的です。
400
401 @return 関数の実行結果を返します。以下に挙げる Result を返します。
402 @retval ResultSuccess 処理に成功しました。
403 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
404 @retval ResultInvalidState 実行可能なステートではありません。
405 @retval ResultOutOfResource システムリソースが不足している場合、nn::uds::Initialize 関数で指定したバッファから受信バッファが足りなくなった場合に返ります。
406 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
407 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
408 @retval 上記以外 上記以外の理由で失敗しました。
409 */
410 nn::Result Attach ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize = ATTACH_BUFFER_SIZE_DEFAULT );
411
412 /*!
413 @brief データを受信します。(送信元アドレス取得機能なし)
414
415 引数以外は @ref ReceiveFrom と同機能です。詳細は @ref ReceiveFrom のリファレンスを参照下さい。
416
417 @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
418 @param[out] pBuffer 受信データの格納先です。4 Byte整合されたバッファを指定してください。
419 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
420 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。
421 @param[in] option 受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。
422 指定しないとデータを受信、もしくはエラーが発生するまで終了しません。
423
424 @return 関数の実行結果を返します。以下に挙げる Result を返します。
425 @retval ResultSuccess 処理に成功しました。
426 @retval ResultNotInitialized ライブラリが初期化されていない場合、指定した endpoint が存在しない場合に返ります。
427 @retval ResultInvalidState 実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
428 @retval ResultNotAuthorized Attach していない endpoint を指定した場合に返ります。
429 @retval ResultTooLarge 受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE であることが望まれます。
430 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
431 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
432 @retval 上記以外 上記以外の理由で失敗しました。
433 */
434 nn::Result Receive ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 );
435
436 /*!
437 @brief データを受信します。
438
439 @ref Attach を実行済みの endpoint に送信されたパケットを受信します。
440 受信すべきパケットがない場合、関数はブロックします。(エラー発生時を除く)
441 option に @ref NO_WAIT を指定した場合には、パケットを受信していない場合でも完了します。
442
443 @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
444 @param[out] pBuffer 受信データの格納先です。4 Byte整合されたバッファを指定してください。
445 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
446 @param[out] pSrcNodeId 送信元ノードIDです。
447 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。
448 @param[in] option 受信オプションです。
449
450 @return 関数の実行結果を返します。以下に挙げる Result を返します。
451 @retval ResultSuccess 処理に成功しました。
452 @retval ResultNotInitialized ライブラリが初期化されていない場合、指定した endpoint が存在しない場合に返ります。
453 @retval ResultInvalidState 実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
454 @retval ResultNotAuthorized Attach していない endpoint を指定した場合に返ります。
455 @retval ResultTooLarge 受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE であることが望まれます。
456 @retval ResultOutOfRange 指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
457 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
458 @retval 上記以外 上記以外の理由で失敗しました。
459 */
460 nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 );
461
462 /*!
463 @brief endpoint を破棄します。
464
465 @ref Attach を実行済みの endpoint を指定した場合には、受信用バッファを解放します。
466 解放された受信バッファは、再度 @ref Attach で利用できますが、アプリケーションがアクセスできるのは @ref Finalize 実行後であることに注意してください。
467
468 @param[in] pEndpointDesc endpoint を示す descriptor です。
469
470 @return 関数の実行結果を返します。以下に挙げる Result を返します。
471 @retval ResultSuccess 処理に成功しました。
472 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
473 @retval ResultNotAuthorized 無効な EndpointDescriptor を指定した場合に返ります。
474 @retval 上記以外 上記以外の理由で失敗しました。
475 */
476 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc );
477
478 /*!
479 @}
480 */
481
482 /*!
483 @brief 自身の MAC アドレスを取得します。(デバッグ用)
484
485 通信機能のデバッグを行う際に、実行中のデバイスの MAC アドレスを調査、取得するための API です。
486
487 MAC アドレスは本体ごとにユニークな値ですが、修理などによって変更されてる可能性があります。
488 本体の特定を行いたい場合は @ref nn::cfg::GetTransferableId 関数を使用してください。
489
490 @param[out] pMacAddress 自身の MAC アドレスです。
491
492 @return 関数の実行結果を返します。以下に挙げる Result を返します。
493 @retval ResultSuccess 処理に成功しました。
494 @retval ResultNotAuthorized MAC アドレスを取得できない状態です。ライブラリ未初期化でも返ります。
495 @retval 上記以外 上記以外の理由で失敗しました。
496 */
497 nn::Result GetMacAddress( bit8 pMacAddress[MAC_ADDRESS_SIZE] );
498
499 /*!
500 @brief 現在の接続状態を返します。
501
502 @param[out] pStatus 現在の接続状態です。
503
504 @return 関数の実行結果を返します。以下に挙げる Result を返します。
505 @retval ResultSuccess 処理に成功しました。
506 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
507 @retval 上記以外 上記以外の理由で失敗しました。
508 */
509 nn::Result GetConnectionStatus( ConnectionStatus* pStatus );
510
511 /*!
512 @brief 現在のリンクレベルを取得します。
513
514 @param[out] pLinkLevel 現在のリンクレベルです。
515
516 @return 関数の実行結果を返します。以下に挙げる Result を返します。
517 @retval ResultSuccess 処理に成功しました。
518 @retval 上記以外 上記以外の理由で失敗しました。
519 */
520 nn::Result GetLinkLevel( LinkLevel* pLinkLevel );
521
522 /*!
523 @brief 現在のリンクレベルを取得します。
524
525 @return 現在のリンクレベルです。
526 */
527 LinkLevel GetLinkLevel();
528
529 /*!
530 @brief 指定したノードの情報を取得します。
531
532 @param[out] pNodeInfo ノードの情報です。将来、格納するデータに対応した構造体を用意する予定です。
533 @param[in] nodeId 対象となるノードのノードIDです。
534
535 @return 関数の実行結果を返します。以下に挙げる Result を返します。
536 @retval ResultSuccess 処理に成功しました。
537 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
538 @retval ResultInvalidNode 対象のノードはネットワーク上に存在しません。切断されている可能性があります。
539 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
540 @retval 上記以外 上記以外の理由で失敗しました。
541
542 */
543 nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId );
544
545 /*!
546 @brief 省電力モードを変更します。(現在未実装)
547
548 この設定は Master でのみ変更可能で、Client / Spectator は Master の設定に従います。
549 現在未実装で、実行すると必ず失敗します。
550 機能実装後は、通信中に動的に省電力モードを変更することが可能になる予定ですが、高頻度 (数秒未満の間隔) にモードを切り替えないで下さい。
551
552 @param[in] mode 省電力モードです。省電力モードを有効にすると若干接続性が悪くなる場合があります。
553
554 @return 関数の実行結果を返します。以下に挙げる Result を返します。
555 @retval ResultNotImplemented まだ実装されていません。
556
557 */
558 nn::Result SetPowerSaveMode(PowerSaveMode mode);
559
560 /*!
561 @brief ビーコンに任意データをセットします。
562
563 最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte の任意のデータをセットします。
564 暗号化されていませんので PC などの一般機器で収集可能である点にご注意下さい。
565 このデータは他の機器が @ref Scan した際と @ref Client/Spectator として接続中に取得可能です。
566 Master でのみ実行可能です。
567
568 @param[in] pData セットしたいデータのポインタです。
569 @param[in] dataSize セットしたいデータのサイズです。 @ref NET_DESC_APPDATA_SIZE_MAX 以下の数値を指定してください。
570
571 @return 関数の実行結果を返します。以下に挙げる Result を返します。
572 @retval ResultSuccess 処理に成功しました。
573 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
574 @retval ResultInvalidState 実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
575 @retval ResultTooLarge dataSize が nn::uds::NET_DESC_APPDATA_SIZE_MAX を超えています。
576 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
577 @retval 上記以外 上記以外の理由で失敗しました。
578 */
579 nn::Result SetApplicationDataToBeacon ( const void* pData, size_t dataSize );
580
581 /*!
582 @brief ビーコンにセットされたデータを取得します。
583
584 Master が @ref SetApplicationDataToBeacon でセットしたデータを取得します。
585 ネットワークに接続中にのみ実行可能です。
586 データが更新されても通知されませんのでご注意下さい。
587
588 @param[out] pBuffer データの格納先です。
589 @param[out] pDataSize データのサイズです。
590 @param[in] bufferSize バッファの大きさです。受け取るデータのサイズは送信側が自由に変更できますので、基本的には @ref NET_DESC_APPDATA_SIZE_MAX Byte を指定してください。
591
592 @return 関数の実行結果を返します。以下に挙げる Result を返します。
593 @retval ResultSuccess 処理に成功しました。
594 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
595 @retval ResultInvalidState 実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
596 @retval ResultTooLarge 受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::NET_DESC_APPDATA_SIZE_MAX であることが望まれます。
597 @retval ResultWirelessOff 無線 OFF モードに遷移しました。再初期化が必要です。
598 @retval 上記以外 上記以外の理由で失敗しました。
599 */
600 nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize );
601
602 namespace detail{
603
604 /*!
605 :private
606 @brief 詳細な電波強度を取得します。
607
608 この関数は開発機でのみ実行可能な開発支援のための関数ですので製品では利用しないでください。
609 呼び出し間隔が短いと通信に影響を及ぼしますので、1秒程度の間隔を空けて実行するようてください。
610
611 @param[out] info 電波強度情報です。関数が成功した場合にデータが格納されます。
612
613 @return 関数の実行結果を返します。成功したら info にデータが格納され、ResultSuccess を返します。
614 */
615 nn::Result GetRadioStrengthInfo(RadioStrengthInfo* info);
616
617 /*!
618 :private
619 @brief endpoint を破棄します。
620
621 同時に @ref Attach で作成した受信用バッファを解放します。
622 無線による受信は成功したものの、UDS の受信バッファ溢れによってロストしたパケットについての情報を取得できるデバッグ用 API です。
623
624 @param[in] pEndpoint endpoint を示す descriptor です。
625 @param[out] pReport 破棄した Endpoint に到達したパケットに関する情報です。
626
627 @return 関数の実行結果を返します。以下に挙げる Result を返します。
628 @retval ResultSuccess 処理に成功しました。
629 @retval ResultNotInitialized ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
630 @retval ResultNotAuthorized 無効な EndpointDescriptor を指定した場合に返ります。
631 @retval 上記以外 上記以外の理由で失敗しました。
632 */
633 nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport );
634
635 } // end of namespace detail
636
637 } // end of namespace CTR
638 } // end of namespace uds
639 } // end of namespace nn
640
641
642
643 #endif // ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_
644