BACnetStack_SetIntrinsicChangeOfCharacterstringAlgorithm

bool BACnetStack_SetIntrinsicChangeOfCharacterstringAlgorithm(
  const uint32_t deviceInstance,
  const uint16_t objectType,
  const uint32_t objectInstance,
  const char *const * alarmValues,
  const uint32_t * alarmValueLengths,
  const uint8_t * alarmValueEncodings,
  const uint32_t alarmValueCount,
  const uint32_t timeDelay,
  const bool useTimeDelayNormal,
  const uint32_t timeDelayNormal,
  const bool enable);

Enables the ChangeOfCharacterstring intrinsic event algorithm for a characterstringValue object.

The monitored value is the Present_Value (a BACnet CharacterString), compared against a list of alarm strings (135-2024 cl. 13.3.16). The object transitions to OFFNORMAL when the monitored value matches any alarm string and back to NORMAL when it matches none.

The object must exist and have alarms and events enabled by BACnetStack_SetAlarmsAndEventsForObjectEnabled(…, enabled=true) - an Event Enrollment object carries its own and needs no such call; otherwise this returns false.

Matching follows cl. 13.3.16: a non-empty alarm string matches when it appears anywhere inside the monitored string (case-sensitive); an empty alarm string matches only an empty monitored string; and a NULL entry in alarmValues is a Null alarm value, which never matches. When the alarm string and the monitored value are in the same character set, a UCS-2 or UCS-4 match must start on a whole character, and an alarm string that is not a whole number of characters never matches; across two different character sets the octets are compared as they are.

The alarm value parameters are parallel arrays, each of length alarmValueCount. All strings are copied, so the caller may free them on return, and each call REPLACES the previous list. If alarmValues is non-NULL and alarmValueCount > 0, alarmValueLengths must also be non-NULL, or the call is rejected.

BACnet reference: ANSI/ASHRAE 135-2024 clause 13.3.16 (CHANGE_OF_CHARACTERSTRING Event Algorithm).

Parameters

Parameter	Direction	Description
`deviceInstance`	in	The instance number of the device that owns this object.
`objectType, objectInstance`	in	The object for alarms and events: one BACnet Object Identifier, carried as two parameters (see the API conventions).
`alarmValues`	in	Array of alarm strings compared against the monitored Present_Value.
`alarmValueLengths`	in	Array of the number of bytes in each alarm string. Required (non-NULL) whenever alarmValues is non-NULL and alarmValueCount > 0.
`alarmValueEncodings`	in	Array of the character set of each alarm string (0 = UTF-8 / ANSI X3.4). May be NULL to default all entries to 0. An alarm string is matched against Present_Value character by character (clause 13.3.16), case significant: UTF-8 (0), UCS-4 (3), UCS-2 (4) and ISO 8859-1 (5) strings match across those character sets, while a DBCS (1) or JIS X 0208 (2) string matches only a Present_Value in the same character set.
`alarmValueCount`	in	The number of entries in the alarm value arrays.
`timeDelay`	in	How long, in seconds, an offnormal condition has to persist before the event state changes to offnormal.
`useTimeDelayNormal`	in	Whether to use a different time delay value for the timeDelayNormal, or just use the timeDelay value.
`timeDelayNormal`	in	How long, in seconds, a normal condition has to persist before the event state returns to normal.
`enable`	in	Initial inhibit state, inverted - NOT a remove. true arms the algorithm; false leaves it armed but INHIBITED through the object’s Event_Algorithm_Inhibit property (or Reliability_Evaluation_Inhibit for a fault algorithm). Both of those properties are made WRITABLE by BACnetStack_SetAlarmsAndEventsForObjectEnabled(), so a remote client can change the state afterwards. To genuinely remove an armed algorithm, disable the object with BACnetStack_SetAlarmsAndEventsForObjectEnabled(…, enabled=false). Recommended value: true

Returns

True on success; false if the device or object does not exist, the object type does not support this algorithm, alarmValues is non-NULL with a NULL alarmValueLengths, or Alarm-and-Event support was not compiled (STACK_OPTION_ALARMS_AND_EVENTS).

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