# CAN application protocol over EtherCAT® (CoE)

## emCoeSdoDownload

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeSdoDownload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, const [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) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeSdoDownload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, const [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) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Execute a CoE SDO download to an EtherCAT slave device. 

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 
  * **wObIndex** – [in] Object Index 
  * **byObSubIndex** – [in] Object SubIndex. If Complete Access only 0 or 1 allowed. 
  * **pbyData** – [in] Buffer containing transferred data. Must not be EC_NULL if dwDataLen > 0. 
  * **dwDataLen** – [in] Buffer length [bytes]. Can be 0 for example for array. 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **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, pbyData is EC_NULL and dwDataLen > 0, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeSdoDownload Example**

The following code demonstrates how to download a CoE object to a SubDevice using the API [`emCoeSdoDownload()`](#_CPPv416emCoeSdoDownload10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTEPK9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD10EC_T_DWORD).

```cpp
EC_T_DWORD CoeSdoDownloadExample()
{
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    /* slave with station address 2002 used for CoE SDO download */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);
    EC_T_BYTE         abyBuf[4];
    OsMemset(abyBuf, 0, sizeof(abyBuf));

    /* download value 123 to object index 0x40A2, subindex 2, timeout 5s, no complete access */
    EC_SET_FRM_DWORD(abyBuf, 123);
    dwRes = ecatCoeSdoDownload(dwSlaveId, 0x40A2, 2, abyBuf, (EC_T_DWORD)sizeof(abyBuf), 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    return dwRetVal;
}
```

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

## emCoeSdoDownloadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeSdoDownloadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeSdoDownloadReq([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, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Initiates a CoE SDO download to an EtherCAT slave device and returns immediately. 

The length of the data to be downloaded must be set in [EC_T_MBXTFER.dwDataLen](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1acdf20a0520615fca75c9f3a1a6ac18ea). A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub index. If Complete Access only 0 or 1 allowed. 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if the slave is not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if the slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if the slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeSdoDownloadReq Example**

The following code demonstrates how to download a CoE object to a SubDevice using the non-blocking API [`emCoeSdoDownloadReq()`](#_CPPv419emCoeSdoDownloadReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD9EC_T_WORD9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
EC_T_DWORD CoeSdoDownloadReqExample()
{
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    /* needed only for notifications, see
     - ecatRegisterClient(...)
     - pAppContext->pNotificationHandler->GetClientID() */
    EC_T_DWORD        dwClientId = 0;

    /* slave with station address 2002 used for CoE SDO download */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);

    EC_T_MBXTFER*     pMbxTferObject = EC_NULL;
    EC_T_BYTE         abyBuf[4];
    EC_T_MBXTFER_DESC oObjectDataTferDesc;
    OsMemset(abyBuf, 0, sizeof(abyBuf));
    OsMemset(&oObjectDataTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* create mailbox transfer object */
    oObjectDataTferDesc.pbyMbxTferDescData = abyBuf;
    oObjectDataTferDesc.dwMaxDataLen = sizeof(abyBuf);
    pMbxTferObject = ecatMbxTferCreate(&oObjectDataTferDesc);
    if (EC_NULL == pMbxTferObject)
    {
        dwRes = EC_E_NOMEMORY;
        dwRetVal = dwRes;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTferObject->dwClntId = dwClientId;
    pMbxTferObject->dwTferId = 1; /* assigned by application. should be unique for each object */

    /* request download of value 123 to object index 0x40A2, subindex 2, timeout 5s, no complete access */
    EC_SET_FRM_DWORD(abyBuf, 123);
    dwRes = ecatCoeSdoDownloadReq(pMbxTferObject, dwSlaveId, 0x40A2, 2, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* wait for transfer finished */
    while (eMbxTferStatus_Pend == pMbxTferObject->eTferStatus)
    {
        OsSleep(10);
    }

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

    dwRetVal = EC_E_NOERROR;
Exit:
    if (EC_NULL != pMbxTferObject)
    {
        pMbxTferObject->eTferStatus = eMbxTferStatus_Idle;
        ecatMbxTferDelete(pMbxTferObject);
    }

    return dwRetVal;
}
```

#### SEE ALSO
- [emNotify - eMbxTferType_COE_SDO_DOWNLOAD](#emnotify-embxtfertype-coe-sdo-download)
- [`emMbxTferCreate()`](mbx_tfer.html.md#_CPPv415emMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emNotify - eMbxTferType_COE_SDO_DOWNLOAD

SDO download transfer completion.

**emNotify - eMbxTferType_COE_SDO_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 corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The requested parameters stored in element [`EC_T_MBX_DATA::CoE`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA3CoEE) of type [`EC_T_MBX_DATA_COE`](#_CPPv417EC_T_MBX_DATA_COE) are part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_MBX_DATA_COE

### Public Members

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

Station address of the slave 

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

Object index 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) bySubIndex

Object subindex 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bCompleteAccess

Complete access 

## emCoeSdoUpload

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeSdoUpload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [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) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeSdoUpload([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [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) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Execute a CoE SDO upload from an EtherCAT slave device to the master. 

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 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub index. If Complete Access only 0 or 1 allowed. 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataLen** – [in] Buffer length [bytes] 
  * **pdwOutDataLen** – [out] Length of received data [byte] 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeSdoUpload Example**

The following code demonstrates how to upload a CoE object from a SubDevice using the API [`emCoeSdoUpload()`](#_CPPv414emCoeSdoUpload10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTEP9EC_T_BYTE10EC_T_DWORDP10EC_T_DWORD10EC_T_DWORD10EC_T_DWORD).

```cpp
EC_T_DWORD CoeSdoUploadExample()
{
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    /* slave with station address 2002 used for CoE SDO upload */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);
    EC_T_BYTE         abyBuf[4];
    OsMemset(abyBuf, 0, sizeof(abyBuf));

    /* upload object index 0x1018, subindex 1, timeout 5s, no complete access */
    dwRes = ecatCoeSdoUpload(dwSlaveId, 0x1018, 1, abyBuf, (EC_T_DWORD)sizeof(abyBuf), EC_NULL, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = EC_E_NOERROR;
Exit:
    return dwRetVal;
}
```

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

## emCoeSdoUploadReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeSdoUploadReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeSdoUploadReq([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, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwFlags)

Initiates a CoE SDO upload from an EtherCAT slave device to the master and returns immediately. 

A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object created with emMbxTferCreate 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub index. If Complete Access only 0 or 1 allowed. 
  * **dwTimeout** – [in] Timeout [ms] 
  * **dwFlags** – [in] Mailbox Flags. Bit 0: set if Complete Access (EC_MAILBOX_FLAG_SDO_COMPLETE). 
* **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if the ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeSdoUploadReq Example**

The following code demonstrates how to upload a CoE object from a SubDevice using the non-blocking API [`emCoeSdoUploadReq()`](#_CPPv417emCoeSdoUploadReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD9EC_T_WORD9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
EC_T_DWORD CoeSdoUploadReqExample()
{
    EC_T_DWORD dwRetVal = EC_E_ERROR;
    EC_T_DWORD dwRes = EC_E_ERROR;

    /* needed only for notifications, see
     - ecatRegisterClient(...)
     - pAppContext->pNotificationHandler->GetClientID() */
    EC_T_DWORD        dwClientId = 0;

    /* slave with station address 2002 used for CoE SDO upload */
    EC_T_DWORD        dwSlaveId = ecatGetSlaveId(2002);

    EC_T_MBXTFER*     pMbxTferObject = EC_NULL;
    EC_T_BYTE         abyBuf[4];
    EC_T_MBXTFER_DESC oObjectDataTferDesc;
    OsMemset(abyBuf, 0, sizeof(abyBuf));
    OsMemset(&oObjectDataTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));

    /* create mailbox transfer object */
    oObjectDataTferDesc.pbyMbxTferDescData = abyBuf;
    oObjectDataTferDesc.dwMaxDataLen = sizeof(abyBuf);
    pMbxTferObject = ecatMbxTferCreate(&oObjectDataTferDesc);
    if (EC_NULL == pMbxTferObject)
    {
        dwRes = EC_E_NOMEMORY;
        dwRetVal = dwRes;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTferObject->dwClntId = dwClientId;
    pMbxTferObject->dwTferId = 1; /* assigned by application. should be unique for each object */

    /* request upload of object index 0x1018, subindex 1, timeout 5s, no complete access */
    dwRes = ecatCoeSdoUploadReq(pMbxTferObject, dwSlaveId, 0x1018, 1, 5000, 0);
    if (EC_E_NOERROR != dwRes)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* wait for transfer finished */
    while (eMbxTferStatus_Pend == pMbxTferObject->eTferStatus)
    {
        OsSleep(10);

        /* transfer can be canceled using ecatMbxTferAbort(...) if it takes too long */
    }

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

    dwRetVal = EC_E_NOERROR;
Exit:
    if (EC_NULL != pMbxTferObject)
    {
        pMbxTferObject->eTferStatus = eMbxTferStatus_Idle;
        ecatMbxTferDelete(pMbxTferObject);
    }

    return dwRetVal;
}
```

#### SEE ALSO
- [emNotify - eMbxTferType_COE_SDO_UPLOAD](#emnotify-embxtfertype-coe-sdo-upload)
- [`emMbxTferCreate()`](mbx_tfer.html.md#_CPPv415emMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emNotify - eMbxTferType_COE_SDO_UPLOAD

SDO upload transfer completion.

**emNotify - eMbxTferType_COE_SDO_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 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 corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The requested parameters stored in element [`EC_T_MBX_DATA::CoE`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA3CoEE) of type [`EC_T_MBX_DATA_COE`](#_CPPv417EC_T_MBX_DATA_COE) are part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE).
The SDO data stored in [`EC_T_MBXTFER::pbyMbxTferData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) may have to be buffered by the client.
Access to the memory area referenced by [`EC_T_MBXTFER::pbyMbxTferData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER14pbyMbxTferDataE) outside of the notification caller context is illegal and the results are undefined.

## emCoeGetODList

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetODList([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_COE_ODLIST_TYPE](#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_COE_ODLIST](#_CPPv415EC_T_COE_ODLIST) \*poOdList, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetODList([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_COE_ODLIST_TYPE](#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_COE_ODLIST](#_CPPv415EC_T_COE_ODLIST) \*poOdList, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Gets a list of object IDs that are available in a slave. 

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

#### NOTE
The data buffer will receive the slave response containing the list type followed by the list itself. Therefore the buffer must be 2 bytes bigger than the expected list size.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **dwSlaveId** – [in] Slave ID 
  * **eListType** – [in] Which object types shall be transferred 
  * **pbyData** – [out] Buffer receiving transferred data 
  * **dwDataLen** – [in] Buffer length in bytes 
  * **poOdList** – [out] Received OD list object 
  * **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 master 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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### enum EC_T_COE_ODLIST_TYPE

*Values:*

### enumerator eODListType_Lengths

Lengths of each list type 

### enumerator eODListType_ALL

List contains all objects 

### enumerator eODListType_RxPdoMap

List with PDO mappable objects 

### enumerator eODListType_TxPdoMap

List with objects that can be changed 

### enumerator eODListType_StoredFRepl

Only stored for a device replacement objects 

### enumerator eODListType_StartupParm

Only startup parameter objects 

### **emCoeGetODList Example**

The following code demonstrates how to get the list of objects that are available in a SubDevice using the API [`emCoeGetODList()`](#_CPPv414emCoeGetODList10EC_T_DWORD10EC_T_DWORD20EC_T_COE_ODLIST_TYPEP9EC_T_BYTE10EC_T_DWORDP15EC_T_COE_ODLIST10EC_T_DWORD).

```cpp
    EC_T_BYTE*      pbyOdList = EC_NULL;
    EC_T_COE_ODLIST oOdList;
    OsMemset(&oOdList, 0, sizeof(EC_T_COE_ODLIST));

    /* allocate payload memory */
    pbyOdList = (EC_T_BYTE*)OsMalloc(CROD_ODLTFER_SIZE);
    if (EC_NULL == pbyOdList)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    dwRes = emCoeGetODList(dwInstanceId, dwSlaveId, eODListType_ALL, pbyOdList, CROD_ODLTFER_SIZE, &oOdList, 5000 /* timeout */);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetODList: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    dwRetVal = dwRes;
Exit:
    OsSafeFree(pbyOdList);
```

#### SEE ALSO
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
- See `CoeReadObjectDictionary()` in EcSdoServices.cpp as an example for [`emCoeGetODList()`](#_CPPv414emCoeGetODList10EC_T_DWORD10EC_T_DWORD20EC_T_COE_ODLIST_TYPEP9EC_T_BYTE10EC_T_DWORDP15EC_T_COE_ODLIST10EC_T_DWORD) .

## emCoeGetODListReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetODListReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_COE_ODLIST_TYPE](#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetODListReq([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, [EC_T_COE_ODLIST_TYPE](#_CPPv420EC_T_COE_ODLIST_TYPE) eListType, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates retrieval of a list of object IDs that are available in a slave and returns immediately. 

A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

#### NOTE
The mailbox transfer object will receive the slave response containing the list type followed by the list itself. Therefore the buffer must be 2 bytes bigger than the expected list size.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer 
  * **dwSlaveId** – [in] Slave ID 
  * **eListType** – [in] Which object types shall be transferred 
  * **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeGetODListReq Example**

The following code demonstrates how to get the list of objects that are available in a SubDevice using the non-blocking API [`emCoeGetODListReq()`](#_CPPv417emCoeGetODListReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD20EC_T_COE_ODLIST_TYPE10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc;

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_ODLTFER_SIZE;

    /* allocate payload memory */
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    dwRes = emCoeGetODListReq(dwInstanceId, pMbxTfer, dwSlaveId, eODListType_ALL, 5000 /* timeout */);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetODListReq: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    OsSafeFree(oMbxTferDesc.pbyMbxTferDescData);
```

#### SEE ALSO
- [emNotify - eMbxTferType_COE_GETODLIST](#emnotify-embxtfertype-coe-getodlist)
- [`emMbxTferCreate()`](mbx_tfer.html.md#_CPPv415emMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emNotify - eMbxTferType_COE_GETODLIST

Object dictionary list upload transfer completion.

**emNotify - eMbxTferType_COE_GETODLIST**
: **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 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 corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The object list stored in element [`EC_T_MBX_DATA::CoE_ODList`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA10CoE_ODListE) of type [`EC_T_COE_ODLIST`](#_CPPv415EC_T_COE_ODLIST) is part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_ODLIST

### Public Members

### [EC_T_COE_ODLIST_TYPE](#_CPPv420EC_T_COE_ODLIST_TYPE) eOdListType

List type 

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

Amount of object IDs 

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

Station address of the slave 

### [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) \*pwOdList

Array containing object IDs 

## emCoeGetObjectDesc

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetObjectDesc([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*pchObName, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObNameLen, [EC_T_COE_OBDESC](#_CPPv415EC_T_COE_OBDESC) \*poObDesc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetObjectDesc([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*pchObName, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObNameLen, [EC_T_COE_OBDESC](#_CPPv415EC_T_COE_OBDESC) \*poObDesc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Determines the description of a specific object. 

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 
  * **wObIndex** – [in] Object index 
  * **pchObName** – [out] Buffer receiving object name 
  * **wObNameLen** – [in] Buffer length 
  * **poObDesc** – [out] Received object description object 
  * **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 master 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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeGetObjectDesc Example**

The following code demonstrates how to determine the description of a specific object using the API [`emCoeGetObjectDesc()`](#_CPPv418emCoeGetObjectDesc10EC_T_DWORD10EC_T_DWORD9EC_T_WORDP9EC_T_CHAR9EC_T_WORDP15EC_T_COE_OBDESC10EC_T_DWORD).

```cpp
    EC_T_CHAR*      pchObName = EC_NULL;
    EC_T_COE_OBDESC oObDesc;
    OsMemset(&oObDesc, 0, sizeof(EC_T_COE_OBDESC));

    /* allocate payload memory */
    pchObName = (EC_T_CHAR*)OsMalloc(CROD_OBDESC_SIZE);
    if (EC_NULL == pchObName)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    dwRes = emCoeGetObjectDesc(dwInstanceId, dwSlaveId, 0x6411, pchObName, CROD_OBDESC_SIZE, &oObDesc, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetObjectDesc: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    dwRetVal = dwRes;
Exit:
    OsSafeFree(pchObName);
```

#### SEE ALSO
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
- See `CoeReadObjectDictionary()` in EcSdoServices.cpp as an example for [`emCoeGetObjectDesc()`](#_CPPv418emCoeGetObjectDesc10EC_T_DWORD10EC_T_DWORD9EC_T_WORDP9EC_T_CHAR9EC_T_WORDP15EC_T_COE_OBDESC10EC_T_DWORD) .

## emCoeGetObjectDescReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetObjectDescReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetObjectDescReq([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, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates retrieval of the description of a specific object and returns immediately. 

A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeGetObjectDescReq Example**

The following code demonstrates how to determine the description of a specific object using the non-blocking API [`emCoeGetObjectDescReq()`](#_CPPv421emCoeGetObjectDescReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD9EC_T_WORD10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc; /* mailbox transfer descriptor */

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_OBDESC_SIZE;

    /* allocate payload memory */
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create mailbox transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }
    dwRes = emCoeGetObjectDescReq(dwInstanceId, pMbxTfer, dwSlaveId, 0x6411, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "emCoeGetObjectDescReq: %s (0x%lx))\n", ecatGetText(dwRes), dwRes));
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    OsSafeFree(oMbxTferDesc.pbyMbxTferDescData);
```

#### SEE ALSO
- [emNotify - eMbxTferType_COE_GETOBDESC](#emnotify-embxtfertype-coe-getobdesc)
- [`emMbxTferCreate()`](mbx_tfer.html.md#_CPPv415emMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emNotify - eMbxTferType_COE_GETOBDESC

Completion of an SDO information service transfer to get an object description.

**emNotify - eMbxTferType_COE_GETOBDESC**
: **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 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 corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The object description stored in element [`EC_T_MBX_DATA::CoE_ObDesc`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA10CoE_ObDescE) of type [`EC_T_COE_OBDESC`](#_CPPv415EC_T_COE_OBDESC) is part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_OBDESC

### Public Members

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

Index in the object dictionary 

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

Data type of the object 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObjCode

Object code, see Table 62, ETG.1000 section 6 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObjCategory

Object category 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byMaxNumSubIndex

Maximum sub index number 

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

Length of the object name 

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

Station address of the slave 

### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) \*pchObName

Object name (not NULL terminated!) 

#### SEE ALSO
A more detailed description of the values for data type, object code etc. can be found in the EtherCAT® specification ETG.1000, section 5.

## emCoeGetEntryDesc

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetEntryDesc([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byValueInfo, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDataLen, [EC_T_COE_ENTRYDESC](#_CPPv418EC_T_COE_ENTRYDESC) \*poEntryDesc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetEntryDesc([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byValueInfo, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wDataLen, [EC_T_COE_ENTRYDESC](#_CPPv418EC_T_COE_ENTRYDESC) \*poEntryDesc, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Determines the description of a specific object entry. 

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 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub-index 
  * **byValueInfo** – [in] The value info bit mask includes which elements shall be in the response. See [Value info flags](#df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o) for available values. 
  * **pbyData** – [out] Buffer receiving additional entry desc data 
  * **wDataLen** – [in] Buffer length in bytes 
  * **poEntryDesc** – [out] Received entry desc object 
  * **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 master 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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeGetEntryDesc Example**

The following code demonstrates how to get the description of a specific object entry using the API [`emCoeGetEntryDesc()`](#_CPPv417emCoeGetEntryDesc10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTE9EC_T_BYTEP9EC_T_BYTE9EC_T_WORDP18EC_T_COE_ENTRYDESC10EC_T_DWORD).

```cpp
    EC_T_BYTE*         pbyData = EC_NULL;
    EC_T_COE_ENTRYDESC oEntryDesc;
    OsMemset(&oEntryDesc, 0, sizeof(EC_T_COE_ENTRYDESC));

    /* allocate payload memory */
    pbyData = (EC_T_BYTE*)OsMalloc(CROD_ENTRYDESC_SIZE);
    if (EC_NULL == pbyData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    dwRes = emCoeGetEntryDesc(dwInstanceId, dwSlaveId, 0x6411, 1, 0, pbyData, CROD_ENTRYDESC_SIZE, &oEntryDesc, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    dwRetVal = dwRes;
Exit:
    OsSafeFree(pbyData);
```

**Value info flags**

<!-- -*- mode: rst -*- -->

<a id="df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o"></a>

### EC_COE_ENTRY_ObjAccess

Object access 

### EC_COE_ENTRY_ObjCategory

Object category 

### EC_COE_ENTRY_PdoMapping

PDO mapping 

### EC_COE_ENTRY_UnitType

Unit type 

### EC_COE_ENTRY_DefaultValue

Default value 

### EC_COE_ENTRY_MinValue

Minimum value 

### EC_COE_ENTRY_MaxValue

Maximum value 

#### SEE ALSO
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)
- See `CoeReadObjectDictionary()` in EcSdoServices.cpp as an example for [`emCoeGetEntryDesc()`](#_CPPv417emCoeGetEntryDesc10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTE9EC_T_BYTEP9EC_T_BYTE9EC_T_WORDP18EC_T_COE_ENTRYDESC10EC_T_DWORD) .

## emCoeGetEntryDescReq

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeGetEntryDescReq([EC_T_MBXTFER](mbx_tfer.html.md#_CPPv412EC_T_MBXTFER) \*pMbxTfer, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwSlaveId, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byValueInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeGetEntryDescReq([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, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex, [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byValueInfo, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwTimeout)

Initiates retrieval of the description of a specific object entry and returns immediately. 

A unique transfer ID must be written into [EC_T_MBXTFER.dwTferId](mbx_tfer.html.md#dd/db6/struct_e_c___t___m_b_x_t_f_e_r_1a36cd53365b5741523a1f5b8777866024). EC_NOTIFY_MBOXRCV is given on completion.

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **pMbxTfer** – [in] Mailbox transfer object 
  * **dwSlaveId** – [in] Slave ID 
  * **wObIndex** – [in] Object index 
  * **byObSubIndex** – [in] Object sub-index 
  * **byValueInfo** – [in] The value info bit mask includes which elements shall be in the response. See [Value info flags](#df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o) for available values. 
  * **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, the input pointer is EC_NULL or contains EC_NULL pointer, or dwTimeout is EC_NOWAIT
  * [EC_E_NOMEMORY](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_1ga48c2a7b288dc6922a8c0eb116495e1fd) if the mailbox protocol queue of the slave is full
  * [EC_E_SLAVE_NOT_PRESENT](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_1ga45555d5de25571188a82d2d76c02dd81) if slave not present
  * [EC_E_NOTFOUND](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_1ga3113f3b6f82bb50e6ab3cde40268730a) if no slave matching dwSlaveId can be found
  * [EC_E_NO_MBX_SUPPORT](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_1ga461eba97c1aa71d0d6bc72202035ad98) if slave has no mailbox support
  * [EC_E_INVALID_SLAVE_STATE](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_1ga9a3a38c9d24ba99a15c7fc3c953e1ff2) if slave is in an invalid state for mailbox transfer
  * [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
  * [EC_E_ADS_IS_RUNNING](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_1gac053cb32c9b2bee0305b0644ef76e933) if ADS server is running
  * [CoE SDO error code](error-codes_coe.html.md#df-d91-group-e-c-e-r-r-o-r-c-o-d-e-s-c-o-e)

### **emCoeGetEntryDescReq Example**

The following code demonstrates how to get the description of a specific object entry using the non-blocking API [`emCoeGetEntryDescReq()`](#_CPPv420emCoeGetEntryDescReq10EC_T_DWORDP12EC_T_MBXTFER10EC_T_DWORD9EC_T_WORD9EC_T_BYTE9EC_T_BYTE10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
    EC_T_MBXTFER*     pMbxTfer = EC_NULL;
    EC_T_MBXTFER_DESC oMbxTferDesc; /* mailbox transfer descriptor */

    OsMemset(&oMbxTferDesc, 0, sizeof(EC_T_MBXTFER_DESC));
    oMbxTferDesc.dwMaxDataLen = CROD_ENTRYDESC_SIZE;

    /* allocate payload memory */
    oMbxTferDesc.pbyMbxTferDescData = (EC_T_BYTE*)OsMalloc(oMbxTferDesc.dwMaxDataLen);
    if (EC_NULL == oMbxTferDesc.pbyMbxTferDescData)
    {
        dwRetVal = EC_E_NOMEMORY;
        goto Exit;
    }

    /* create transfer object */
    pMbxTfer = emMbxTferCreate(dwInstanceId, &oMbxTferDesc);
    if (EC_NULL == pMbxTfer)
    {
        dwRetVal = EC_E_NOMEMORY;

        goto Exit;
    }
    dwRes = emCoeGetEntryDescReq(dwInstanceId, pMbxTfer, dwSlaveId, 0x6411, 1, 0, 5000);
    if (dwRes != EC_E_NOERROR)
    {
        dwRetVal = dwRes;
        goto Exit;
    }

    /* wait for transfer finished, see also emMbxTferAbort(...) */
    while (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
    {
        OsSleep(10);
    }

    dwRetVal = pMbxTfer->dwErrorCode;
Exit:
    if (EC_NULL != pMbxTfer)
    {
        if (eMbxTferStatus_Pend == pMbxTfer->eTferStatus)
        {
            emMbxTferAbort(dwInstanceId, pMbxTfer);
        }
        emMbxTferDelete(dwInstanceId, pMbxTfer);
    }

    OsSafeFree(oMbxTferDesc.pbyMbxTferDescData);
```

#### SEE ALSO
- [emNotify - eMbxTferType_COE_GETENTRYDESC](#emnotify-embxtfertype-coe-getentrydesc)
- [`emMbxTferCreate()`](mbx_tfer.html.md#_CPPv415emMbxTferCreate10EC_T_DWORDP17EC_T_MBXTFER_DESC)
- [`emGetSlaveId()`](api_slave_control.html.md#_CPPv412emGetSlaveId10EC_T_DWORD9EC_T_WORD)

## emNotify - eMbxTferType_COE_GETENTRYDESC

Completion of an SDO information service transfer to get an object entry description.

**emNotify - eMbxTferType_COE_GETENTRYDESC**
: **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 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 corresponding transfer ID can be found in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE). The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The object entry description stored in element [`EC_T_MBX_DATA::CoE_EntryDesc`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA13CoE_EntryDescE) of type [`EC_T_COE_ENTRYDESC`](#_CPPv418EC_T_COE_ENTRYDESC) is part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_ENTRYDESC

### Public Members

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

Index in the object dictionary 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObSubIndex

Sub index in the object dictionary 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byValueInfo

Bit mask which information is included in pbyData. See [Value info flags](#df-db0-group-e-c-c-o-e-e-n-t-r-y-v-a-l-u-e-i-n-f-o). 

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

Object data type according to ETG.1000 

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

Object size (number of bits) 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byObAccess

Access rights. See [Object access flags](#de-d21-group-e-c-c-o-e-e-n-t-r-y-o-b-j-a-c-c-e-s-s). 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bRxPdoMapping

Object is mappable in a RxPDO 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bTxPdoMapping

Object is mappable in a TxPDO 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bObCanBeUsedForBackup

Object can be used for backup 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bObCanBeUsedForSettings

Object can be used for settings 

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

Station address of the slave 

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

Size of the remaining object data 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData

Remaining object data: dwUnitType, pbyDefaultValue, pbyMinValue, pbyMaxValue, pbyDescription

(see ETG.1000.5 and ETG.1000.6)

**Object access flags**

<!-- -*- mode: rst -*- -->

<a id="de-d21-group-e-c-c-o-e-e-n-t-r-y-o-b-j-a-c-c-e-s-s"></a>

### EC_COE_ENTRY_Access_R_PREOP

Read access in Pre-Operational state 

### EC_COE_ENTRY_Access_R_SAFEOP

Read access in Safe-Operational state 

### EC_COE_ENTRY_Access_R_OP

Read access in Operational state 

### EC_COE_ENTRY_Access_W_PREOP

Write access in Pre-Operational state 

### EC_COE_ENTRY_Access_W_SAFEOP

Write access in Safe-Operational state 

### EC_COE_ENTRY_Access_W_OP

Write access in Operational state 

#### SEE ALSO
- An example for the evaluation of [`EC_T_COE_ENTRYDESC::pbyData`](#_CPPv4N18EC_T_COE_ENTRYDESC7pbyDataE) comes with EcMasterDemo.
- A more detailed description of the values can be found in the EtherCAT® specification ETG.1000, section 5 and 6.

## emCoeProfileGetChannelInfo

### static [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) ecatCoeProfileGetChannelInfo([EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bStationAddress, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwChannel, [EC_T_PROFILE_CHANNEL_INFO](#_CPPv425EC_T_PROFILE_CHANNEL_INFO) \*pInfo)

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emCoeProfileGetChannelInfo([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixedAddressing, [EC_T_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wSlaveAddress, [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwChannel, [EC_T_PROFILE_CHANNEL_INFO](#_CPPv425EC_T_PROFILE_CHANNEL_INFO) \*pInfo)

Return information about a configured CoE profile channel from the ENI file. 

* **Parameters:**
  * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) 
  * **bFixedAddressing** – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address 
  * **wSlaveAddress** – [in] Slave address according bFixedAddressing 
  * **dwChannel** – [in] Channel 
  * **pInfo** – [out] Channel info 
* **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 

### struct EC_T_PROFILE_CHANNEL_INFO

### Public Members

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

[out] ProfileNo: “low word of CoE object 0x1000” 

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

[out] AddInfo : “high word of CoE object 0x1000” 

### [EC_T_CHAR](toc_api.html.md#_CPPv49EC_T_CHAR) szDisplayName[ECAT_DEVICE_NAMESIZE]

[out] Display name 

### **emCoeProfileGetChannelInfo Example**

The following code demonstrates how to return information about a configured CoE profile channel from the ENI file using the non-blocking API [`emCoeProfileGetChannelInfo()`](#_CPPv426emCoeProfileGetChannelInfo10EC_T_DWORD9EC_T_BOOL9EC_T_WORD10EC_T_DWORDP25EC_T_PROFILE_CHANNEL_INFO).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
    /* get information about CoE profile channel configured in ENI */
    EC_T_PROFILE_CHANNEL_INFO oInfo;
    dwRes = emCoeProfileGetChannelInfo(dwInstanceId, EC_TRUE, wSlaveAddress, 0, &oInfo);
```

## emNotify - EC_NOTIFY_COE_INIT_CMD

Indicates a COE mailbox transfer completion during SubDevice state transition. This notification is disabled by default.

**emNotify - EC_NOTIFY_COE_INIT_CMD**
: **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 [`EC_T_MBX_DATA::CoE_InitCmd`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA11CoE_InitCmdE) element of type [`EC_T_MBX_DATA_COE_INITCMD`](#_CPPv425EC_T_MBX_DATA_COE_INITCMD) is part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_MBX_DATA_COE_INITCMD

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

Handle passed by EC_IOCTL_ADD_COE_INITCMD, otherwise zero 

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

Transition, e.g. ECAT_INITCMD_I_P 

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

Comment (ENI) 

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

InitCmd result 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bFixed

Fixed flag (ENI) 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byCcs

Client command specifier (read or write access) 

### [EC_T_BOOL](toc_api.html.md#_CPPv49EC_T_BOOL) bCompleteAccess

Complete access 

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

Object Index 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) bySubIndex

Object SubIndex 

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

InitCmd data length 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) \*pbyData

InitCmd data 

#### SEE ALSO
[emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED](api_notifications.html.md#emioctl-ec-ioctl-set-notification-enabled)

## CoE Emergency (emNotify - eMbxTferType_COE_EMERGENCY)

Indication of a CoE emergency request. An [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) is given with [`EC_T_MBXTFER::eMbxTferType`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER12eMbxTferTypeE) = [`EC_T_MBXTFER_TYPE::eMbxTferType_COE_EMERGENCY`](mbx_tfer.html.md#_CPPv4N17EC_T_MBXTFER_TYPE26eMbxTferType_COE_EMERGENCYE).

**emNotify - eMbxTferType_COE_EMERGENCY**
: **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 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

In case of an emergency notification all registered clients will get this notification.
The corresponding mailbox transfer object will be created inside the EC-Master. The content in [`EC_T_MBXTFER::dwTferId`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER8dwTferIdE) is undefined as it is not needed by the client and the MainDevice.
The transfer result is stored in [`EC_T_MBXTFER::dwErrorCode`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER11dwErrorCodeE).

The emergency data stored in element [`EC_T_MBX_DATA::CoE_Emergency`](mbx_tfer.html.md#_CPPv4N13EC_T_MBX_DATA13CoE_EmergencyE) of type [`EC_T_COE_EMERGENCY`](#_CPPv418EC_T_COE_EMERGENCY) is part of [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) and may have to be buffered by the client.
Access to the memory area [`EC_T_MBXTFER::MbxData`](mbx_tfer.html.md#_CPPv4N12EC_T_MBXTFER7MbxDataE) outside of the notification caller context is illegal and the results are undefined.

### struct EC_T_COE_EMERGENCY

### Public Members

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

Error code according to EtherCAT specification 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) byErrorRegister

Error register 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) abyData[EC_COE_EMERGENCY_DATASIZE]

Error data 

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

Slave node address of the faulty slave 

### **CoE Emergency Example**

```cpp
    /* send CoE Emergency */
    EC_T_BYTE abyEmergencyData[6] = { 0x01, 0x02, 0x03, 0x04, 0x05, 0x06 };
    dwRes = esSendSlaveCoeEmergency(dwSimulatorId, wSlaveAddress, 0x1234 /* code */, abyEmergencyData, 6 /* data length */);
    if (dwRes != EC_E_NOERROR)
    {
        EcLogMsg(EC_LOG_LEVEL_ERROR, (pEcLogContext, EC_LOG_LEVEL_ERROR, "esSendSlaveCoeEmergency failed: %s (0x%lx))\n", esGetText(dwSimulatorId, dwRes), dwRes));
        goto Exit;
    }
```

#### SEE ALSO
A more detailed description of the values can be found in the EtherCAT® specification ETG.1000, section 5.

## CoE Abort (emNotify - EC_NOTIFY_MBSLAVE_COE_SDO_ABORT)

The application can abort asynchronous CoE Uploads and Downloads.
The SubDevice may abort CoE Uploads and Downloads which is indicated at the return code of [`emCoeSdoUpload()`](#_CPPv414emCoeSdoUpload10EC_T_DWORD10EC_T_DWORD9EC_T_WORD9EC_T_BYTEP9EC_T_BYTE10EC_T_DWORDP10EC_T_DWORD10EC_T_DWORD10EC_T_DWORD), … .
This notification is given if an SDO transfer aborts while sending init commands.

**emNotify - EC_NOTIFY_MBSLAVE_COE_SDO_ABORT**
: **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 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

Detailed error information is stored in structure [`EC_T_MBOX_SDO_ABORT_DESC`](#_CPPv424EC_T_MBOX_SDO_ABORT_DESC) of the union element SdoAbortDesc.

### struct EC_T_MBOX_SDO_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_WORD](toc_api.html.md#_CPPv49EC_T_WORD) wObjIndex

SDO object index 

### [EC_T_BYTE](toc_api.html.md#_CPPv49EC_T_BYTE) bySubIndex

SDO object sub index 

#### SEE ALSO
[`emMbxTferAbort()`](mbx_tfer.html.md#_CPPv414emMbxTferAbort10EC_T_DWORDP12EC_T_MBXTFER)

## emConvertEcErrorToCoeError

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

### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) emConvertEcErrorToCoeError([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 CoE error code. 

* **Returns:**
  CoE error code according to the following specifications:
  * CoE Abort Codes defined in ETG.1000.6 V1.0.4, Table 41: SDO Abort Codes
  * Additional codes defined in ETG.1020, V1.2.0, Table 21: CoE Abort Codes (extension) 

### **emConvertEcErrorToCoeError Example**

The following code demonstrates how to convert EC-Master error codes to CoE error codes using the non-blocking API [`emConvertEcErrorToCoeError()`](#_CPPv426emConvertEcErrorToCoeError10EC_T_DWORD10EC_T_DWORD).

In this example the mailbox transfer object state is polled. [emNotify - EC_NOTIFY_MBOXRCV](mbx_tfer.html.md#emnotify-ec-notify-mboxrcv) can be used as alternative to polling.

```cpp
    dwCoeError = emConvertEcErrorToCoeError(dwInstanceId, EC_E_NOERROR);
```