# WM_StartDataSharing

## C Specification

      #include <nitro/wm.h>

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

## Description

Initializes data sharing.

This function is executable when the WM is in either the `MP_PARENT` state or the `MP_CHILD` state. Be sure to call WM_StartDataSharing only after `WM_StartMP`. Processing and communication does not occur regularly simply by calling this API. Processing is started by calling `WM_StepDataSharing`.

This is a synchronous function that immediately returns `WM_ERRCODE_SUCCESS` if the process succeeds.

For parents, it is possible to perform parallel data sharing for multiple groups. Prepare the `WMDataSharingInfo` structure for each group and call this function multiple times for different port numbers.

You cannot specify a value (number of group terminals performing data sharing × shared data size) that exceeds the permitted range from the length limit (508 bytes) of data that the parent can send at once.

When a value of TRUE is specified in the `doubleMode` argument, the value that can be obtained with the `WM_StepDataSharing` function is the value that was set with two sets of `WM_StepDataSharing` functions prior to the current function. This function can be called for each MP communication.

When a value of FALSE is specified, it is possible to obtain the value that was specified immediately before this value, but it requires at least two intervals of MP communications for `WM_StepDataSharing` to succeed.

## Arguments

`dsInfo` | Specifies the pointer to the data sharing information structure. The buffer must separately allocate each group that performs data sharing. Because the buffer is cache controlled, it must be 32 byte aligned.
`port` | Specifies the port number that performs data sharing.
`aidBitmap` | Specifies the Poll map of the AID of the terminal that performs data sharing. When data sharing with the maximum 16 units, it is 0xFFFF.
`dataLength` | Specifies the data length for one child to share. This must be a byte length that is a multiple of two.
`doubleMode` | Specifies a value of TRUE for using DataSharing in every frame in the mode that executes one MP communication per frame.

For the argument `mpFreq` of `WM_StartMP` and parameters of `WM_StartDataSharing`, the data sharing success interval and communication delay of shared data correspond as shown below.

`mpFreq` | `doubleMode` | Data sharing intervals | Delay | Note
1 | TRUE | Every frame | 2 frames | If `doubleMode` is set to TRUE, it adds one set of buffering and the delay increases.
2 or more, or 0 (continuous communication mode) | FALSE | Every frame | 1 frame | When executing more than 2 MP communications per frame, data can be shared in every frame even when `doubleMode` is set to FALSE. However, it is more likely to cause errors and increase power consumption, so use it with caution.
1 | FALSE | 2 or more frames | 2 or more frames | When data sharing is executed at intervals of 2 or more frames, `doubleMode` can be FALSE even if `mpFreq` is 1. Therefore, the delay time equals the data sharing interval.

## Return Values

Returns the process results of the `WMErrCode` enumerator type.

## See Also

`WM_EndDataSharing`, `WM_StepDataSharing`, `WMPort`

## Revision History

10/25/2004 Changed maximum value of shared data to 508 bytes
10/22/2004 Changed return value type
09/25/2004 Added and revised descriptions
08/31/2004 Added `doubleMode` to Arguments
08/11/2004 Initial version