BACnetStack_RegisterCallbackValidateNetworkPortChanges
void BACnetStack_RegisterCallbackValidateNetworkPortChanges( bool (*FPCallbackValidateNetworkPortChanges)(const uint32_t deviceInstance, const uint32_t networkPortInstance, uint32_t *failedPropertyIdentifier, uint16_t *errorClass, uint16_t *errorCode));Registers the host’s part of a VALIDATE_CHANGES written to a Network Port object’s Command property.
135-2024 cl. 12.56.16, VALIDATE_CHANGES: the port validates its properties’ values, each as that property’s own clause specifies, skipping a property that is present but unused for the port’s Network_Type, and records the outcome in Command_Validation_Result (cl. 12.56.18). The command leaves Changes_Pending unchanged, and a device that supports pending changes must support it on the port. Some of those validations need data only the host holds: on a BACnet/SC port, cl. 12.56.100 requires VALIDATE_CHANGES to check the operational certificate (CERTIFICATE_MALFORMED, UNKNOWN_KEY, CERTIFICATE_INVALID, CERTIFICATE_EXPIRED, class SECURITY), and the private key and the certificate data never reach the stack.
WHAT THE STACK DOES on a WriteProperty of Command = VALIDATE_CHANGES (10):
- It checks the port’s pending (written, not yet activated) values itself - the same admissibility checks a ReinitializeDevice ACTIVATE_CHANGES runs before it activates them (for example a pending Network_Number a router port cannot move to, or a pending value whose Set callback is not registered). The first failure is recorded as Error class PROPERTY, code INVALID_CONFIGURATION_DATA, with the property that failed; the host is not called.
- Only if those pass, it calls this callback, on EVERY Network Port type, when one is registered.
- It records the outcome in the port’s Command_Validation_Result (cl. 12.56.18, a BACnetHealth): Timestamp the device’s local date and time (the unspecified datetime with no CallbackGetSystemTime), and either the failure (Error and, when known, Property) or success (Property absent).
- It answers the write with Result(+) whatever the validation outcome - the outcome is in Command_Validation_Result. It changes nothing else: Changes_Pending and every pending value stay as they were, and Command reads IDLE again when the write is answered (the validation is synchronous).
WITHOUT A REGISTERED CALLBACK: a BACnet/SC port answers VALIDATE_CHANGES with Result(-) PROPERTY / OPTIONAL_FUNCTIONALITY_NOT_SUPPORTED, because its certificate validations cannot be done without the host. Every other port type (IPv4, MS/TP, virtual, …) validates with the stack’s own checks only.
Command_Validation_Result is present on every Network Port object the stack creates, because cl. 12.56.18 requires it on any port that supports the VALIDATE_CHANGES command.
RE-ENTRANCY: the callback runs inside the WriteProperty service. As for every callback (see “Callbacks” and “Threading” in docs/_doxygen/api-reference/conventions.md), it must not call back into the stack.
Pass NULL to unregister.
See also: CASBACnetStack::FPCallbackValidateNetworkPortChanges
BACnet reference: ANSI/ASHRAE 135-2024 clause 12.56 (Network Port Object Type).
Parameters
Section titled “Parameters”| Parameter | Direction | Description |
|---|---|---|
FPCallbackValidateNetworkPortChanges |
in | The function pointer for the CallbackValidateNetworkPortChanges function, or NULL. Its parameters are deviceInstance (the device that owns the port), networkPortInstance (the Network Port object whose Command was written), and three out-parameters for a false return: failedPropertyIdentifier (the property that failed; preset to 4294967295, which leaves the Property field absent), errorClass (preset to PROPERTY, 2) and errorCode (preset to INVALID_CONFIGURATION_DATA, 46). Return true when the host’s validation passes. See CASBACnetStack::FPCallbackValidateNetworkPortChanges for more info. |
Callback type
Section titled “Callback type”FPCallbackValidateNetworkPortChanges
Topic: Service callbacks. Declared in CASBACnetStackDLL.h.