# Notifications ## Notification handler The application can register a notification handler using [`esRegisterClient()`](api_general.html.md#_CPPv416esRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS) for notifications as described below. A further important rule exists due to the fact that this callback function is usually called in the context of the EC-Simulator stack timer thread. As the whole EtherCAT® operation is blocked while calling this function the notification handler must not use much CPU time or even call operating system functions that may block. Time consuming operations should be executed in separate application threads. Data structure filled with detailed information about the according notification: ### struct EC_T_NOTIFYPARMS Data structure filled with detailed information about the according notification. ### Public Members ### EC_T_VOID \*pCallerData [in] Client depending caller data parameter. This pointer is one of the parameters when the client registers. ### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyInBuf [in] Notification input parameters ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInBufSize [in] Size of notification input parameters in bytes ### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyOutBuf [out] Buffer for notification output (result) ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwOutBufSize [in] Size of buffer at pbyOutBuf in bytes ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) \*pdwNumOutData [out] Amount of bytes written to pbyOutBuf by notification. EC_NULL: amount not set by notification. ## EC_NOTIFY_SLAVE_PRESENCE This notification is given when a SubDevice appears or disappears from the network. **emNotify - EC_NOTIFY_SLAVE_PRESENCE** : **Parameter** : * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_PRESENCE_NTFY_DESC * `dwInBufSize`: [in] Size of the input buffer 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 Disconnecting the SubDevice from the network, powering it off or a bad connection will generate this notification. ### struct EC_T_SLAVE_PRESENCE_NTFY_DESC ### Public Members ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStationAddress Slave station address ### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) bPresent EC_TRUE: present, EC_FALSE: absent ## EC_NOTIFY_SLAVE_STATECHANGED This notification is given when a SubDevice changed its EtherCAT® state. **emNotify - EC_NOTIFY_SLAVES_STATECHANGED** : **Parameter** : * `pbyInBuf`: [in] Pointer to EC_T_SLAVE_STATECHANGED_NTFY_DESC * `dwInBufSize`: [in] Size of the input buffer 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 ### struct EC_T_SLAVE_STATECHANGED_NTFY_DESC ### Public Members ### EC_T_SLAVE_PROP SlaveProp Slave properties ### EC_T_STATE newState New slave state ## EC_NOTIFY_STATECHANGED This notification is given when the MainDevice changes its EtherCAT® state. **emNotify - EC_NOTIFY_STATECHANGED** : **Parameter** : * `pbyInBuf`: [in] Pointer to data of type EC_T_STATECHANGE which contains the old and the new MainDevice operational state * `dwInBufSize`: [in] Size of the input buffer 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 ### struct EC_T_STATECHANGE ### Public Members ### EC_T_STATE oldState Old operational state ### EC_T_STATE newState New operational state ## EC_NOTIFY_HC_TOPOCHGDONE This notification is given by eUsrJob_SimulatorTimer when the topology changes. **emNotify - EC_NOTIFY_HC_TOPOCHGDONE** : **Parameter** : * `pbyInBuf`: [in] Should be set to EC_NULL * `dwInBufSize`: [in] Should be set to 0 * `pbyOutBuf`: [out] Should be set to EC_NULL * `dwOutBufSize`: [in] Should be set to 0 * `pdwNumOutData`: [out] Should be set to EC_NULL #### SEE ALSO [`esPowerSlave()`](api_network_operation_functions.html.md#_CPPv412esPowerSlave10EC_T_DWORD9EC_T_WORD9EC_T_BOOL) , [`esDisconnectPort()`](api_network_operation_functions.html.md#_CPPv416esDisconnectPort10EC_T_DWORD9EC_T_WORD9EC_T_BYTE) , [`esConnectPorts()`](api_network_operation_functions.html.md#_CPPv414esConnectPorts10EC_T_DWORD9EC_T_WORD9EC_T_BYTE10EC_T_DWORD9EC_T_WORD9EC_T_BYTE) ## EC_NOTIFY_SLAVE_ERROR_STATUS_INFO This notification is given when the Error bit on the specific SubDevice is set or cleared Detailed error information is stored in structure [`EC_T_SLAVE_ERROR_INFO_DESC`](#_CPPv426EC_T_SLAVE_ERROR_INFO_DESC) of `EC_T_ERROR_NOTIFICATION_DESC`. ### struct EC_T_SLAVE_ERROR_INFO_DESC ### Public Members ### EC_T_SLAVE_PROP SlaveProp Slave properties ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStatus Slave Status (AL Status) ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wStatusCode Error status code (AL STATUS CODE) ## EC_NOTIFY_EEPROM_OPERATION This notification is given, when a SubDevice EEPROM is written by the MainDevice. **emNotify - EC_NOTIFY_EEPROM_OPERATION** : **Parameter** : * `pbyInBuf`: [in] Pointer to EC_T_EEPROM_OPERATION_NTFY_DESC * `dwInBufSize`: [in] Size of the input buffer 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 ### struct EC_T_EEPROM_OPERATION_NTFY_DESC ### Public Members ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTferId Transfer ID. For every new EEPROM operation a unique ID has to be assigned. This ID can be used after completion to identify the transfer. ### [EC_T_EEPROM_OPERATION_TYPE](#_CPPv426EC_T_EEPROM_OPERATION_TYPE) eType Type of EEPROM operation ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwResult Result of EEPROM operation ### EC_T_SLAVE_PROP SlaveProp Slave properties ### union \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT ### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_ACTIVE ### Public Members ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bSlavePDIAccessActive EC_TRUE: EEPROM active by PDI application, EC_FALSE: EEPROM not active ### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_READ ### Public Members ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset Start address of EEPRom operation. Given by API. ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwData Pointer to WORD array containing the data. Given by API. ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwReadLen Number of Words to be read. Given by API. ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwNumOutData Number of Words actually read from EEPRom ### struct \_EC_T_EEPROM_OPERATION_NTFY_DESC_RESULT_WRITE ### Public Members ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wEEPRomStartOffset Start address of EEPRom operation. Given by API. ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) \*pwData Pointer to WORD array containing the data. Given by API. ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwWriteLen Number of Words to be written. Given by API. ### enum EC_T_EEPROM_OPERATION_TYPE *Values:* ### enumerator eEEPRomOp_Unknown Unknown EEPROM operation, only for internal use ### enumerator eEEPRomOp_Assign Assign slave EEPROM operation, used by emAssignSlaveEEPRomReq ### enumerator eEEPRomOp_Active Active slave EEPROM operation, used by emActiveSlaveEEPRomReq ### enumerator eEEPRomOp_Read Read slave EEPRom operation, used by emReadSlaveEEPRomReq ### enumerator eEEPRomOp_Write Write slave EEPRom operation, used by emWriteSlaveEEPRomReq ### enumerator eEEPRomOp_Reload Reload slave EEPRom operation, used by emReloadSlaveEEPRomReq ### enumerator eEEPRomOp_Reset Reset slave EEPRom operation, used by emResetSlaveController ## EC_NOTIFY_FRAME_RESPONSE_ERROR This notification is given, when a Ethernet pause frame (MAC control EtherType 0x8808, Control opcode 0x0001) is received. This may occur if any Flow Control mode is active within the network adapter’s native driver settings. **emNotify - EC_NOTIFY_FRAME_RESPONSE_ERROR** : **Parameter** : * `pbyInBuf`: [in] Pointer to EC_T_ERROR_NOTIFICATION_DESC * `dwInBufSize`: [in] SIZEOF_EC_T_ERROR_NOTIFICATION_FRAME_RSPERR * `pbyOutBuf`: [out] Should be set to EC_NULL * `dwOutBufSize`: [in] Should be set to 0 * `pdwNumOutData`: [out] Should be set to EC_NULL ### struct EC_T_FRAME_RSPERR_DESC ### Public Members ### [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bIsCyclicFrame Indicates whether the lost frame was a cyclic frame ### [EC_T_FRAME_RSPERR_TYPE](#_CPPv422EC_T_FRAME_RSPERR_TYPE) EErrorType Frame response error type ### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxSet Expected IDX value, this value is valid only for acyclic frames in case EErrorType is not equal to eRspErr_UNEXPECTED ### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) byEcCmdHeaderIdxAct Actually received IDX value, this value is only valid for acyclic frames in case of EErrorType is equal to: eRspErr_WRONG_IDX and eRspErr_UNEXPECTED ### [EC_T_WORD](api.html.md#_CPPv49EC_T_WORD) wCycFrameNum Number of the lost cyclic frame from the ENI ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwTaskId Cyclic Task ID (ENI: Cyclic/TaskId). Only valid if bIsCyclicFrame is set ### enum EC_T_FRAME_RSPERR_TYPE *Values:* ### enumerator eRspErr_UNDEFINED Undefined ### enumerator eRspErr_NO_RESPONSE No Ethernet frame received (timeout, frame loss) ### enumerator eRspErr_WRONG_IDX Wrong IDX value in acyclic frame ### enumerator eRspErr_UNEXPECTED Unexpected frame was received ### enumerator eRspErr_FRAME_RETRY Ethernet frame will be re-sent (timeout, frame loss) ### enumerator eRspErr_RETRY_FAIL All retry mechanism fails to re-sent acyclic frames ### enumerator eRspErr_FOREIGN_SRC_MAC Frame with MAC from other Master received ### enumerator eRspErr_NON_ECAT_FRAME Non EtherCAT frame received ### enumerator eRspErr_CRC Ethernet frame with CRC error received ### enumerator eRspErr_ETHERNET_PAUSE_FRAME Ethernet pause frame (flow control) received ## esNotifyApp ### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) esNotifyApp([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwCode, [EC_T_NOTIFYPARMS](#_CPPv416EC_T_NOTIFYPARMS) \*pParms) Calls the notification callback functions of all registered clients. #### NOTE EC_E_ERROR and EC_E_INVALIDPARM from registered clients’ callback functions are ignored. * **Parameters:** * **dwInstanceID** – [in] Instance ID (Multiple EtherCAT Network Support) * **dwCode** – [in] Application specific notification code. dwCode must be <= EC_NOTIFY_APP_MAX_CODE. The callback functions get “EC_NOTIFY_APP | dwCode” as parameter. * **pParms** – [in] Parameter to all callback functions. Note: Output parameters are not transferred from RAS client to RAS server. * **Returns:** [EC_E_ERROR](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_1gae45dc6c94a43aa671697ecc700555c22) or first error code different from [EC_E_ERROR](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_1gae45dc6c94a43aa671697ecc700555c22) and [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) of registered clients’ callback functions