# WM_StartMPEx

## C Specification

      #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 );

## Description

Starts the MP Communication mode

This function is only executable when the WM is in either the `PARENT` or `CHILD` state.

If the return value is `WM_ERRCODE_OPERATING`, a callback is generated after the transition to the MP mode is complete. The WM changes to `MP_PARENT` or `MP_CHILD` state as appropriate.

A callback is generated every time data is received via MP communication or when a single MP communication completes. After entering the MP communication mode, V-Blank synchronization automatically occurs between the connected devices.

MP communication is attempted in each frame for the number of times that is specified by `mpFreq`. The number of attempts is not guaranteed and is dependent on the communication status. The maximum number of MP communication attempts that occur during a each frame varies with each communication parameter.

`WM_StartMP` is equivalent to `WM_StartMPEx` with `defaultRetryCount` set to `0` and `minPollBmpMode`, `singlePacketMode`, `fixFreqMode`, and `ignoreFatalError` all set to `FALSE`.

## Arguments

`callback` | Designates the condition notifications of the asynchronous processes and the callback functions that are called upon completion.
`recvBuf` | The storage buffer for the receive data that the SDK uses internally. This value must be aligned to the 32-byte boundary. Because the ARM7 processor writes directly to the buffer, be careful of coherency with the cache.
`recvBufSize` | Size of the storage buffer for the receive data. This value must be larger than the return value of `WM_GetMPReceiveBufferSize` and must be a multiple of 64 bytes.
`sendBuf` | Storage buffer for the send data that the SDK uses internally. This value must be aligned to the 32-byte boundary. Because the ARM7 processor writes directly to the buffer, be careful of coherency with the cache.
`sendBufSize` | Size of the storage buffer for send data. This value must be larger than the return value of `WM_GetMPSendBufferSize` and must be a multiple of 32 bytes.
`mpFreq` | Number of times to perform MP communications per frame. If 0 is designated, the mode becomes the continuous communication mode. The continuous communication mode is provided for high capacity data communications. This argument affects only the parent device.
`defaultRetryCount` | For communication on ports 0-7, this argument designates the default value of the number of resend attempts when the send attempt fails. This value has no relation to the communication that occurs on ports 8-15 and the resends can be repeated without limit. This argument affects only the parent device.

`minPollBmpMode`

When TRUE, the value of the MP communications poll bitmap becomes the logical OR of the destination of the packet that the parent sends on that communication.
If FALSE, it sets up the poll bitmaps of all child devices. The default value of `WM_StartMP` is FALSE.
This argument affects only the parent device.

`singlePacketMode` | When this value is TRUE, this function always sends only one packet for each MP communication. When this value is FALSE, the packets are packed as much as the sendable bytes allow.

`fixFreqMode`

If a resend occurs, this normally performs continuous MP communications. However, if the value for this argument is TRUE, the number of communications does not increase even if a resend occurs. In one frame, the number of MP communications that are performed is less than the number in the `mpFreq` argument. (Based on the state of the channel and the length of the data, there is always the possibility that this number could fall below the value in the `mpFreq` argument.)
This argument affects only the parent device.

`ignoreFatalError` | If a fatal error occurs during MP communication due to the radio wave status, the parent is disconnected from a child and a child from the parent. However, when this flag is specified as `TRUE`, the disconnection process is not executed even if a fatal error occurred, and the connection is maintained. This flag should not be set to `TRUE` for modes other than MB.

## Return Values

Returns the process result as a `WMErrCode` enumerated type.

## See Also

`WM_StartMP`, `WM_EndMP`, `WM_SetMPDataToPort`, `WM_SetPortCallback`

## Revision History

10/22/2004 Changed return value type
10/03/2004 Added description regarding `ignoreFatalError`
09/25/2004 Added and revised descriptions
08/27/2004 Added arguments
08/25/2004 Initial version