BACnetStack_SetSegmentationEnabled

bool BACnetStack_SetSegmentationEnabled(
  const uint32_t deviceInstance,
  const uint8_t segmentationSupported,
  const uint32_t maxSegmentsAccepted,
  const uint32_t apduSegmentTimeout,
  const uint8_t proposedWindowSize,
  const uint8_t actualWindowSize,
  const uint8_t maxSegmentsTransmittable,
  const bool enabled);

Enables segmentation and sets up the various parameters used by the segmentation logic.

Also sets up the properties used by the device for segmentation

Receiving segments needs CallbackGetSystemTime: without it a server refuses a segmented request with Abort SEGMENTATION_NOT_SUPPORTED, because its segment timer cannot run. The advertised max-segments-accepted is also capped at what the reassembly buffer holds (STACK_OPTION_MAX_RECEIVED_SEGMENTED_RESPONSE_SIZE divided by Max_APDU_Length_Accepted), and a response beyond it is aborted with BUFFER_OVERFLOW.

RANGES BELOW ARE ENFORCED; an out-of-range value returns false and changes nothing. maxSegmentsAccepted must be 1 for SegmentedTransmit and NoSegmentation, and greater than 1 for SegmentedBoth and SegmentedReceive (cl. 12.11.20); 0 is always rejected. proposedWindowSize and actualWindowSize must each be 1..127 (MIN_WINDOW_SIZE..MAX_WINDOW_SIZE); 0 is rejected. apduSegmentTimeout must be non-zero (cl. 12.11.27) - 0 is rejected unconditionally, not only when Number_Of_APDU_Retries is non-zero, since no legitimate configuration needs a zero segment timeout. maxSegmentsTransmittable is still NOT validated - any value, including 0, is accepted.

apduSegmentTimeout is in MILLISECONDS, as cl. 12.11.27 defines APDU_Segment_Timeout, and is advertised over the wire in those units. The spec-suggested default of 5000 means five seconds. (The segment timer runs on CallbackGetSystemTime(), which is in SECONDS, so the stack converts the milliseconds. Because that clock has one-second resolution the conversion rounds UP with a one-second floor, so a sub-second timeout behaves as one second rather than as already-expired.)

Passing a small number - 5 to mean five seconds - means 5 ms, which the floor turns into one second. Pass 5000.

A client receiving a segmented response waits up to four times apduSegmentTimeout for each next segment (cl. 5.4.4.4’s segment timer limit), then abandons the transaction and reports HookAbort with TSM_TIMEOUT. While segments arrive, the request is not retried.

The trailing enabled argument turns segmentation OFF when false: Segmentation_Supported becomes noSegmentation, Max_Segments_Accepted is reset to 1, and the Max_Segments_Accepted and APDU_Segment_Timeout optional properties are disabled. EVERY OTHER ARGUMENT IS IGNORED when enabled is false, and the call returns true without validating them

BACnet reference: ANSI/ASHRAE 135-2024 clause 5.2 (Segmentation of BACnet Messages).

Parameters

Parameter	Direction	Description
`deviceInstance`	in	The instance of the device to enable segmentation
`segmentationSupported`	in	The segmentation option that the device supports, 0 = SegmentedBoth, 1 = SegmentedTransmit, 2 = SegmentedReceive, 3 = NoSegmentation. The value is a BACnetSegmentation (cl. 21), served as the Device object’s Segmentation_Supported. All four are accepted. With 0 (SegmentedBoth) or 2 (SegmentedReceive) the device receives segmented messages: as a client it accepts a segmented ComplexACK (its Confirmed-Requests carry segmented-response-accepted = TRUE and max-segments-accepted from maxSegmentsAccepted), and as a server it accepts a segmented Confirmed-Request. With 1 or 3, a segmented ComplexACK is answered with an Abort (INVALID_APDU_IN_THIS_STATE) and reported to HookAbort, as 135-2024 cl. 5.4.4.3 requires.

Parameters

Parameter	Direction	Description
`maxSegmentsAccepted`	in	cl. 12.11.20: must be 1 when the Device object’s Segmentation_Supported is SEGMENTED_TRANSMIT or NO_SEGMENTATION, and more than 1 when it is SEGMENTED_BOTH or SEGMENTED_RECEIVE.
`apduSegmentTimeout`	in	cl. 12.11.27: how many milliseconds to wait before an APDU segment is sent again; 5000 is the suggested default. It may not be 0 while the Device object’s Number_Of_APDU_Retries is not 0. Devices that talk to one another communicate most reliably when all of their Device objects hold the same APDU_Segment_Timeout.
`proposedWindowSize`	in	The most segments this device sends before it has to wait for a SegmentACK (cl. 5.3.2, 5.3.3). The device picks the value as it sees fit, as long as it is from 1 to 127 inclusive, and every segment of a segmented Confirmed-Request-PDU or ComplexACK-PDU carries it in its Proposed Window Size parameter
`actualWindowSize`	in	The supported actual window size that this device uses
`maxSegmentsTransmittable`	in	The maximum number of segments this device is capable of send (usually do to memory constraints)
`enabled`	in	Whether segmentation is enabled. When false the six configuration arguments above (segmentationSupported, maxSegmentsAccepted, apduSegmentTimeout, proposedWindowSize, actualWindowSize, maxSegmentsTransmittable) are ignored and not validated. deviceInstance is still used to locate the device. Recommended value: true.

Returns

True on success; false if the device does not exist or segmentation support was not compiled (STACK_OPTION_SEGMENTATION).

Topic: Device and services. Declared in CASBACnetStackDLL.h.