BACnetStack_AddScheduleExceptionEventWithCalendarEntry

bool BACnetStack_AddScheduleExceptionEventWithCalendarEntry(
  const uint32_t deviceInstance,
  const uint32_t scheduleObjectInstance,
  const uint8_t periodType,
  const uint16_t y1,
  const uint8_t m1,
  const uint8_t d1,
  const uint8_t wd1,
  const uint16_t y2,
  const uint8_t m2,
  const uint8_t d2,
  const uint8_t wd2,
  const uint8_t eventPriority,
  uint32_t * exceptionIndex);

Adds an exception event, defined by a calendar entry, to a Schedule object’s Exception_Schedule.

Adds a special (exception) event, specified as a calendar entry (Date/DateRange/WeekNDay), 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.

This export covers only the calendar-entry form of an exception event. The other CHOICE arm, calendar-reference, is BACnetStack_AddScheduleExceptionEventWithCalendarReference() below - see its doc comment for what is and is not yet implemented there.

Wildcards: month, day and weekday take X’FF’ (255) to mean “any”; a year of 0 means “any year”. A DateRange with year 0 at both specific endpoints recurs every year; when its start falls after its end in the year (Dec 24 .. Jan 2) it runs over New Year. ReadProperty serves year 0 as X’FF’, and a WriteProperty of that value is accepted, although 135-2024 cl. 12.1.7 defines no encoding for “every year” in a DateRange endpoint (only an unspecified or a specific date), so another device may read it differently. 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.

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.
`periodType`	in	Which period form the y/m/d/wd arguments describe: 0 = calendar Date (uses y1/m1/d1/wd1 only), 1 = DateRange (y1/m1/d1 .. y2/m2/d2), 2 = WeekNDay. The value is the BACnetCalendarEntry CHOICE tag (date, date-range, weeknday) that sets the period of the new BACnetSpecialEvent, one element of Exception_Schedule (cl. 12.24, cl. 21).
`y1`	in	Start/only year, full 4-digit; 0 = any year.
`m1`	in	Start/only month, 1..12; 255 = any.
`d1`	in	Start/only day of month, 1..31; 255 = any.
`wd1`	in	Start/only weekday, 1 = Monday .. 7 = Sunday; 255 = any.
`y2`	in	End year (DateRange only), full 4-digit; 0 = any year.
`m2`	in	End month (DateRange only), 1..12; 255 = any.
`d2`	in	End day of month (DateRange only), 1..31; 255 = any.
`wd2`	in	End weekday (DateRange only), 1..7; 255 = any.
`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 or Schedule object does not exist, exceptionIndex is NULL, the Exception_Schedule already holds 255 special events, periodType is not 0, 1 or 2, a field is outside what that period form allows (for a Date or a DateRange endpoint, a year other than 0 or 1900..2154; a Date month other than 1..14 or 255, day other than 1..34 or 255, or weekday other than 1..7 or 255; a DateRange endpoint that is neither fully unspecified - year 0, month and day 255 - nor a specific month 1..12, day 1..31 and weekday 1..7 or 255; a WeekNDay month other than 1..14 or 255, week of month other than 1..9 or 255, or weekday other than 1..7 or 255 - its year is not checked), 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.