WM_StartConnectEx

構文

#include <nitro/wm.h>

WMErrCode WM_StartConnectEx(
    WMCallbackFunc    callback ,
    const WMBssDesc*  pInfo ,
    const u8*         ssid ,
    BOOL              powerSave ,
    u16               authMode
);

引数

callback	非同期処理の状況通知、及び完了した際に呼び出されるコールバック関数を指定します。このコールバックは割り込みハンドラ内から呼び出されます。
pInfo	接続する親機の情報を指定します。 WM_StartScan( )もしくはWM_StartScanEx( )にて取得した構造体をそのまま指定して下さい。この構造体の実体は強制的にキャッシュストアされる点に注意して下さい。
ssid	親機に通知する子機情報 ( 24 バイト ( WM_SIZE_CHILD_SSID ) 固定サイズ ) を指定してください。ここで指定したデータは、WM_StartParent( )のコールバックで親機に通知されます。 NULLを指定した場合は、全て 0 である 24 バイトのデータが設定されます。
powerSave	省電力モードを使用する場合にTRUEを指定、常時待ち受けモードを使用する場合はFALSEを指定します。通常はTRUEを指定して下さい。インフラストラクチャモードにて比較的頻繁にデータ送受信を行う必要がある場合のみFALSEを指定して下さい。 FALSEを指定すると省電力モードに比べて著しく電力を消耗します。
authMode	認証モードを指定します。通常はオープンシステム認証( WM_AUTHMODE_OPEN_SYSTEM )を指定して下さい。共通鍵認証( WM_AUTHMODE_SHARED_KEY )を指定する場合は、WEP暗号を用いた認証が行われますので、事前にWM_SetWEPKeyEx( )などを用いて通信相手と同じWEPキーを設定しておく必要があります。この 2つ以外の値は指定できません。

返り値

WMErrCode列挙型の処理結果を返します。

説明

親機への接続処理を開始します。インフラストラクチャモードを使用する際などにWM_StartConnect( )より詳細に接続動作を制御可能ですが、通常は使用する必要はありません。 WMがIDLEステートのときにのみ実行可能です。 APIの戻り値がWM_ERRCODE_OPERATINGであった場合、接続処理が開始された時、及び親機によって認証されてAIDが割り当てられた時にコールバックが発生します。接続処理開始後、正常に接続状態まで移行できなかった場合にもコールバックが発生します。接続が完了した場合に、WMはCHILDステートに移行します。
また、接続完了後に親機から切断された場合にはこの関数で指定したコールバックが発生します。親機が定期的に送信しているはずのビーコンを一定時間受信できない状態が続いた場合にもこの関数で指定したコールバックが発生します。
接続処理の途中で失敗してコールバックを返した場合は、内部状態が不正になっていることがありますので、WM_StartConnectExをリトライする前にWM_Reset( )を呼び出すようにしてください。

注意

この関数を呼び出した後、正常に子機として接続が完了した場合にコールバックが発生しますが、場合によってはこのコールバックが発生する前にビーコン受信通知や親機から切断されたことを示す通知が発生することがあります。子機としての初期化処理などを行う場合はコールバックが発生した際に行うのではなく、この関数を呼び出す前に行っておくようにして下さい。

APIの戻り値であるWM_ERRCODE_OVER_MAX_ENTRYは、親機に対してGGIDやTGIDが一致しない不適切なほかの子機が接続してきていた瞬間に一時的に発生することがあるため、リトライ処理を行うことが推奨されます。
特に、ダウンロードプレイにおける子機プログラムのブート直前の接続で、親機の古いビーコンを元にダウンロードの接続にくる他のIPL子機が存在した場合が、問題の発生しやすいケースです。

引数に渡したデータ(pInfo)は内部で強制的にキャッシュストアされます。キャッシュのトラブルを回避するには、32バイト境界に揃ったデータを渡す必要があります。
注意点などの詳細は「ワイヤレス通信ライブラリ解説 (AboutWirelessManager.pdf)」を参照してください。

参照

WM_StartConnect, WM_StartScan, WM_EndScan, WM_Disconnect

履歴

2008/12/17 引数に渡したデータが内部で強制的にキャッシュストアされる点について注意を追記
2007/04/12 WM_ERRCODE_OVER_MAX_ENTRYに関する注意追記
2005/06/08 コールバックが割り込みハンドラから呼び出される旨を補足
2005/03/02 説明追記
2005/02/14 初版