BACnetStack_RegisterHookTextMessage

void BACnetStack_RegisterHookTextMessage(
  bool (*FPHookTextMessage)(const uint32_t sourceDeviceIdentifier, const bool useMessageClass, const uint32_t messageClassUnsigned, const char *messageClassString, const uint32_t messageClassStringLength, const uint8_t messagePriority, const char *message, const uint32_t messageLength, const uint8_t *connectionString, const uint8_t connectionStringLength, const uint32_t networkPortInstance, const uint16_t sourceNetwork, const uint8_t *sourceAddress, const uint8_t sourceAddressLength, uint16_t *errorClass, uint16_t *errorCode));

Registers a hook the stack calls when a ConfirmedTextMessage or UnconfirmedTextMessage is received.

Fires from inside BACnetStack_Tick(). This is the ONLY hook in this group whose return value is read.

For a CONFIRMED text message, returning true sends a SimpleACK and returning false sends an Error built from whatever the hook wrote to errorClass and errorCode. Both are pre-set to 0 before the call, so returning false without writing them sends an Error of class 0, code 0.

For an UNCONFIRMED text message the return value AND both out-parameters are discarded without being examined - nothing is sent back either way.

Text messages are answered at all only in a build with STACK_OPTION_TEXT_MESSAGE and once the application has enabled the service with BACnetStack_SetServiceEnabled() - neither text-message service is enabled by default, and a confirmed request for a service that is not enabled is rejected with UNRECOGNIZED_SERVICE. With the service enabled but NO hook registered, a CONFIRMED text message is answered with Error(SERVICES, SERVICE_REQUEST_DENIED), not a SimpleACK, and an UNCONFIRMED one is ignored.

The message-class string is never NULL: when the peer sent a numeric message class, or none at all, it points at an EMPTY string with length 0. It and the message text both point into stack-owned temporaries valid only for the duration of the call.

Note

Requires the STACK_OPTION_DM_TM_TEXT_MESSAGE build option (it turns on STACK_OPTION_TEXT_MESSAGE, the macro this function checks).

See also: CASBACnetStack::FPHookTextMessage

BACnet reference: ANSI/ASHRAE 135-2024 clause 16.5 (ConfirmedTextMessage Service); clause 16.6 (UnconfirmedTextMessage Service).

Parameters

Parameter	Direction	Description
FPHookTextMessage	in	The function pointer for the HookTextMessage function. See CASBACnetStack::FPHookTextMessage for more info.

Callback type

FPHookTextMessage

Topic: Service callbacks. Declared in CASBACnetStackDLL.h.