BACnetStack_RegisterCallbackEventNotificationReceived

void BACnetStack_RegisterCallbackEventNotificationReceived(
  void (*FPCallbackEventNotificationReceived)(const uint32_t deviceInstance, const bool isConfirmed, const uint32_t processIdentifier, const uint32_t initiatingDeviceIdentifier, const uint16_t eventObjectType, const uint32_t eventObjectInstance, const uint8_t timeStampForm, const uint8_t timeStampYearMinus1900, const uint8_t timeStampMonth, const uint8_t timeStampDay, const uint8_t timeStampWeekday, const uint8_t timeStampHour, const uint8_t timeStampMinute, const uint8_t timeStampSecond, const uint8_t timeStampHundredthSecond, const uint16_t timeStampSequenceNumber, const uint32_t notificationClass, const uint8_t priority, const uint16_t eventType, const char *messageText, const uint32_t messageTextLength, const uint8_t messageTextEncoding, const uint8_t notifyType, const bool useAckRequired, const bool ackRequired, const bool useFromState, const uint16_t fromState, const uint16_t toState, const uint16_t eventValuesChoice, const uint8_t *eventValuesEncoded, const uint16_t eventValuesEncodedLength, const uint8_t *connectionString, const uint8_t connectionStringLength, const uint32_t networkPortInstance, const uint16_t sourceNetwork, const uint8_t *sourceAddress, const uint8_t sourceAddressLength));

Registers the callback that receives every valid event notification a local device receives.

Registers a callback that receives the contents of every valid ConfirmedEventNotification and UnconfirmedEventNotification a local device receives - the AE-N-A and AE-VN-A BIBBs an operator display (B-OD) needs: the event object, the time stamp and the message text, without decoding the frame.

The callback fires after the stack has decoded the request, only for a notification whose parameters are all valid and that is addressed to a device this stack hosts. A notification that decodes but is not conformant (for example an unconfirmed ackNotification that carries AckRequired, From_State or Event_Values) is not delivered. It is a notification, not a gate: the confirmed form is answered with a SimpleACK whether or not a callback is registered, and the callback cannot change that.

The device must execute the services: enable them with BACnetStack_SetServiceEnabled(deviceInstance, 2, true) for ConfirmedEventNotification and (deviceInstance, 29, true) for UnconfirmedEventNotification (their BACnetServicesSupported bit numbers, 135-2024 cl. 21.6). A notification for a service no local device executes is not delivered.

It is called once for each local device the stack hands the notification to, each time with that device’s instance. Every pointer argument is valid only for the duration of the call; copy what you keep.

Built only with STACK_OPTION_ALARMS_AND_EVENTS. Without it the export is still present, registering is a no-op (a debug message says the feature was not compiled), and no notification is delivered.

BACnet reference: ANSI/ASHRAE 135-2024 clause 13.8 (ConfirmedEventNotification Service); clause 13.9 (UnconfirmedEventNotification Service).

Parameters

Parameter	Direction	Description
`FPCallbackEventNotificationReceived`	in	The function to call, or NULL to stop. Its parameters: - deviceInstance: the local device that received the notification. - isConfirmed: true for a ConfirmedEventNotification, false for an UnconfirmedEventNotification. - processIdentifier, initiatingDeviceIdentifier, eventObjectType, eventObjectInstance, notificationClass, priority, eventType, notifyType, toState: the notification’s parameters of those names. eventType is a BACnetEventType, notifyType a BACnetNotifyType, and toState (like fromState below) a BACnetEventState (cl. 21). - timeStampForm: the form of the Time Stamp, the BACnetTimeStamp CHOICE tag (0 = time, 1 = sequenceNumber, 2 = dateTime) - the encoding timeOfAcknowledgmentForm uses in BACnetStack_SendAcknowledgeAlarmDateTime(). The date fields are set for form 2, the time fields for forms 0 and 2, timeStampSequenceNumber for form 1; the others are 0. - messageText / messageTextLength / messageTextEncoding: the Message Text (not NUL-terminated), its length in bytes and its character set; NULL / 0 / 0 when the notification omitted it. - useAckRequired / ackRequired, useFromState / fromState: each optional parameter and whether it was present (both are absent from an ackNotification); the value is false / 0 when absent. - eventValuesChoice: the CHOICE tag of the Event Values (BACnetNotificationParameters, for example 5 = out-of-range), so a display can label the alarm without decoding anything; 0xFFFF when absent. - eventValuesEncoded / eventValuesEncodedLength: the Event Values encoded as context tag 12 (opening and closing tags included), re-encoded by the stack from the decoded value - for an application that forwards or logs them; most displays can ignore them. NULL / 0 when absent, and also when the stack could not encode them (eventValuesChoice still names the CHOICE then). - connectionString / connectionStringLength / networkPortInstance: the link and Network Port the frame arrived on. For a routed notification the connection string is the router’s address. - sourceNetwork / sourceAddress / sourceAddressLength: the sender’s network and address when the notification was routed (the NPDU’s SNET and SADR), as BACnetStack_RegisterHookIAm() reports them; 0 / NULL / 0 when it came from the local network. Use them to address a reply, such as BACnetStack_SendAcknowledgeAlarmDateTime(), to a device behind a router. See CASBACnetStack::FPCallbackEventNotificationReceived for the full parameter list.

Callback type

FPCallbackEventNotificationReceived

Topic: Service callbacks. Declared in CASBACnetStackDLL.h.