WM_StartMPEx

構文

#include <nitro/wm.h>

WMErrCode WM_StartMPEx(
        WMCallbackFunc  callback ,
        u16*            recvBuf ,
        u16             recvBufSize ,
        u16*            sendBuf ,
        u16             sendBufSize ,
        u16             mpFreq ,
        u16             defaultRetryCount ,
        BOOL            minPollBmpMode ,
        BOOL            singlePacketMode ,
        BOOL            fixFreqMode ,
        BOOL            ignoreFatalError
);

引数

callback	非同期処理の状況通知、及び完了した際に呼び出されるコールバック関数を指定します。このコールバックは割り込みハンドラ内から呼び出されます。
recvBuf	SDK が内部的に使用する受信データ格納バッファを指定します。 32バイト境界にあっている必要があります。 ARM7が直接データを書き出しますので、キャッシュに注意して下さい。
recvBufSize	受信データ格納バッファのサイズを指定します。 WM_GetMPReceiveBuffterSizeの返り値より大きく、かつ64バイトの倍数である必要があります。
sendBuf	SDK が内部的に使用する送信データ格納バッファを指定します。 32バイト境界にあっている必要があります。 ARM7が直接データを読み書きしますので、キャッシュに注意して下さい。
sendBufSize	送信データ格納バッファのサイズを指定します。 WM_GetMPSendBuffterSizeの返り値より大きく、かつ32バイトの倍数である必要があります。
mpFreq	1フレームあたり何回のMP通信を行うかを指定します。 0 を指定すると大容量のデータ通信用に用意された連続通信モードになります。親機のみ意味を持ちます。
defaultRetryCount	0～7番ポートでの通信において、送信が失敗した場合の再送回数のデフォルト値を指定します。なお、8～15番ポートでの通信はこの値に関係なく無限に再送を繰り返します。親機のみ意味を持ちます。
minPollBmpMode	TRUEの場合、MP通信のpoll bitmapの値はその回の通信で親が送信するパケットの宛先の論理和になります。FALSEの場合は、常に子機全員のpoll bitmapを立てます。WM_StartMPでのデフォルト値はFALSEです。親機のみ意味を持ちます。
singlePacketMode	TRUEの場合、1回のMP通信では常に1パケットしか送信しません。FALSEの場合は、送信容量が許す限りパケットを詰め込みます。WM_StartMPでのデフォルト値はFALSEです。
fixFreqMode	再送が発生すると通常は連続してMP通信を行いますが、この引数が TRUE の場合は再送が発生しても通信回数を増やしません。必ず1フレームに行われるMP通信の回数は mpFreq 回以下になります。（通信路の状態やデータ長の関係で mpFreq 回を下回る可能性は常にあります）内部的には MP 通信の再送を含めた上限回数を mpFreq と同じ値に設定することで実現されています。mpFreq が 0 の場合は、この指定は無視されます。親機のみ意味を持ちます。
ignoreFatalError	電波状態によりまれに起こるMP通信の致命的エラーが発生した場合、親機の場合は対象となる子機を、子機の場合は親機を切断します。しかしこのフラグをTRUEに指定しておいた場合は、致命的エラー発生時も切断処理を行なわず接続状態を維持します。このフラグはMBなど限られたモード以外では決してTRUEにしないでください。

返り値

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

説明

MP通信モードに入ります。WMがPARENTステート、もしくはCHILDステートの場合のみ実行可能です。 APIの戻り値がWM_ERRCODE_OPERATINGであった場合、MPモードへの移行処理が完了した後にコールバックが発生します。 WMのステートはそれぞれMP_PARENTステート、もしくはMP_CHILDステートに移行します。
また、MP通信によってデータを受信した場合や一回のMP通信が完了した場合にも、その都度コールバックが発生します。 MP通信モードに入った後、接続機器間でVブランク同期処理が自動的に行われるようになります。
毎フレームにmpFreqで指定した回数だけMP通信をしようと試みますが、通信状態によっては回数は保証されません。1フレームで可能なMP通信の回数の上限は、各通信パラメータによって変動します。
defaultRetryCount, minPollBmpMode, singlePacketMode, fixFreqMode, ignoreFatalError といったこの関数で設定される設定値は、この関数の呼び出しで開始されるMP_PARENT または MP_CHILD ステートの間だけ有効です。これらの設定値をWM_SetMPParameter( )で設定した上で、WM_StartMP( ) を呼び出しても同様の効果が得られますが、その場合はWM_SetMPParameter( )で設定した値はREADYステートに戻るまで有効となります。

minPollBmpMode の使用に関しては MP 通信に関する詳細な理解が必要となりますので、通常は有効にしないようにしてください。有効にする場合は、8～15番の範囲で使用しているportに関して、全ての子機、全てのportに対し、60秒に1回は通信が行われる必要があります。

MP通信を行う子機の場合、WM_StartConnect( ) で親機と接続した後に、あまり時間をあけずにWM_StartMPEx( ) を呼び出すようにしてください。接続してからWM_StartMPEx( ) を呼び出すまでの間、子機は親機からの通信に対して応答を返しません。この状態が親機のWM_SetLifeTime( ) で設定されたCAMライフタイムを超えると親機から切断されます。

また、MP通信パラメータを変更することを目的として、接続中にWM_EndMP( ) とWM_StartMPEx( )を連続して呼び出すことは避けてください。 Sequential通信の情報など、MP通信の内部情報が初期化されるため、前後で通信の一貫性が取れなくなります。
MP通信中に、MP通信頻度などの特定のMP通信パラメータを変更する場合は、WM_SetMPFrequency( ), WM_SetMPParameter( ) などの関数を使用することが可能です。

参照

WM_StartMP, WM_EndMP, WM_SetMPDataToPort, WM_SetPortCallback, WM_SetMPFrequency, WM_SetMPParameter

履歴

2007/05/02 fixFreqMode に関する記述の追記
2007/05/02 設定値が有効な範囲の変更に伴う記述の変更
2006/01/13 通信中のMP通信パラメータの変更に関する注記を追加
2005/11/24 WM_StartMP 関数の仕様変更に伴う記述変更
2005/06/08 コールバックが割り込みハンドラから呼び出される旨を補足
2005/02/14 minPollBmpMode に関する記述を追加
2004/10/22 返り値の型を変更
2004/10/03 ignoreFatalErrorについての記述を追加
2004/09/25 説明の加筆・修正
2004/08/27 引数の追加
2004/08/25 初版