BACnetStack_RegisterCallbackReadFile

void BACnetStack_RegisterCallbackReadFile(
  bool (*FPCallbackReadFile)(const uint32_t deviceInstance, const uint32_t fileInstance, const uint32_t fileStart, const uint32_t requestedCount, uint8_t *fileData, uint32_t *fileDataLength, const uint32_t maxFileDataLength, bool *endOfFile, uint32_t *errorCode));

Registers the callback the stack calls to serve an AtomicReadFile request.

Called from inside BACnetStack_Tick().

A FALSE RETURN IS ANSWERED WITH AN ERROR, NOT AN ABORT. errorCode is preset to success; on a false return the stack answers Result(-) with the code you set and its clause-18 error class (for example invalidFileStartPosition -> SERVICES, fileAccessDenied -> SERVICES, deviceBusy -> DEVICE). An untouched errorCode, other, or a code that cannot be sent as an Error (abortOther included) is answered Error(SERVICES, FILE_ACCESS_DENIED).

requestedCount MEANS DIFFERENT THINGS PER ACCESS METHOD: octets for a stream-access File object, RECORDS for a record-access one. fileDataLength is always in octets and is OUT-only - the stack presets it to 0, so there is no incoming length to read.

Over-reporting is unforgiving in one direction and silent in the other: a fileDataLength larger than maxFileDataLength ABORTS the request, while a stream read longer than requestedCount is CLAMPED to requestedCount, and the stack then decides the answer’s End Of File itself from File_Size: TRUE only if the clamped data still ends at the file’s last octet.

Serving a RECORD-access file through this callback rather than the newer BACnetStack_RegisterCallbackReadFileRecord() requires the packed framing: each record written into the buffer as a 2-octet BIG-endian length followed by that many octets, back to back, ending exactly on a record boundary. A malformed buffer, trailing bytes, or more records than requested all abort the request. At most 128 records fit.

Unregistered, a stream-access read answers Error(SERVICES, OPTIONAL_FUNCTIONALITY_NOT_SUPPORTED); a record-access read with neither this callback nor CallbackReadFileRecord answers Error(SERVICES, INVALID_FILE_ACCESS_METHOD). Registering has no effect if file I/O was not compiled (STACK_OPTION_ATOMIC_FILE_IO).

Note

Requires one of the build options STACK_OPTION_NM_SCCM_A (with the BACnet/SC data link), STACK_OPTION_DM_BR_BACKUP_AND_RESTORE (any of them turns on STACK_OPTION_ATOMIC_FILE_IO, the macro this function checks).

See also: CASBACnetStack::FPCallbackReadFile

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

Parameters

Parameter	Direction	Description
FPCallbackReadFile	in	The function pointer for the CallbackReadFile function. See CASBACnetStack::FPCallbackReadFile for more info.

Callback type

FPCallbackReadFile

Topic: Service callbacks. Declared in CASBACnetStackDLL.h.