BACnetStack_AddRecipientToNotificationClass

bool BACnetStack_AddRecipientToNotificationClass(
  const uint32_t deviceInstance,
  const uint32_t notificationClassInstance,
  const uint8_t validDays,
  const uint8_t fromTimeHour,
  const uint8_t fromTimeMinute,
  const uint8_t fromTimeSecond,
  const uint8_t fromTimeHundredthSecond,
  const uint8_t toTimeHour,
  const uint8_t toTimeMinute,
  const uint8_t toTimeSecond,
  const uint8_t toTimeHundredthSecond,
  const uint32_t processIdentifier,
  const bool issueConfirmedNotifications,
  const bool transitionToOffNormal,
  const bool transitionToFault,
  const bool transitionToNormal,
  const bool useRecipientDeviceChoice,
  const uint32_t recipientDeviceInstance,
  const bool useRecipientAddressChoice,
  const uint16_t recipientNetworkNumber,
  const uint8_t * recipientMacAddress,
  const uint32_t recipientMacAddressLength);

Adds a BACnetDestination that represents a recipient to receive event notifications.

This gets added to an existing Notification Class Object, therefore, a Notification Class Object must exist before this function can be called.

ADDRESS BINDING: a recipient given as ANOTHER device (the device form, not an address) makes this device bind that device’s address (135-2024 cl. 16.10, dynamic binding). It sends a Who-Is for that device instance at once and then on every heartbeat - broadcast until the device answers with an I-Am, directed to its address after. The heartbeat is 3600 s by default; BACnetStackSetting_DABHeartbeatIntervalSeconds changes it, and 0 disables it. The binding is held while any recipient or reference to that device remains.

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.21 (Notification Class Object Type).

Parameters

Parameter	Direction	Description
`deviceInstance`	in	The instance number of the device that owns the Notification Class Object.
`notificationClassInstance`	in	The instance number of the Notification Class Object to add this recipient to.
`validDays`	in	The recipient’s valid days, a BACnetDaysOfWeek BIT STRING (cl. 21; the Recipient_List destination, cl. 12.21.8) packed into one byte: bit 0 (0x01) = Monday, bit 1 = Tuesday, … bit 6 (0x40) = Sunday. Bit 7 (0x80) is UNUSED and is silently ignored, so a caller who assumes Sunday is bit 7 gets a destination with no valid days and no error. 0x7F is every day; 0 is never. (Bit assignment as described above for this parameter; that description is authoritative.)
`fromTimeHour`	in	The hour value of the start time that this recipient can receive notifications.
`fromTimeMinute`	in	The minute value of the start time that this recipient can receive notifications.
`fromTimeSecond`	in	The second value of the start time that this recipient can receive notifications.
`fromTimeHundredthSecond`	in	The hundredth-second value of the start time that this recipient can receive notifications.
`toTimeHour`	in	The hour value of the end time that this recipient can receive notifications.
`toTimeMinute`	in	The minute value of the end time that this recipient can receive notifications.
`toTimeSecond`	in	The second value of the end time that this recipient can receive notifications.
`toTimeHundredthSecond`	in	The hundredth second value of the end time that this recipient can receive notifications.
`processIdentifier`	in	A number identifying which process inside the recipient device the event notifications are meant for.
`issueConfirmedNotifications`	in	Whether to send confirmed notifications (true) or unconfirmed notifications (false).
`transitionToOffNormal`	in	Whether this recipient should be sent To_OffNormal events (true) or not (false).
`transitionToFault`	in	Whether this recipient should be sent To_Fault events (true) or not (false).
`transitionToNormal`	in	Whether this recipient should be sent To_Normal events (true) or not (false). The three transitionTo* flags are the bits of the destination’s transitions field, a BACnetEventTransitionBits BIT STRING (cl. 21).
`useRecipientDeviceChoice`	in	Whether this recipient is a Device Identifier (true) or not (false). Only useRecipientDeviceChoice or useRecipientAddressChoice may be true, not both.
`recipientDeviceInstance`	in	If the recipient is a Device Identifier, this is the device instance of the recipient.
`useRecipientAddressChoice`	in	Whether this recipient is an Address (true) or not (false). Only useRecipientDeviceChoice or useRecipientAddressChoice may be true, not both. The two flags select the device or the address alternative of the destination’s BACnetRecipient CHOICE (cl. 21).
`recipientNetworkNumber`	in	If the recipient is an Address, this is the network number of the recipient. 0 = local network. With recipientMacAddress it makes up the recipient’s BACnetAddress (cl. 21).
`recipientMacAddress`	in	The BACnet MAC Address of the recipient. If BACnet IP, this is the 6-octet byte representation of the IP Address and Port of the device.
`recipientMacAddressLength`	in	The number of bytes of the macAddress. If BACnet IP, this should be 6.

Returns

True on success; false if the device or the Notification Class object does not exist, on allocation failure, if Notification Class support was not compiled, or if useRecipientDeviceChoice and useRecipientAddressChoice are both true or both false - exactly one must be true, and a rejected insert leaves Recipient_List unchanged. There is no list-full failure - the recipient list is unbounded - and no export removes a recipient once added. recipientMacAddress is COPIED, so the caller may free it on return.

Topic: Alarms and events. Declared in CASBACnetStackDLL.h.