# File access over EtherCAT® (FoE)

The File access over EtherCAT® (FoE) mailbox command specifies a standard way to download a firmware or any other files from a client to a server or to upload a firmware or any other files from a server to a client.

Reference:

- ETG.1000.5, ETG.1000.6 and ETG.5003.2

## Specification

### FoE file download

**Regular download**

**Segmented download**

In case of segmented download the EC-Master raises emNotify - EC_NOTIFY_MBOXRCV in the [EC-Master Class B](https://developer.acontis.com/ethercat-manuals.html) documentation to request more data from the application after each ACK from the SubDevice.
The notification handler may not block the EC-Master, e.g. due to reading from or writing to the file system, therefore applications typically do not handle EC_NOTIFY_MBOXRCV within the JobTask context.
The segments are transferred using the SubDevice’s mailbox, so the maximum size of a segment is known from the configuration. The segment’s size can be calculated as follows:

segment size = mailbox size - 12 (protocol overhead)

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::dwMbxOutSize`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO12dwMbxOutSizeE) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`EC_T_CFG_SLAVE_INFO::dwMbxOutSize2`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO13dwMbxOutSize2E) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`EC_T_CFG_SLAVE_INFO::dwMbxInSize`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO11dwMbxInSizeE) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`EC_T_CFG_SLAVE_INFO::dwMbxInSize2`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO12dwMbxInSize2E) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))

**Download with busy**

**Download with error**

### FoE file upload

The names of availables files and their size are SubDevice specific and cannot be retrieved using FoE. It is possible to upload the complete file in segments without the need to know the file size.

The segments are transferred using the SubDevice’s mailbox, so the maximum size of a segment is known from the configuration.

**Regular upload**

### Boot State

For the download of firmware the BOOT state in the EtherCAT® state machine is defined. In bootstrap mode only FoE Download is possible. A special Mailbox size can be supported by the SubDevice for the Boot state (ETG.2000). This is part of the Init-Commands in the network configuration.

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::dwMbxOutSize2`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO13dwMbxOutSize2E) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`EC_T_CFG_SLAVE_INFO::dwMbxInSize2`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO12dwMbxInSize2E) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))

## emFoeFileDownload

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeFileDownload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeFileDownload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Execute an FoE File download to an EtherCAT slave device. 

This function is used to download a complete file. The function returns after the download has been successfully completed or an error has occurred. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **achFileName** – [in] File name of slave file to write 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **pbyData** – [in] Buffer containing transferred data 
  * **dwDataLen** – [in] Buffer length [bytes] 
  * **dwPassword** – [in] Slave password 
  * **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_FOE_ERRCODE_NOTINBOOTSTRAP](error-codes_foe.html.md#d0/d24/group___e_c___e_r_r_o_r___c_o_d_e_s___f_o_e_1ga5e685fe449018e4bca5184fb4d70047e) if slave in BOOTSTRAP and filename not accepted by slave
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error code](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

The following example demonstrates how to do a firmware update using FoE (ETG.5003.2).

### **emFoeFileDownload() Example**

This example code shows how to download a file from a buffer at the EC-Master to a SubDevice, e.g. in order to update the firmware.

```cpp
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    EC_T_WORD  wSlaveAddress = MY_FOE_SLAVE_ADDRESS /* e.g. 1001 */;
    EC_T_DWORD dwSlaveId = ecatGetSlaveId(wSlaveAddress);

    FILE*      pfLocalFile = EC_NULL;

    EC_T_BYTE* pbyBuffer = EC_NULL;
    EC_T_DWORD dwBufferSize = 0;

    /* read file to buffer */
    pfLocalFile = OsFopen(MY_FOE_TRANSFER_LOCAL_FILENAME, "rb");
    if (EC_NULL == pfLocalFile)
    {
        dwRetVal = EC_E_OPENFAILED;
        goto Exit;
    }
    dwBufferSize = OsGetFileSize(pfLocalFile);

    pbyBuffer = (EC_T_BYTE*)OsMalloc(dwBufferSize);
    if (EC_NULL == pbyBuffer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    dwRes = (EC_T_DWORD)OsFread(pbyBuffer, 1, dwBufferSize, pfLocalFile);
    if (dwRes != dwBufferSize)
    {
        dwRetVal = EC_E_ERROR;
        goto Exit;
    }

    /* download buffer to slave */
    dwRes = ecatFoeFileDownload(dwSlaveId, MY_FOE_TRANSFER_SLAVE_FILENAME,
        (EC_T_DWORD)OsStrlen(MY_FOE_TRANSFER_SLAVE_FILENAME),
        pbyBuffer, dwBufferSize, 0, 600000 /* 10 minutes */);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    /* free resources */
    if (EC_NULL != pfLocalFile)
    {
        OsFclose(pfLocalFile);
    }
    OsSafeFree(pbyBuffer);
```

## emFoeFileUpload

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeFileUpload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwOutDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeFileUpload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) \*pdwOutDataLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Execute an FoE File upload from an EtherCAT slave device. 

This function is used to upload a complete file. The function returns after the upload has been successfully completed or an error has occurred. This function may not be called from within the JobTask’s context.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **achFileName** – [in] File name of slave file to read 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **pbyData** – [out] Buffer receiving transfered data 
  * **dwDataLen** – [in] Buffer length [bytes] 
  * **pdwOutDataLen** – [out] Length of received data [byte] 
  * **dwPassword** – [in] Slave password 
  * **dwTimeout** – [in] Timeout [ms]. The function will block at most for this time. 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_TIMEOUT](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_1ga2d09527654c655e159d26d36143674cb) if dwTimeout elapsed during the API call
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error code](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emFoeDownloadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeDownloadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeDownloadReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates an FoE File download to an EtherCAT slave device. 

This function is used to download a complete file and returns immediately. After the download has been successfully completed or an error has occurred, EC_NOTIFY_MBOXRCV is raised. The progress of the file transfer is also notified with EC_NOTIFY_MBOXRCV.

### *Deprecated:*

EC_NOWAIT as a timeout is still accepted for reasons of compatibility and sets the timeout to 10 seconds

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object 
  * **dwSlaveId** – [in] Slave ID 
  * **achFileName** – [in] File name of slave file to write 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **dwPassword** – [in] Slave password 
  * **dwTimeout** – [in] Timeout [ms] 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error codes](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

The following example demonstrates how to perform a FoE Download.

### **emFoeDownloadReq() Example**

This example code shows how to initiate file download to a SubDevice using emFoeDownloadReq(), e.g. in order to update the firmware.

```cpp
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    EC_T_WORD  wSlaveAddress = MY_FOE_SLAVE_ADDRESS /* e.g. 1001 */;
    EC_T_DWORD dwSlaveId = ecatGetSlaveId(wSlaveAddress);

    FILE* pfLocalFile = EC_NULL;

    EC_T_DWORD dwBufferSize = 0;

    /* setup mbx transfers */
    CEcMbxTfer MbxTfer1;
    MbxTfer1.Create(FOE_BUFFER_SIZE);

    /* read file to buffer */
    pfLocalFile = OsFopen(MY_FOE_TRANSFER_LOCAL_FILENAME, "rb");
    if (EC_NULL == pfLocalFile)
    {
        dwRetVal = EC_E_OPENFAILED;
        goto Exit;
    }
    dwBufferSize = OsGetFileSize(pfLocalFile);

    dwRes = (EC_T_DWORD)OsFread(MbxTfer1.GetMbxTfer()->pbyMbxTferData, 1, dwBufferSize, pfLocalFile);
    if (dwRes != dwBufferSize)
    {
        dwRetVal = EC_E_ERROR;
        goto Exit;
    }

    /* download file to slave */
    dwRes = ecatFoeDownloadReq(MbxTfer1.GetMbxTfer(), dwSlaveId, MY_FOE_TRANSFER_SLAVE_FILENAME,
        (EC_T_DWORD)OsStrlen(MY_FOE_TRANSFER_SLAVE_FILENAME),
        0, 600000 /* 10 minutes */);
    /* wait for transfer finished */
    while (eMbxTferStatus_Pend == MbxTfer1.GetMbxTfer()->eTferStatus)
    {
        OsSleep(10);
    }

    /* check transfer result */
    dwRes = MbxTfer1.GetMbxTfer()->dwErrorCode;
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    /* free resources */
    if (EC_NULL != pfLocalFile)
    {
        OsFclose(pfLocalFile);
    }
```

## emFoeSegmentedDownloadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeSegmentedDownloadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeSegmentedDownloadReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates or continues a segmented FoE File download to an EtherCAT slave device. 

This function is used to download a file chunk-by-chunk and returns immediately. An EC_NOTIFY_MBOXRCV is raised to request the next chunk from the application or to provide information about the progress and the change in the transfer status.

The slave may have a different mailbox size for BOOTSTRAP than for PREOP, SAFEOP, OP. See

[EC_T_CFG_SLAVE_INFO.dwMbxInSize2](api_slave_control.html.md#d5/dca/struct_e_c___t___c_f_g___s_l_a_v_e___i_n_f_o_1a3923c1c1189cbbddc469e66528040dee). The maximum chunk size is the slave’s mailbox size - 12 bytes overhead for EtherCAT’s FoE protocol. The mailbox transfer object’s buffer must be at least as big as the chunks to be transferred.

### *Deprecated:*

EC_NOWAIT as a timeout is still accepted for reasons of compatibility and sets the timeout to 10 seconds

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Pointer to the corresponding mailbox transfer object. [EC_T_MBXTFER.pbyMbxTferData](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1ac34001036b1d33234363c1e0773143c7): next chunk, [EC_T_MBXTFER.dwDataLen](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1acdf20a0520615fca75c9f3a1a6ac18ea): next chunk size. 
  * **dwSlaveId** – [in] Slave ID 
  * **szFileName** – [in] File name of slave file to write. Only evaluated when initiating the request. 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **dwFileSize** – [in] Complete file size (mandatory). Used also for progress information. Only evaluated when initiating the request. 
  * **dwPassword** – [in] Slave password. Only evaluated when initiating the request. 
  * **dwTimeout** – [in] Overall timeout [ms] of the FoE transfer. 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error code](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::dwMbxOutSize`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO12dwMbxOutSizeE) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`EC_T_CFG_SLAVE_INFO::dwMbxOutSize2`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO13dwMbxOutSize2E) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

The following example demonstrates how to download a file in segments:

### **emFoeSegmentedDownloadReq() Example**

The following code demonstrates how to send FoE to the SubDevice with address MY_FOE_SLAVE_ADDRESS from a local file.
The data from MY_FOE_TRANSFER_LOCAL_FILENAME is downloaded to MY_FOE_TRANSFER_SLAVE_FILENAME on the SubDevice in this example.

The example code can be placed after the corresponding [`emSetMasterState()`](api_general_functions.html.md#_CPPv416emSetMasterState10EC_T_DWORD10EC_T_DWORD10EC_T_STATE)-call in EcDemoApp.cpp:

```cpp
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes    = EC_E_ERROR;

    EC_T_WORD  wSlaveAddress = MY_FOE_SLAVE_ADDRESS /* e.g. 1001 */;
    EC_T_DWORD dwSlaveId     = ecatGetSlaveId(wSlaveAddress);

    EC_T_CFG_SLAVE_INFO oCfgSlaveInfo;

    FILE*      pfLocalFile = EC_NULL;
    EC_T_DWORD dwFileSize  = 0;

    EC_T_MBXTFER_DESC oMbxTferDesc;
    EC_T_MBXTFER*     pMbxTfer     = EC_NULL;
    EC_T_BYTE*        pbyBuffer    = EC_NULL;
    EC_T_DWORD        dwBufferSize = 0;

    OsMemset(&oCfgSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_INFO));
    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* get max. FoE segment size */
    dwRes = ecatGetCfgSlaveInfo(EC_TRUE, wSlaveAddress, &oCfgSlaveInfo);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }
    /* mailbox contains mailbox header, FoE header and payload for buffer */
    dwBufferSize = oCfgSlaveInfo.dwMbxOutSize - ETHERCAT_MAX_FOE_MBOX_HDR_LEN;

    /* allocate segment buffer */
    pbyBuffer = (EC_T_BYTE*)OsMalloc(dwBufferSize);
    if (EC_NULL == pbyBuffer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    oMbxTferDesc.pbyMbxTferDescData = pbyBuffer;
    oMbxTferDesc.dwMaxDataLen        = dwBufferSize;
    pMbxTfer = ecatMbxTferCreate(&oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    pMbxTfer->dwTferId = 0x12345678; /* unique ID from application */

    /* open local file */
    pfLocalFile = OsFopen(MY_FOE_TRANSFER_LOCAL_FILENAME /* e.g. (EC_T_CHAR*)"MyFile.dat" */, "rb");
    if (EC_NULL == pfLocalFile)
    {
        dwRetVal = EC_E_OPENFAILED;
        goto Exit;
    }
    dwFileSize = OsGetFileSize(pfLocalFile);

    /* start download */
    pMbxTfer->dwDataLen = dwFileSize;
    dwRes = ecatFoeSegmentedDownloadReq(pMbxTfer, dwSlaveId,
        MY_FOE_TRANSFER_SLAVE_FILENAME /* e.g. (EC_T_CHAR*)"MyFile.dat" */, (EC_T_DWORD)OsStrlen(MY_FOE_TRANSFER_SLAVE_FILENAME),
        dwFileSize, 0, MBX_TIMEOUT /* e.g. 5000 */);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* download file reading segments from disk */
    while ((eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        || (eMbxTferStatus_TferWaitingForContinue == pMbxTfer->eTferStatus))
    {
        /* wait for master ready to accept next segment */
        if (eMbxTferStatus_TferWaitingForContinue == pMbxTfer->eTferStatus)
        {
            /* read next segment from file (returns 0 at EOF, signalling end of transfer) */
            pMbxTfer->dwDataLen = (EC_T_DWORD)OsFread(pMbxTfer->pbyMbxTferData, 1, dwBufferSize, pfLocalFile);

            /* provide segment to master so it can send it to the slave */
            dwRes = ecatFoeSegmentedDownloadReq(pMbxTfer, 0, EC_NULL, 0, 0, 0, 0);
            if (EC_E_NOERROR != dwRes)
            {
                dwRetVal = dwRes;
                goto Exit;
            }
        }
        OsSleep(10);
    }
    if (eMbxTferStatus_TferReqError == pMbxTfer->eTferStatus)
    {
        dwRetVal = pMbxTfer->dwErrorCode;
        goto Exit;
    }

    /* transfer done */
    if (eMbxTferStatus_TferDone == pMbxTfer->eTferStatus)
    {
        dwRetVal = pMbxTfer->dwErrorCode; /* e.g. EC_E_NOERROR */
        pMbxTfer->eTferStatus = eMbxTferStatus_Idle;
    }

Exit:
    /* free resources */
    if (EC_NULL != pfLocalFile)
    {
        OsFclose(pfLocalFile);
    }
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            CEcTimer oTimeout(MBX_TIMEOUT);
            ecatMbxTferAbort(pMbxTfer);
            while ((eMbxTferStatus_Pend == pMbxTfer->eTferStatus) && !oTimeout.IsElapsed())
            {
                OsSleep(100);
            }
        }
        ecatMbxTferDelete(pMbxTfer);
    }
    OsSafeFree(pbyBuffer);
```

## emFoeUploadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeUploadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeUploadReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*achFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates an FoE File upload from an EtherCAT slave device. 

This function is used to upload a complete file and returns immediately. After the upload has been successfully completed or an error has occurred, EC_NOTIFY_MBOXRCV is raised. The progress of the file transfer is also notified with EC_NOTIFY_MBOXRCV.

### *Deprecated:*

EC_NOWAIT as a timeout is still accepted for reasons of compatibility and sets the timeout to 10 seconds

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object 
  * **dwSlaveId** – [in] Slave ID 
  * **achFileName** – [in] File name of slave file to read 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **dwPassword** – [in] Slave password 
  * **dwTimeout** – [in] Timeout [ms] 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error code](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
[`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emFoeSegmentedUploadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatFoeSegmentedUploadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emFoeSegmentedUploadReq([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, const [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*szFileName, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileNameLen, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileSize, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwPassword, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates or continues a segmented FoE File upload from an EtherCAT slave device. 

This function is used to upload a file chunk-by-chunk and returns immediately. An EC_NOTIFY_MBOXRCV is raised to provide the next chunk to the application or to get information about the progress and the change in the transfer status.

The slave may have a different mailbox size for BOOTSTRAP than for PREOP, SAFEOP, OP. See

[EC_T_CFG_SLAVE_INFO.dwMbxInSize2](api_slave_control.html.md#d5/dca/struct_e_c___t___c_f_g___s_l_a_v_e___i_n_f_o_1a3923c1c1189cbbddc469e66528040dee). The maximum chunk size is the slave’s mailbox size - 12 bytes overhead for EtherCAT’s FoE protocol. The mailbox transfer object’s buffer must be at least as big as the chunks to be transferred.

### *Deprecated:*

EC_NOWAIT as a timeout is still accepted for reasons of compatibility and sets the timeout to 10 seconds

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Pointer to the corresponding mailbox transfer object. [EC_T_MBXTFER.pbyMbxTferData](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1ac34001036b1d33234363c1e0773143c7): next chunk, [EC_T_MBXTFER.dwDataLen](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1acdf20a0520615fca75c9f3a1a6ac18ea): next chunk size. 
  * **dwSlaveId** – [in] Slave ID 
  * **szFileName** – [in] File name of slave file to write. Only evaluated when initiating the request. 
  * **dwFileNameLen** – [in] Length of slave file name in bytes 
  * **dwFileSize** – [in] Used only for progress information 
  * **dwPassword** – [in] Slave password. Only evaluated when initiating the request. 
  * **dwTimeout** – [in] Overall timeout [ms] of the FoE transfer. 
* **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
  * [EC_E_INVALIDSTATE](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_1ga2a6310e052fca1b94797e8e26f031739) if EtherCAT stack isn’t initialized
  * [EC_E_INVALIDPARM](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_1ga1e10d9022db11a708658c71b0dead2fe) if dwInstanceID is out of range or maximum file name length of 64 bytes (MAX_FILE_NAME_SIZE) exceeded
  * [EC_E_MASTER_RED_STATE_INACTIVE](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_1gae2870f20d370920995e27b2a78171a5e) if Master Redundancy is configured and master is inactive
  * [FoE error code](error-codes_foe.html.md#d0-d24-group-e-c-e-r-r-o-r-c-o-d-e-s-f-o-e)

#### SEE ALSO
- [`EC_T_CFG_SLAVE_INFO::dwMbxInSize`](api_slave_control.html.md#_CPPv4N19EC_T_CFG_SLAVE_INFO11dwMbxInSizeE) ([`emGetCfgSlaveInfo()`](api_slave_control.html.md#_CPPv417emGetCfgSlaveInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORDP19EC_T_CFG_SLAVE_INFO))
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

The following example demonstrates how to upload a file in segments:

### **emFoeSegmentedUploadReq() Example**

The following code demonstrates how to receive FoE from the SubDevice with address MY_FOE_SLAVE_ADDRESS and store it in a file.
The data uploaded from MY_FOE_TRANSFER_SLAVE_FILENAME of the SubDevice is stored in a file with filename MY_FOE_TRANSFER_LOCAL_FILENAME in this example.

The example code can be placed after the corresponding [`emSetMasterState()`](api_general_functions.html.md#_CPPv416emSetMasterState10EC_T_DWORD10EC_T_DWORD10EC_T_STATE)-call in EcDemoApp.cpp:

```cpp
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    EC_T_WORD  wSlaveAddress = MY_FOE_SLAVE_ADDRESS /* e.g. 1001 */;
    EC_T_DWORD dwSlaveId = ecatGetSlaveId(wSlaveAddress);

    EC_T_CFG_SLAVE_INFO oCfgSlaveInfo;

    FILE*               pfLocalFile = EC_NULL;
    EC_T_DWORD          dwFileSize = 0;

    EC_T_MBXTFER_DESC   oMbxTferDesc;
    EC_T_MBXTFER*       pMbxTfer = EC_NULL;
    EC_T_BYTE*          pbyBuffer = EC_NULL;
    EC_T_DWORD          dwBufferSize = 0;

    OsMemset(&oCfgSlaveInfo, 0, sizeof(EC_T_CFG_SLAVE_INFO));
    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* get max. FoE segment size */
    dwRes = ecatGetCfgSlaveInfo(EC_TRUE, wSlaveAddress, &oCfgSlaveInfo);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }
    /* mailbox contains mailbox header, FoE header and payload for buffer */
    dwBufferSize = oCfgSlaveInfo.dwMbxInSize - ETHERCAT_MAX_FOE_MBOX_HDR_LEN;

    /* allocate segment buffer */
    pbyBuffer = (EC_T_BYTE*)OsMalloc(dwBufferSize);
    if (EC_NULL == pbyBuffer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    oMbxTferDesc.pbyMbxTferDescData = pbyBuffer;
    oMbxTferDesc.dwMaxDataLen = dwBufferSize;
    pMbxTfer = ecatMbxTferCreate(&oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    pMbxTfer->dwTferId = 0x12345678; /* uniq ID from application */

    /* open local file */
    pfLocalFile = OsFopen(MY_FOE_TRANSFER_LOCAL_FILENAME /* e.g. (EC_T_CHAR*)"MyFile.dat" */, "wb");
    if (EC_NULL == pfLocalFile)
    {
        dwRetVal = EC_E_OPENFAILED;
        goto Exit;
    }

    /* start upload */
    dwRes = ecatFoeSegmentedUploadReq(pMbxTfer, dwSlaveId,
        MY_FOE_TRANSFER_SLAVE_FILENAME /* e.g. (EC_T_CHAR*)"MyFile.dat" */, (EC_T_DWORD)OsStrlen(MY_FOE_TRANSFER_SLAVE_FILENAME),
        0xFFFFFFFF /* unknown file size */, 0, MBX_TIMEOUT /* e.g. 5000 */);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* upload file writing segments to disk */
    while ((eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        || (eMbxTferStatus_TferWaitingForContinue == pMbxTfer->eTferStatus))
    {
        /* wait for master received data from slave */
        if (eMbxTferStatus_TferWaitingForContinue == pMbxTfer->eTferStatus)
        {
            /* write segment */
            OsFwrite(pMbxTfer->pbyMbxTferData, pMbxTfer->dwDataLen, 1, pfLocalFile);
            dwFileSize = dwFileSize + pMbxTfer->dwDataLen;

            /* acknowledge segment so master can receive the next segment */
            dwRes = ecatFoeSegmentedUploadReq(pMbxTfer, 0, EC_NULL, 0, 0, 0, 0);
            if (EC_E_NOERROR != dwRes)
            {
                dwRetVal = dwRes;
                goto Exit;
            }
        }
        OsSleep(10);
    }
    if (eMbxTferStatus_TferReqError == pMbxTfer->eTferStatus)
    {
        dwRetVal = pMbxTfer->dwErrorCode;
        goto Exit;
    }

    /* transfer done */
    if (eMbxTferStatus_TferDone == pMbxTfer->eTferStatus)
    {
        dwRetVal = pMbxTfer->dwErrorCode; /* e.g. EC_E_NOERROR */
        pMbxTfer->eTferStatus = eMbxTferStatus_Idle;
    }

Exit:
    /* free resources */
    if (EC_NULL != pfLocalFile)
    {
        OsFclose(pfLocalFile);
    }
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            CEcTimer oTimeout(MBX_TIMEOUT);
            ecatMbxTferAbort(pMbxTfer);
            while ((eMbxTferStatus_Pend == pMbxTfer->eTferStatus) && !oTimeout.IsElapsed())
            {
                OsSleep(100);
            }
        }
        ecatMbxTferDelete(pMbxTfer);
    }
    OsSafeFree(pbyBuffer);
```

## emConvertEcErrorToFoeError

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatConvertEcErrorToFoeError([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwErrorCode)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emConvertEcErrorToFoeError([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwErrorCode)

Convert master error code to FoE error code. 

* **Returns:**
  FoE error code according to ETG1000.6 Table 92 - Error codes of FoE 

## emNotify - EC_NOTIFY_FOE_MBXSND_WKC_ERROR

This error will be indicated in case the working counter of an FoE mailbox write command was not set to the expected value of 1.
Detailed error information is stored in the structure [`EC_T_WKCERR_DESC`](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC) of the union element WkcErrDesc.

### struct [EC_T_WKCERR_DESC](api_diagnosis.html.md#_CPPv416EC_T_WKCERR_DESC)

### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) [SlaveProp](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC9SlavePropE)

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) [byCmd](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC5byCmdE)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) [dwAddr](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC6dwAddrE)

### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) [wWkcSet](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC7wWkcSetE)

### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) [wWkcAct](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC7wWkcActE)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) [dwTaskId](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC8dwTaskIdE)

### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) [wMsuId](api_diagnosis.html.md#_CPPv4N16EC_T_WKCERR_DESC6wMsuIdE)

## emNotify - EC_NOTIFY_FOE_MBSLAVE_ERROR

This error will be indicated in case an FoE mailbox SubDevice sends an error message.
Detailed error information is stored in the structure [`EC_T_MBOX_FOE_ABORT_DESC`](#_CPPv424EC_T_MBOX_FOE_ABORT_DESC) of the union element FoeErrorDesc.

### struct EC_T_MBOX_FOE_ABORT_DESC

### Public Members

### [EC_T_SLAVE_PROP](api_diagnosis.html.md#_CPPv415EC_T_SLAVE_PROP) SlaveProp

Slave properties 

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

Error code 

### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) achErrorString[MAX_STD_STRLEN]

FoE error string 

## Extending EC_T_MBX_DATA

FoE transfer data, e.g. progress information in notification.

### struct EC_T_MBX_DATA_FOE

### Public Members

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTransferredBytes

[out] Amount of transferred bytes 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwRequestedBytes

[out] Amount of bytes to be provided by the application 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusyDone

[out] If slave is busy: 0 … dwBusyEntire 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwBusyEntire

[out] If dwBusyEntire > 0: Slave is busy 

### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szBusyComment[EC_FOE_BUSY_COMMENT_SIZE]

[out] Busy Comment from slave 

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFileSize

[out] File size 

### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wStationAddress

[out] Station address of the slave