WM_StartDataSharing

C Specification

#include <nitro/wm.h>

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

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. Use a value from 0-15.
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.

Return Values

Returns the results of the WMErrCode enumerated type process.

Description

Initializes data sharing. This function is executable when the WM is in either the MP_PARENT state or the MP_CHILD state. This is a synchronous function that promptly returns the WM_ERRCODE_SUCCESS return value when the process succeeds.
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. 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.

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 Comments
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.

See Also

WM_EndDataSharing, WM_StepDataSharing, WMPort

Revision History

03/02/2005 Added description of allowable range for port argument.
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