# WM_StartDataSharing

## 構文

      #include <nitro/wm.h>

      WMErrCode WM_StartDataSharing(
              WMDataSharingInfo*  dsInfo ,
              u16                 port ,
              u16                 aidBitmap ,
              u16                 dataLength ,
              BOOL                doubleMode
      );

## 引数

dsInfo | データシェアリング情報構造体へのポインタを指定します。 バッファの実体はデータシェアリングを行うグループごとに別々に確保しておく必要があります。 また、バッファの実体はキャッシュ制御されるため、32バイトアラインされている必要があります。
port | データシェアリングを行うポート番号を指定します。0 〜 15 の値を指定して下さい。
aidBitmap | データシェアリングを行う相手端末のAIDのビットマップを指定します。 最大の16台でデータシェアする場合は 0xFFFF となります。
dataLength | 共有データの１端末辺りのデータ長を指定します。2 の倍数バイトである必要があります。
doubleMode | 1フレームに1回のMP通信を行うモードで、毎フレーム DataSharing を行いたい場合は、ここに TRUE を指定します。

## 返り値

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

## 説明

データシェアリングを初期化します。WMがMP_PARENTステート、もしくはMP_CHILDステートの場合に実行可能です。 この関数は同期関数ですので、処理に成功した場合即座にWM_ERRCODE_SUCCESSを返します。必ずWM_StartMP( ) 直後に呼び出すようにしてください。 このAPIを呼んだだけで定期的に処理や通信が発生することはありません。WM_StepDataSharing( ) を呼びだすことで処理が開始されます。
親機の場合は複数のグループに対して平行してデータシェアリングを行うことが可能です。 グループごとにWMDataSharingInfo構造体を用意し、異なるポート番号で複数回この関数を呼び出して下さい。 また、親機が一度に送信可能なデータ長の制限から、( データシェアリングを行うグループの端末数 × 共有データサイズ )が許容範囲(508Bytes)を越えるような指定はできません。
doubleMode にTRUEを指定した場合、WM_StepDataSharing( ) で取得できる値は、2回前のWM_StepDataSharing( )で設定した値になりますが、 MP通信1回ごとにWM_StepDataSharing( ) を呼び出すことができます。 FALSE の場合は、直前で指定した値を取得することが可能ですが、その代わり呼び出し間隔を最低MP通信2回分空けなければWM_StepDataSharing( )は成功しません。

WM_StartMPの引数mpFreqとWM_StepDataSharing( )のパラメータに対して、データシェリングの成功間隔と共有データの通信遅延の対応は以下のとおりです。

mpFreq | doubleMode | データシェアリング間隔 | 遅延 | 備考
1 | TRUE | 毎フレーム | 2フレーム | doubleModeをTRUEにすると途中で1セット分のバッファリングが入る形になりますので、遅延が増えます。
2以上 or 0（連続通信モード） | FALSE | 毎フレーム | 1フレーム | 1フレームに2回以上のMP通信を行えばdoubleModeがFALSEでも毎フレームでシェアできますが、エラーに弱くなり、電力消費も多くなるため、利用に際しては慎重に検討してください。
1 | FALSE | 2フレーム以上 | 同左 | 2フレーム以上の間隔でデータシェアリングを行う場合は、mpFreqが1の場合でもdoubleModeをFALSEで運用できるため、遅延もデータシェアリング間隔と等しくなります。

## 参照

`WM_EndDataSharing, WM_StepDataSharing, WMPort`

## 履歴

2005/03/02 port引数について指定可能範囲を追記
2004/10/25 共有データ総計の最大値を508バイトに変更
2004/10/22 返り値の型を変更
2004/09/25 説明の加筆・修正
2004/08/31 引数に doubleMode を追加
2004/08/11 初版