BACnetStack_RegisterCallbackReceiveMessageForPort

void BACnetStack_RegisterCallbackReceiveMessageForPort(
  uint16_t (*FPCallbackReceiveMessageForPort)(uint8_t *message, const uint16_t maxMessageLength, uint8_t *sourceConnectionString, uint8_t *sourceConnectionStringLength, uint8_t *destinationConnectionString, uint8_t *destinationConnectionStringLength, const uint8_t maxConnectionStringLength, uint32_t *networkPortInstance));

Registers the callback the stack calls to pull one inbound raw BACnet message from the host’s transport layer.

Called exactly once per BACnetStack_Tick(), and from nowhere else.

MUST NOT BLOCK-WAIT. Tick() cannot proceed until this returns. Return 0 when no message is waiting; that is the normal idle case, not an error.

The callback returns the number of bytes it wrote into the message buffer. The stack DISCARDS the whole message, and logs, if that count exceeds maxMessageLength or if either connection-string length exceeds maxConnectionStringLength - it does not clamp.

All four buffers belong to the stack, are its own call-frame locals, and are valid only for the duration of the call. Write into them; never retain them. The two length out-parameters are OUT-only - their values on entry are undefined.

If this callback is never registered the stack reads nothing, reports no error, and the device is silently deaf.

BACnet/SC accepted connections: report frames from an accepted WebSocket with the per-socket <acceptUri>|client=<token> string as sourceConnectionString - see BACnetStack_RegisterCallbackSCStartListening().

MS/TP: BOTH connection strings are REQUIRED, one octet each. The source is the sending station’s MAC address (never 255). The destination is the frame’s destination MAC address: this station’s own address for a frame sent to it, or 255 for a broadcast frame. The stack DISCARDS a frame whose source or destination is missing or is not exactly one octet, or whose source is 255, and in a build without STACK_OPTION_API_DEBUG_LOGGING nothing reports it - the device simply never answers. Any destination other than 255 is taken as addressed to this station; it is not compared with the station’s own MAC address. Do not leave the destination empty to mean “to this station”: the destination is the only way the stack learns that a frame was a local broadcast, which it needs, among other things, to forward broadcasts when it routes and for the Notification Forwarder.

BACnet/IPv6 (Annex U; a build with STACK_OPTION_DATA_LINK_LAYER_IPV6): the source connection string is REQUIRED and is exactly 18 octets, the sender’s 16-octet IPv6 address followed by its 2-octet UDP port, each most significant octet first (a B/IPv6 address, Annex U.1.1.2). The destination connection string is optional, except that a host whose port runs as a BBMD must pass each datagram’s real destination address in it (18 octets, or the 16-octet IPv6 address): the multicast group it arrived on, or this node’s unicast address it was sent to - not the socket’s bound address. A BBMD passes a peer BBMD’s broadcast on only when it knows that broadcast reached it by unicast; without a destination (or with the unspecified address ::) it still forwards its own link’s broadcasts to its peers and foreign devices, but does not pass its peers’ broadcasts on to its link or its foreign devices. A host that passes its socket’s bound unicast address for every datagram makes every arrival look unicast, and the BBMD forwards nothing from its own link: pass the real destination, or nothing. Pass the datagram as received, BVLL header included (BVLC Type X’82’): the stack reads the header itself. A datagram that is not a BVLL-IPv6 message, or whose source is not 18 octets, is dropped. The stack learns each sender’s VMAC address (its device instance) from the header, so a reply to a peer that has spoken goes out to the 18-octet address it spoke from.

See also: CASBACnetStack::FPCallbackReceiveMessageForPort

Parameters

Parameter	Direction	Description
FPCallbackReceiveMessageForPort	in	The function pointer for the CallbackReceiveMessageForPort function. See CASBACnetStack::FPCallbackReceiveMessageForPort for more info.

Callback type

FPCallbackReceiveMessageForPort

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