Skip to content
Version 6.1.0
Contact Us

BACnetStack_RegisterCallbackSendMessageForPort

void BACnetStack_RegisterCallbackSendMessageForPort(
  uint16_t (*FPCallbackSendMessageForPort)(const uint8_t *message, const uint16_t messageLength, const uint8_t *connectionString, const uint8_t connectionStringLength, const uint32_t networkPortInstance, bool broadcast));

Registers the callback the stack calls to hand one outbound raw BACnet frame to the host’s transport layer.

Fires from inside BACnetStack_Tick() AND synchronously from every BACnetStack_Send* export before that export returns.

THE RETURN IS A BYTE COUNT AND MUST EQUAL messageLength. Return exactly messageLength when the whole frame was accepted for transmission; return 0 when it was not (unknown or closed connection, transport error, transmit queue full). Any other value - including 1/true, or an honest partial count - is treated as a failed send and logged. There is no partial-write or resume contract on any data link.

A return of messageLength means ACCEPTED FOR TRANSMISSION, not delivered. The stack has no later failure channel: a confirmed request that is lost is recovered by the stack’s own APDU timeout/retry, and unconfirmed traffic is simply lost (as with BACnet/IP over UDP). Do not block inside this callback; if the host’s transmit queue for the connection is full, return 0. Report a BACnet/SC socket that fails later through BACnetStack_SetBACnetSCWebSocketStatus().

BACnet/SC accepted connections: connectionString is the per-socket <acceptUri>|client=<token> string the host reported for that peer - see BACnetStack_RegisterCallbackSCStartListening().

Both the message and the connection string are stack-owned and valid only for the duration of the call.

WHERE TO SEND. Read the connection string and the broadcast flag together:

  • broadcast false: send to the connection string as given, and only to it. It can itself be a broadcast address: a remote subnet’s directed broadcast address that a BBMD forwards to, or the MS/TP broadcast MAC 0xFF.
  • broadcast true, no connection string (NULL, length 0): the stack leaves the address to the host. Send the frame as a local broadcast on this port.
  • broadcast true, with a connection string (BACnet/IP only): the frame is a broadcast the host asked for, and the connection string is the address the host passed to its own BACnetStack_Send* call. Send the frame to it. A broadcast the stack chooses itself - a BBMD’s re-broadcast on its own subnet, a broadcast answer to a request, an I-Am-Router-To-Network or Network-Number-Is, or the stack’s own periodic Who-Is - has no connection string (the case above), so send it to the port’s B/IP broadcast address. CASBACnetStack::FPCallbackSendMessageForPort lists every case.
  • BACnet/SC: broadcast is always false. The connection string names the WebSocket connection, and a broadcast is addressed by the destination VMAC inside the frame.
  • MS/TP: the message is the NPDU, and the frame type follows bit 2 of message[1] (the NPCI control octet; cl. 9.7.2): set, BACnet Data Expecting Reply (BACnet Extended Data Expecting Reply when the NPDU is over 501 octets); clear, BACnet Data Not Expecting Reply (or Extended).
  • BACnet/IPv6 (a build with STACK_OPTION_DATA_LINK_LAYER_IPV6): the message is a whole BVLL-IPv6 message (BVLC Type X’82’). broadcast false: the connection string is the peer’s 18-octet B/IPv6 address (16 octets of IPv6 address, then the 2-octet UDP port, most significant octet first); send the datagram to it. broadcast true, no connection string: the message is an Original-Broadcast-NPDU; send it by IPv6 multicast to the BACnet/IPv6 group on this port’s UDP port, which is FF0X::BAC0 for the scope the host configures (Annex U.4; the link-local group FF02::BAC0 is the one every node must support). The stack never gives a connection string with a broadcast on BACnet/IPv6.

If this callback is never registered the stack can answer nothing: each send site logs “CallbackSendMessageForPort does not exist” and drops the frame with no BACnet-level diagnostic.

See also: CASBACnetStack::FPCallbackSendMessageForPort

Parameters

Section titled “Parameters”
Parameter Direction Description
FPCallbackSendMessageForPort in The function pointer for the CallbackSendMessageForPort function. See CASBACnetStack::FPCallbackSendMessageForPort for more info.

Callback type

Section titled “Callback type”

FPCallbackSendMessageForPort

Topic: Data link and system callbacks. Declared in CASBACnetStackDLL.h.