6.5. Generic notification interface

One of the parameters the client has to set when registering with the EtherCAT® MainDevice is a generic notification callback function ( emNotify()). The MainDevice calls this function every time an event (for example an error event) occurs about which the client has to be informed.

Within this callback function the client must not call any active EtherCAT® functions which finally would lead to send EtherCAT® commands (e.g. initiation of mailbox transfers, starting/stopping the MainDevice, sending raw commands). In such cases the behavior is undefined.

This callback function is usually called in the context of the EtherCAT® MainDevice timer thread or the EtherCAT® Real-time Ethernet Driver receiver thread. It may also be called within the context of a user thread (when calling an EtherCAT® MainDevice function). To avoid dead-lock situations the notification callback handler may not use mutex semaphores.

As the whole EtherCAT® operation is blocked while calling this function the error handling must not use much CPU time or even call operating system functions that may block. Usually the error handling will be done in a separate application thread.

6.5.1. Notification callback: emNotify

When a client registers with the EtherCAT® MainDevice the client has to determine a generic notification callback function. The MainDevice calls this function every time an event (for example an error event or operational state change event) occurs about which the client has to be informed. Within this callback function the client must not call any active EtherCAT® functions which finally would lead to sending EtherCAT® commands (e.g. initiation of mailbox transfers, starting/stopping the MainDevice, sending raw commands). In such cases the behavior is undefined. Only EtherCAT® functions which are explicitly marked to be callable within emNotify() may be called.

A further important rule exists due to the fact that this callback function is usually called in the context of the EtherCAT® MainDevice 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.

typedef EC_T_DWORD (*EC_PF_NOTIFY)(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)
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 *pbyInBuf

[in] Notification input parameters

EC_T_DWORD dwInBufSize

[in] Size of notification input parameters in bytes

EC_T_BYTE *pbyOutBuf

[out] Buffer for notification output (result)

EC_T_DWORD dwOutBufSize

[in] Size of buffer at pbyOutBuf in bytes

EC_T_DWORD *pdwNumOutData

[out] Amount of bytes written to pbyOutBuf by notification. EC_NULL: amount not set by notification.

6.5.2. emNotify - EC_NOTIFY_STATECHANGED

Notification about a change in the MainDevice’s operational state. This notification is enabled by default.

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

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED for how to control the deactivation

6.5.3. emNotify - EC_NOTIFY_XXXX

Notification about an error.

emNotify - EC_NOTIFY_XXXX
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_ERROR_NOTIFICATION_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

See also

Diagnosis, error detection, error notifications

6.5.4. Feature Pack MainDevice Redundancy Notifcations

See also

Feature Pack “MainDevice Redundancy”

6.5.5. emNotifyApp

By calling this function the generic notification callback function setup by emRegisterClient() is called for all clients including RAS.

static EC_T_DWORD ecatNotifyApp(EC_T_DWORD dwCode, EC_T_NOTIFYPARMS *pParms)
EC_T_DWORD emNotifyApp(EC_T_DWORD dwInstanceID, EC_T_DWORD dwCode, EC_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 or first error code different from EC_E_ERROR and EC_E_INVALIDPARM of registered clients’ callback functions

The maximum value for dwCode is defined by EC_NOTIFY_APP_MAX_CODE

6.5.6. emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED

The following notifications can be enabled or disabled.

EC_IOCTL_SET_NOTIFICATION_ENABLED

Set notification enabled state. With EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwCode set to EC_ALL_NOTIFICATIONS, all notifications can be changed at once. EC_T_SET_NOTIFICATION_ENABLED_PARMS::dwEnabled set to EC_NOTIFICATION_DEFAULT, resets to default.

Parameters

  • pbyInBuf – [in] Pointer to EC_T_SET_NOTIFICATION_ENABLED_PARMS.

  • 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

Returns

EC_E_NOERROR or error code

struct EC_T_SET_NOTIFICATION_ENABLED_PARMS

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code or EC_ALL_NOTIFICATIONS

EC_T_DWORD dwEnabled

[in] Enable, disable or reset to default notification. See EC_NOTIFICATION_ flags.

Notifications are given to clients if enabled for dwClientId = 0 AND corresponding dwClientId.

6.5.7. emIoCtl - EC_IOCTL_GET_NOTIFICATION_ENABLED

EC_IOCTL_GET_NOTIFICATION_ENABLED

The enabled state of notifications can be retrieved using EC_IOCTL_GET_NOTIFICATION_ENABLED.

Parameters

  • pbyInBuf – [in] Pointer to EC_T_GET_NOTIFICATION_ENABLED_PARMS

  • dwInBufSize – [in] Size of the input buffer provided at pbyInBuf in bytes

  • pbyOutBuf – [out] Pointer to EC_T_BOOL to carry out current enable set

  • dwOutBufSize – [in] Size of the output buffer provided at pbyOutBuf in bytes

  • pdwNumOutData – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer

Returns

EC_E_NOERROR or error code

struct EC_T_GET_NOTIFICATION_ENABLED_PARMS

Public Members

EC_T_DWORD dwClientId

[in] Client ID, 0: Master

EC_T_DWORD dwCode

[in] Notification code

See also

emIoCtl - EC_IOCTL_SET_NOTIFICATION_ENABLED