BACnetStack_AddScheduleExceptionEventWithCalendarReference

bool BACnetStack_AddScheduleExceptionEventWithCalendarReference(
  const uint32_t deviceInstance,
  const uint32_t scheduleObjectInstance,
  const uint32_t calendarObjectInstance,
  const uint8_t eventPriority,
  uint32_t * exceptionIndex);

Adds an exception event, defined by a reference to a Calendar object, to a Schedule object’s Exception_Schedule.

Adds a special (exception) event, specified as a reference to a Calendar object (the calendar-reference [1] arm of BACnetSpecialEvent’s period CHOICE, cl. 21.6), to the Exception_Schedule and returns its INDEX via exceptionIndex - a handle you then pass to BACnetStack_AddScheduleExceptionTimeValue() to append (time, value) transitions to that event.

The event’s period matches on every date that the referenced Calendar’s Date_List matches. That requires the Calendar to be stack-held (BACnetStack_AddCalendarObject(), then BACnetStack_AddCalendar*Entry); a Calendar that exists but is not stack-held never matches. Local Calendars only: calendarObjectInstance names a Calendar in this same device.

Lower eventPriority wins when several special events cover the same moment (135-2024 cl. 12.24.8).

SIDE EFFECT - WIRE VISIBLE: a successful call enables the Schedule’s Exception_Schedule property, so it appears in Property_List and is served on a read.

Note

Requires all of these build options: STACK_OPTION_OBJECT_TYPE_SCHEDULE; and STACK_OPTION_OBJECT_TYPE_CALENDAR.

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.24 (Schedule Object Type).

Parameters

Parameter	Direction	Description
deviceInstance	in	The device instance that owns this Schedule object.
scheduleObjectInstance	in	The Schedule object to modify.
calendarObjectInstance	in	The Calendar object instance whose Date_List determines when this event’s period matches. Must already exist on this device (BACnetStack_AddObject()), and must be stack-held (BACnetStack_AddCalendarObject()) for the event to ever match.
eventPriority	in	Tie-break priority, 1..16 (1 = highest). Values outside that range are CLAMPED to 16, not rejected.
exceptionIndex	out	The new special-event index, written only on success. It is zero-based: index 0 is Exception_Schedule array index 1.

Returns

True on success; false if the device, Schedule object or Calendar object does not exist, exceptionIndex is NULL, the Exception_Schedule already holds 255 special events, the stack is out of memory, or Schedule support was not compiled.

Topic: Schedules, calendars, trend logs and other object configuration. Declared in CASBACnetStackDLL.h.