# EtherCAT® Mailbox Transfer

To be able to initiate a mailbox transfer the client has to create a mailbox transfer object first.
This mailbox transfer object also contains the memory where the data to be transferred is stored.
The one client that initiated the mailbox transfer will be notified about a mailbox transfer completion by the `emonNotify()` callback function.

To be able to identify the transfer which was completed the client has to assign a unique transfer identifier for each mailbox transfer.
The mailbox transfer object can only be used for one single mailbox transfer.
If multiple transfers shall be initiated in parallel the client has to create one transfer object for each.
The transfer object can be re-used after mailbox transfer completion.

Typical mailbox transfer sequence:

1. Record a mailbox transfer.
2. Create a transfer object (for example an SDO download transfer object).
   : ```cpp
     MbxTferDesc.dwMaxDataLen = 10
     <br/>
     MbxTferDesc.pbyMbxTferDescData = (EC_T_PBYTE)OsMalloc(MbxTferDesc.dwMaxDataLen)
     <br/>
     pMbxTfer = emonMbxTferCreate(&MbxTferDesc)
         state of the transfer object = Idle
     ```
3. Set the location to write the transferred data to, determine the transfer ID, store the client ID in the object and initiate the transfer (e.g. a SDO upload). A transfer may only be initiated if the state of the transfer object is Idle.
   : ```cpp
     pMbxTfer->dwDataLen = MbxTferDesc.dwMaxDataLen;
     <br/>
     pMbxTfer->pbyMbxTferData = MbxTferDesc.pbyMbxTferDescData
     <br/>
     pMbxTfer->dwTferId = 1;
     <br/>
     pMbxTfer->dwClntId = dwClntId;
     <br/>
     <br/>
     dwResult = emonCoeSdoUplodadReq(pMbxTfer, dwSlaveId, wObIndex, ...);
         state of the transfer object = Pend or TferReqError
     ```
     <br/>
     The state will then be set to Pend to indicate that this mailbox transfer object currently is in use and the transfer is not completed.
     If the mailbox transfer cannot be initiated the MainDevice will set the object into the state TferReqError - in such cases the client
     is responsible to set the state back into Idle.
4. If the mailbox transfer is completed the notification callback function of the corresponding client ( `emonNotify()`) will be called with a pointer to the mailbox transfer object. The state of the transfer object is set to TferDone prior to calling `emonNotify()`.
   : ```cpp
     if( dwResult != EC_E_NOERROR ) { ... }
     <br/>
     emonNotify( EC_NOTIFY_MBOXRCV, pParms )
         state of the transfer object = TferDone
     ```
5. In case of errors the appropriate error handling has to be executed. The application must set the transfer object state to Idle.
   : ```cpp
     if( pMbxTfer->dwErrorCode != EC_E_NOERROR ) { ... }
         In emonNotify: application may set transfer object state to Idle
     ```
6. Delete the transfer object. Alternatively this object can be used for the next transfer.
   : ```cpp
     emonMbxTferDelete(pMbxTfer);
     ```

## Mailbox transfer object states

The following states exist for a mailbox transfer object:

### enum EC_T_MBXTFER_STATUS

*Values:*

### enumerator eMbxTferStatus_Idle

Mailbox transfer object not in use 

### enumerator eMbxTferStatus_Pend

Mailbox transfer in process 

### enumerator eMbxTferStatus_TferDone

Mailbox transfer completed 

### enumerator eMbxTferStatus_TferReqError

Mailbox transfer request error 

### enumerator eMbxTferStatus_TferWaitingForContinue

Mailbox transfer waiting for continue, object owned by application 

A mailbox transfer will be processed by the monitor independently from the client’s timeout setting.
Some types of mailbox transfers can be cancelled by the client, e.g. if the client’s timeout elapsed.

After completion of the mailbox transfer (with timeout) the client may finally set the transfer object into
the state [`EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle`](#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).
New mailbox transfers can only be requested if the object is in the state [`EC_T_MBXTFER_STATUS::eMbxTferStatus_Idle`](#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).

## emonMbxTferCreate

### [EC_T_MBXTFER](#_CPPv412EC_T_MBXTFER) \*emonMbxTferCreate([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER_DESC](#_CPPv417EC_T_MBXTFER_DESC) \*pMbxTferDesc)

Creates a mailbox transfer object. 

While a mailbox transfer is in process the related transfer object and the corresponding memory may not be accessed. After a mailbox transfer completion the object may be used for the next transfer. The mailbox transfer object has to be deleted by calling ecatMbxTferDelete if it is not needed any more.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTferDesc** – [in] Pointer to the mailbox transfer descriptor. Determines details of the mailbox transfer. 
* **Returns:**
  * Pointer to the created mailbox transfer object if successful
  * EC_NULL on error (No memory left) 

### struct EC_T_MBXTFER_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwMaxDataLen

Maximum amount of data bytes that shall be transferred using this object. A mailbox transfer type without data transfer will ignore this parameter. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxTferDescData

Pointer to byte stream carrying in and out data of mailbox content 

### struct EC_T_MBXTFER

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwClntId

[] Client ID 

### [EC_T_MBXTFER_DESC](#_CPPv417EC_T_MBXTFER_DESC) MbxTferDesc

[out] Mailbox transfer descriptor. All elements of pMbxTferDesc will be stored here. 

### [EC_T_MBXTFER_TYPE](#_CPPv417EC_T_MBXTFER_TYPE) eMbxTferType

[] This type of information is written to the Mailbox Transfer Object by the last call to a mailbox command function. It may be used as information, and is required to fan out consecutive notifications. This value is only valid until the next relevant mailbox API call, where this value may be overwritten. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen

[] Amount of data bytes for the next mailbox download transfer. If the mailbox transfer does not transfer data to the slave this parameter will be ignored. This element has to be set to an appropriate value every time prior to initiating a new download request. When either a download or upload transfer is completed (emNotify) this value will contain the amount of data that was actually transferred. 

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyMbxTferData

[in/out] Pointer to data. In case of a download transfer the client has to store the data in this location. In case of an upload transfer this element points to the received data. Access to data that was uploaded from a slave is only valid within the notification function because the buffer will be re-used by the master. These data have to be copied into a separate buffer in case it has to be used later by the client. 

### [EC_T_MBXTFER_STATUS](#_CPPv419EC_T_MBXTFER_STATUS) eTferStatus

[out] Transfer state. After a new transfer object is created the state will be set to eMbxTferStatus_Idle. 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwErrorCode

[out] Error code of a mailbox transfer that was terminated with error 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTferId

[] Transfer ID. For every new mailbox transfer a unique ID has to be assigned. This ID can be used after mailbox transfer completion to identify the transfer. 

### [EC_T_MBX_DATA](#_CPPv413EC_T_MBX_DATA) MbxData

[] Mailbox data. This element contains mailbox transfer data, e.g. the CoE object dictionary list. 

### enum EC_T_MBXTFER_TYPE

*Values:*

### enumerator eMbxTferType_COE_SDO_DOWNLOAD

CoE SDO download 

### enumerator eMbxTferType_COE_SDO_UPLOAD

CoE SDO upload 

### enumerator eMbxTferType_COE_GETODLIST

CoE Get object dictionary list 

### enumerator eMbxTferType_COE_GETOBDESC

CoE Get object description 

### enumerator eMbxTferType_COE_GETENTRYDESC

CoE Get object entry description 

### enumerator eMbxTferType_COE_EMERGENCY

CoE emergency request 

### enumerator eMbxTferType_COE_RX_PDO

CoE RxPDO 

### enumerator eMbxTferType_FOE_FILE_UPLOAD

FoE upload 

### enumerator eMbxTferType_FOE_FILE_DOWNLOAD

FoE download 

### enumerator eMbxTferType_SOE_READREQUEST

SoE read request 

### enumerator eMbxTferType_SOE_READRESPONSE

SoE read response 

### enumerator eMbxTferType_SOE_WRITEREQUEST

SoE write request 

### enumerator eMbxTferType_SOE_WRITERESPONSE

SoE write response 

### enumerator eMbxTferType_SOE_NOTIFICATION

SoE notification 

### enumerator eMbxTferType_SOE_EMERGENCY

SoE emergency 

### enumerator eMbxTferType_VOE_MBX_READ

VoE read 

### enumerator eMbxTferType_VOE_MBX_WRITE

VoE write 

### enumerator eMbxTferType_AOE_READ

AoE read 

### enumerator eMbxTferType_AOE_WRITE

AoE write 

### enumerator eMbxTferType_AOE_READWRITE

AoE read/write 

### enumerator eMbxTferType_AOE_WRITECONTROL

AoE write control 

### enumerator eMbxTferType_RAWMBX

Raw mbx 

### enumerator eMbxTferType_FOE_SEG_DOWNLOAD

FoE segmented download 

### enumerator eMbxTferType_FOE_SEG_UPLOAD

FoE segmented upload 

### enumerator eMbxTferType_S2SMBX

S2S mbx 

### enumerator eMbxTferType_FOE_UPLOAD_REQ

FoE upload request 

### enumerator eMbxTferType_FOE_DOWNLOAD_REQ

FoE download request 

### enumerator eMbxTferType_EOE_SEND_FRAME

EoE send frame 

### enumerator eMbxTferType_EOE_RECEIVE_FRAME

EoE receive frame 

### enumerator eMbxTferType_EOE_SET_IP

EoE set IP address 

### union EC_T_MBX_DATA

 *#include <EcInterfaceCommon.h>*

### Public Members

### EC_T_AOE_CMD_RESPONSE AoE_Response

AoE 

### [EC_T_MBX_DATA_COE](api_mbx_coe.html.md#_CPPv417EC_T_MBX_DATA_COE) CoE

CoE 

### [EC_T_COE_ODLIST](api_mbx_coe.html.md#_CPPv415EC_T_COE_ODLIST) CoE_ODList

CoE Object Dictionary list 

### EC_T_COE_OBDESC CoE_ObDesc

CoE object description 

### [EC_T_COE_ENTRYDESC](api_mbx_coe.html.md#_CPPv418EC_T_COE_ENTRYDESC) CoE_EntryDesc

CoE entry description 

### [EC_T_COE_EMERGENCY](api_mbx_coe.html.md#_CPPv418EC_T_COE_EMERGENCY) CoE_Emergency

CoE emergency data 

### EC_T_MBX_DATA_COE_INITCMD CoE_InitCmd

CoE InitCmd 

### [EC_T_MBX_DATA_FOE](api_mbx_foe.html.md#_CPPv417EC_T_MBX_DATA_FOE) FoE

FoE 

### [EC_T_MBX_DATA_FOE_REQ](api_mbx_foe.html.md#_CPPv421EC_T_MBX_DATA_FOE_REQ) FoE_Request

FoE request 

### EC_T_MBX_DATA_SOE SoE

SoE 

### EC_T_SOE_NOTIFICATION SoE_Notification

SoE notification request 

### EC_T_SOE_EMERGENCY SoE_Emergency

SoE emergency request 

## emonMbxTferAbort

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonMbxTferAbort([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](#_CPPv412EC_T_MBXTFER) \*pMbxTfer)

Abort a running mailbox transfer. 

This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) if successful 

Currently only supported for FoE Transfer, CoE Download and CoE Upload.

## emonMbxTferDelete

### EC_T_VOID emonMbxTferDelete([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](#_CPPv412EC_T_MBXTFER) \*pMbxTfer)

Deletes a mailbox transfer object. 

A transfer object may only be deleted if it is in the Idle state.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonNotify - EC_NOTIFY_MBOXRCV

Indicates a mailbox transfer completion.

**emonNotify - EC_NOTIFY_MBOXRCV**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to a structure of type EC_T_MBXTFER, containing the corresponding mailbox transfer object
    * `dwInBufSize`: [in] Size of the transfer object provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

The element [`EC_T_MBXTFER::dwClntId`](#_CPPv4N12EC_T_MBXTFER8dwClntIdE) contains the corresponding ID of the client that is notified, the corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

On error [`EC_T_MBXTFER::eTferStatus`](#_CPPv4N12EC_T_MBXTFER11eTferStatusE) is [`eMbxTferStatus_TferReqError`](#_CPPv4N19EC_T_MBXTFER_STATUS27eMbxTferStatus_TferReqErrorE), on success [`eMbxTferStatus_TferDone`](#_CPPv4N19EC_T_MBXTFER_STATUS23eMbxTferStatus_TferDoneE). In order to reuse the transfer object the application must set it back to [`eMbxTferStatus_Idle`](#_CPPv4N19EC_T_MBXTFER_STATUS19eMbxTferStatus_IdleE).

The [`EC_T_MBXTFER::eMbxTferType`](#_CPPv4N12EC_T_MBXTFER12eMbxTferTypeE) element determines the mailbox transfer type (e.g. [`eMbxTferType_COE_SDO_DOWNLOAD`](#_CPPv4N17EC_T_MBXTFER_TYPE29eMbxTferType_COE_SDO_DOWNLOADE) for a completion of a CoE SDO download transfer).

## emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR

Indicates a WKC error during a mailbox write. Detailed error information is stored in structure [`EC_T_WKCERR_DESC`](notification_error.html.md#_CPPv416EC_T_WKCERR_DESC) which is part of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

**emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR**
: **Parameter**
  : * `pbyInBuf`: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC
    * `dwInBufSize`: [in] Size of the error description provided at pbyInBuf in bytes
    * `pbyOutBuf`: [out] Should be set to EC_NULL
    * `dwOutBufSize`: [in] Should be set to 0
    * `pdwNumOutData`: [out] Should be set to EC_NULL

## emonNotify - EC_NOTIFY_AOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_EOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_SOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](#emonnotify-ec-notify-coe-mbxsnd-wkc-error)

## emonNotify - EC_NOTIFY_VOE_MBXSND_WKC_ERROR

See [emonNotify - EC_NOTIFY_COE_MBXSND_WKC_ERROR](#emonnotify-ec-notify-coe-mbxsnd-wkc-error)