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