BACnetStack_AddFileObject

bool BACnetStack_AddFileObject(
  const uint32_t deviceInstance,
  const uint32_t objectInstance,
  const bool isWritable,
  const bool isConfigurationFile,
  const uint8_t fileAccessMethod);

Adds a File Object.

The device must be added first before this function can be called. The only File properties that are handled and stored by the CAS BACnet Stack are:

• FileAccessMethod (set by this function)
• ReadOnly (set from isWritable; a CallbackGetPropertyBool that answers it takes precedence)
• PropertyList

Callbacks are used to handle other properties. The following list contains the required properties and the Callbacks that are used to get the required data:

    --------------------------------------------------------------------------------
    Property            Datatype            Callback
    --------------------------------------------------------------------------------
    ObjectName          CharacterString     CallbackGetPropertyCharacterString
    FileType            CharacterString     CallbackGetPropertyCharacterString
    FileSize            Unsigned            CallbackGetPropertyUnsignedInteger
                                            CallbackSetPropertyUnsignedInteger (if writable)
    ModificationDate    BACnetDateTime      CallbackGetPropertyDate
                                            CallbackGetPropertyTime
    Archive             Boolean             CallbackGetPropertyBool
                                            CallbackSetPropertyBool
    ReadOnly            Boolean             stored (see above); CallbackGetPropertyBool may answer instead
    RecordCount*        Unsigned            CallbackGetPropertyUnsignedInteger
        (*) Only if FileAccessMethod is set to RecordAccess
    --------------------------------------------------------------------------------

Calling this function again for a File Object that already exists updates the property set to match the fileAccessMethod given on the later call:

• RecordCount is added or removed. ASHRAE 135-2024 Table 12-16 footnote 2 requires this: the property exists only on a file whose File_Access_Method is RECORD_ACCESS.
• FileSize is made writable for a writable stream-access file and non-writable otherwise. Only the first half is required (footnote 1 makes FileSize writable when the file is stream-access and its size can change by writing to it - a sufficient condition, not a prohibition). Withholding a writable FileSize from a record-access file is a CAS BACnet Stack policy decision: cl. 12.13.6 defines writing FileSize in octets, which has no defined meaning against record boundaries, and a record file resizes through RecordCount.
• The isConfigurationFile listing is add-only: a repeat call will not list the same object twice, but it also will not remove an object from ConfigurationFiles that an earlier call added.

DECLARED LIMIT for record access - at most 128 records per AtomicReadFile request, and at most 2048 octets of record data. This is a deliberate bound (stack-allocated buffers, embedded targets) and it is a declared deviation from ASHRAE 135-2024 cl. 14.1.5, so it must be declared in the PICS/EPICS of a product built on this stack. See BACnetStack_RegisterCallbackReadFileRecord() for the full statement.

Note

Requires all of these build options: one of STACK_OPTION_NM_SCCM_A (with the BACnet/SC data link), STACK_OPTION_DM_BR_BACKUP_AND_RESTORE (for STACK_OPTION_ATOMIC_FILE_IO); and STACK_OPTION_OBJECT_TYPE_FILE.

See also: BACnetStack_ObjectExists(), BACnetStack_RemoveObject()

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.13 (File Object Type).

Parameters

Parameter	Direction	Description
deviceInstance	in	The instance number of the device that owns this File Object.
objectInstance	in	The instance number of this File Object.
isWritable	in	A flag that determines if the file is writable. This sets the File’s ReadOnly property flag to true (if not writable) or false. If writable, the File’s FileSize property is made writable. The CAS BACnet Stack supports only writing a value of 0 to the FileSize property which should delete all the contents of the file but not the file itself.
isConfigurationFile	in	A flag that determines if the file is a configuration file. Configuration files do not increment the DatabaseRevision property when they are added or removed.
fileAccessMethod	in	The File_Access_Method of this File Object, a BACnetFileAccessMethod (cl. 21): Record Access = 0, Stream Access = 1. Any other value is rejected. Record-access File objects are served by the callbacks registered with BACnetStack_RegisterCallbackReadFileRecord() / BACnetStack_RegisterCallbackWriteFileRecord(), and their RecordCount property is enabled automatically. See the repeat-call and record-limit notes above.

Returns

True on success; false if the device does not exist, the object could not be added, File-object support was not compiled, or one of the object’s stored properties could not be saved. IMPORTANT for that last case: the File object may ALREADY be present in Object_List even though false was returned, missing File_Access_Method and/or Read_Only - which makes every AtomicReadFile/AtomicWriteFile against it fail. Read false as “this object is not usable” rather than “nothing happened”, and remove the object or restart configuration.

Topic: Objects and properties. Declared in CASBACnetStackDLL.h.