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