BACnetStack_RegisterCallbackWriteFile

void BACnetStack_RegisterCallbackWriteFile(
  bool (*FPCallbackWriteFile)(const uint32_t deviceInstance, const uint32_t fileInstance, const int32_t fileStart, const uint8_t *fileData, const uint32_t fileDataLength, int32_t *ackFileStart, uint32_t *errorCode));

Registers the callback the stack calls to apply an AtomicWriteFile request.

Called from inside BACnetStack_Tick().

fileStart IS SIGNED AND -1 MEANS APPEND. The stack passes -1 straight through (135-2024 cl. 14.2.2.2.1 / 14.2.2.3.1) and only rejects values below -1 before calling you. You MUST resolve -1 to the real position the write began at and report it in ackFileStart, because that value is copied verbatim into the AtomicWriteFile-ACK. ackFileStart is OUT-only, preset to 0; a negative value left there after a successful write is logged but still sent, and fails 135.1-2023 9.13.1.1.3 (record access) and 9.13.1.2.3 (stream access).

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, fileFull -> OBJECT, 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).

Serving a RECORD-access file through this callback rather than the newer BACnetStack_RegisterCallbackWriteFileRecord() means the data arrives packed: each record as a 2-octet BIG-endian length followed by that many octets, back to back, and fileDataLength is the total framed byte count, NOT a record count. At most 128 records arrive at once.

Unregistered, a stream-access write answers Error(SERVICES, OPTIONAL_FUNCTIONALITY_NOT_SUPPORTED); a record-access write with neither this callback nor CallbackWriteFileRecord answers Error(SERVICES, INVALID_FILE_ACCESS_METHOD). A read-only File object is rejected with Error(SERVICES, FILE_ACCESS_DENIED) before you are called. 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::FPCallbackWriteFile

BACnet reference: ANSI/ASHRAE 135-2024 clause 14.2 (AtomicWriteFile Service).

Parameters

Parameter	Direction	Description
FPCallbackWriteFile	in	The function pointer for the CallbackWriteFile function. See CASBACnetStack::FPCallbackWriteFile for more info.

Callback type

FPCallbackWriteFile

Topic: Service callbacks. Declared in CASBACnetStackDLL.h.