# File access over EtherCAT® (FoE)

The EC-Monitor can record file transfers via the FoE protocol between an EtherCAT® MainDevice and a SubDevice. These FoE transfers can be forwarded to the application as segmented packets in real time via the notifications [emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD](#emonnotify-embxtfertype-foe-seg-download) and [emonNotify - eMbxTferType_FOE_SEG_UPLOAD](#emonnotify-embxtfertype-foe-seg-upload).

In addition, the FoE transfers can be stored as a file on the file system. The files are automatically created and stored in [`EC_T_MONITOR_INIT_PARMS::szFileStoragePath`](api_general.html.md#_CPPv4N23EC_T_MONITOR_INIT_PARMS17szFileStoragePathE). The file name consists of the following:
: ```default
  <TimeStamp[msec]>_Slave<StationAddress>_<FoeFileName>
  ```

For example:
: ```default
  0123456789_Slave1001_firmware.bin
  ```

The notifications for FoE can be deactivated using the [`EC_T_MBX_PARMS_FOE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE21bDisableNotificationsE) parameter if they are not required or to save computing time.
If no file system is available or file storage is not desired, it can be disabled using the [`EC_T_MBX_PARMS_FOE::bDisableFileStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE19bDisableFileStorageE) parameter.

If both parameters [`EC_T_MBX_PARMS_FOE::bDisableNotifications`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE21bDisableNotificationsE) and [`EC_T_MBX_PARMS_FOE::bDisableFileStorage`](api_general.html.md#_CPPv4N18EC_T_MBX_PARMS_FOE19bDisableFileStorageE) are set, the FoE monitoring is completely deactivated.

## Notification sequence

Once the EC-Monitor detects an FoE transfer, the application is notified via an [emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ](#emonnotify-embxtfertype-foe-download-req) or [emonNotify - eMbxTferType_FOE_UPLOAD_REQ](#emonnotify-embxtfertype-foe-upload-req) notification. This notification contains basic information about the upcoming transfer, e.g. requested file name.

After that, each individual packet is transmitted via an [emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD](#emonnotify-embxtfertype-foe-seg-download) or [emonNotify - eMbxTferType_FOE_SEG_UPLOAD](#emonnotify-embxtfertype-foe-seg-upload) notification. The end of the transfer is set via the [`EC_T_MBXTFER::eTferStatus`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER11eTferStatusE) = [`eMbxTferStatus_TferDone`](api_mbx.html.md#_CPPv4N19EC_T_MBXTFER_STATUS23eMbxTferStatus_TferDoneE).

**Download**

**Upload**

## emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ

Notifies an FoE download request from the EtherCAT® MainDevice to a SubDevice.

**emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ**
: **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 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 parameters that the MainDevice has requested from the SubDevice are stored in the structure [`EC_T_MBX_DATA::FoE_Request`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA11FoE_RequestE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).

### struct EC_T_MBX_DATA_FOE_REQ

### Public Members

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

[out] Station address of the slave 

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

[out] FoE read/write request password 

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) szFileName[EC_MAX_FILE_NAME_SIZE]

[out] Name of the file to be read/write 

## emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD

Transmits a data segment of the ongoing FoE download.

**emonNotify - eMbxTferType_FOE_SEG_DOWNLOAD**
: **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 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 FoE download data segment is stored at [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) with size [`EC_T_MBXTFER::dwDataLen`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER9dwDataLenE) and may have to be buffered by the application.
Access to the memory area [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer is stored in the structure [`EC_T_MBX_DATA::FoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3FoEE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE). Among other things, it contains the SubDevice station address [`EC_T_MBX_DATA_FOE::wStationAddress`](#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE) and the number of bytes already transmitted [`EC_T_MBX_DATA_FOE::dwTransferredBytes`](#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE).

### struct EC_T_MBX_DATA_FOE

### Public Members

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

[out] Amount of transferred bytes 

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

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

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

[out] If slave is busy: 0 … dwBusyEntire 

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

[out] If dwBusyEntire > 0: Slave is busy 

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

[out] Busy Comment from slave 

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

[out] File size 

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

[out] Station address of the slave 

#### NOTE
The elements [`EC_T_MBX_DATA_FOE::dwRequestedBytes`](#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE) and [`EC_T_MBX_DATA_FOE::dwFileSize`](#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE) are not used by the EC-Monitor because they are not known at runtime.

## emonNotify - eMbxTferType_FOE_UPLOAD_REQ

Notifies an FoE upload request from the EtherCAT® MainDevice to a SubDevice.

**emonNotify - eMbxTferType_FOE_DOWNLOAD_REQ**
: **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 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 parameters that the MainDevice has requested from the SubDevice are stored in the structure [`EC_T_MBX_DATA::FoE_Request`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA11FoE_RequestE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).

### struct [EC_T_MBX_DATA_FOE_REQ](#_CPPv421EC_T_MBX_DATA_FOE_REQ)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wStationAddress](#_CPPv4N21EC_T_MBX_DATA_FOE_REQ15wStationAddressE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwPassword](#_CPPv4N21EC_T_MBX_DATA_FOE_REQ10dwPasswordE)

### [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) [szFileName](#_CPPv4N21EC_T_MBX_DATA_FOE_REQ10szFileNameE)[EC_MAX_FILE_NAME_SIZE]

## emonNotify - eMbxTferType_FOE_SEG_UPLOAD

Transmits a data segment of the ongoing FoE upload.

**emonNotify - eMbxTferType_FOE_SEG_UPLOAD**
: **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 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 FoE upload data segment is stored at [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) with size [`EC_T_MBXTFER::dwDataLen`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER9dwDataLenE) and may have to be buffered by the application.
Access to the memory area [`EC_T_MBXTFER::pbyMbxTferData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) outside of the notification caller context is illegal and the results are undefined.

Information about the current transfer is stored in the structure [`EC_T_MBX_DATA::FoE`](api_mbx.html.md#_CPPv4N13EC_T_MBX_DATA3FoEE) which is part of [`EC_T_MBXTFER::MbxData`](api_mbx.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE). Among other things, it contains the SubDevice station address [`EC_T_MBX_DATA_FOE::wStationAddress`](#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE) and the number of bytes already transmitted [`EC_T_MBX_DATA_FOE::dwTransferredBytes`](#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE).

### struct [EC_T_MBX_DATA_FOE](#_CPPv417EC_T_MBX_DATA_FOE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwTransferredBytes](#_CPPv4N17EC_T_MBX_DATA_FOE18dwTransferredBytesE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwRequestedBytes](#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwBusyDone](#_CPPv4N17EC_T_MBX_DATA_FOE10dwBusyDoneE)

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwBusyEntire](#_CPPv4N17EC_T_MBX_DATA_FOE12dwBusyEntireE)

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

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) [dwFileSize](#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE)

### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) [wStationAddress](#_CPPv4N17EC_T_MBX_DATA_FOE15wStationAddressE)

#### NOTE
The elements [`EC_T_MBX_DATA_FOE::dwRequestedBytes`](#_CPPv4N17EC_T_MBX_DATA_FOE16dwRequestedBytesE) and [`EC_T_MBX_DATA_FOE::dwFileSize`](#_CPPv4N17EC_T_MBX_DATA_FOE10dwFileSizeE) are not used by the EC-Monitor because they are not known at runtime.

## emonNotify - 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) which is part of [`EC_T_ERROR_NOTIFICATION_DESC`](notification_error.html.md#_CPPv428EC_T_ERROR_NOTIFICATION_DESC).

### struct EC_T_MBOX_FOE_ABORT_DESC

### Public Members

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

Slave properties 

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

Error code 

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

FoE error string 

## emonConvertEcErrorToFoeError

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonConvertEcErrorToFoeError([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](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