Skip to content
Version 6.1.0
Contact Us

BACnetStack_RegisterCallbackReadFileRecord

void BACnetStack_RegisterCallbackReadFileRecord(
  bool (*FPCallbackReadFileRecord)(const uint32_t deviceInstance, const uint32_t fileInstance, const int32_t fileStartRecord, const uint32_t requestedRecordCount, uint8_t *recordData, uint32_t *recordDataLengths, uint32_t *returnedRecordCount, const uint32_t maxRecordCount, const uint32_t maxRecordDataLength, bool *endOfFile, uint32_t *errorCode));

Registers a callback to handle read file requests against File objects whose File_Access_Method is record access, and allows implementors to respond with whole records.

The callback will be called in response to an AtomicReadFile BACnet message.

DECLARED LIMIT - at most 128 records per AtomicReadFile request. The CAS BACnet Stack carries at most 128 records (‘maxRecordCount’) and at most 2048 octets of record data (‘maxRecordDataLength’) in one record-access response. A ‘Requested Record Count’ larger than 128 is clamped to 128 and answered normally; it is not an error and does not abort. The bound is deliberate: the per-record length array and the payload buffer are stack-allocated, and this stack supports embedded targets.

This is a DECLARED DEVIATION FROM THE STANDARD, not just a test failure, and is stated here so it is not discovered during a BTL run:

  • ASHRAE 135-2024 cl. 14.1.5 (normative): the responder reads the number of records the request’s ‘Requested Record Count’ asks for, and may return fewer only when fewer octets or records remain. Clamping returns short while records remain, which that clause does not permit.

  • Where it is observed - ANY 135.1-2023 record-read test that asks for more than 128 records, not just one of them. A BTL preparer scoping to a single test will under-scope:

    • 9.12.1.1.1 (an entire file) - requests every record in the test file and expects ‘End of File’ = TRUE with all of them. This is the read-from-record-0 case.
    • 9.12.1.1.3 (an intermediate point to the end) - requests every record from record n on and expects ‘End of File’ = TRUE with all of them.
    • 9.12.1.1.6 (past the end) - requests more records than remain and expects all remaining records with ‘End of File’ = TRUE. In each case a file of more than 128 records returns 128 with ‘End Of File’ = FALSE instead.

A PICS/EPICS for a product built on this stack must declare the 128-record-per-request limit for record-access File objects. Applications that must serve larger files should keep files at or below 128 records, or use stream access.

Also unimplemented, on both the record and the stream path: a response too large for a single APDU is not segmented.

See also: CASBACnetStack::FPCallbackReadFileRecord

BACnet reference: ANSI/ASHRAE 135-2024 clause 14.1 (AtomicReadFile Service).

Parameters

Section titled “Parameters”
Parameter Direction Description
FPCallbackReadFileRecord in The function pointer for the CallbackReadFileRecord function. See CASBACnetStack::FPCallbackReadFileRecord for more info.

Callback type

Section titled “Callback type”

FPCallbackReadFileRecord

Topic: Service callbacks. Declared in CASBACnetStackDLL.h.