BACnetStack_SendIAmRouterToNetwork

bool BACnetStack_SendIAmRouterToNetwork(
  const uint16_t * networkNumbers,
  const uint32_t networkNumberCount,
  const uint8_t * connectionString,
  const uint8_t connectionStringLength,
  const uint32_t networkPortInstance,
  const bool broadcast,
  const uint16_t destinationNetwork,
  const uint8_t * destinationAddress,
  const uint8_t destinationAddressLength);

Sends an I-Am-Router-To-Network NPDU announcing the networks this device routes to (cl. 6.4.2).

Works for BOTH virtual routers and plain BACnet (physical) routers.

networkNumberCount == 0 (networkNumbers may be NULL) announces this device’s FULL routing table: every configured virtual network of a virtual router, and, on an enabled physical router, every network it can reach through an ENABLED router port - directly connected to that port or learned behind it; a route whose port is disabled is not listed - except the networks reachable through the port the message is sent on (the rule cl. 6.6.2 gives for the start-up announcement). A network that is both is listed once. If the data link for networkPortInstance serves more than one router port, the sending port cannot be told apart, so no physical-router network is listed (the debug log says so; pass the list explicitly instead). If the resulting list is empty, nothing is sent and this function returns false, because the message must carry at least one network number (cl. 6.4.2).

networkNumberCount > 0 announces exactly the caller-supplied networkNumbers list instead, per cl. 6.4.2’s “list of network numbers” - a partial or arbitrary announcement, for either kind of router. A non-zero count with a NULL networkNumbers is rejected (a caller bug, not a request for the default).

broadcast = false IS ALLOWED: the message is then sent unicast to connectionString, and only that one node sees it. Cl. 6.4.2 requires I-Am-Router-To-Network to be sent with a broadcast MAC address, so a conformant sender passes broadcast = true; the stack does not force it and does not refuse false, so the choice (and its conformance) is the caller’s.

Note

Requires one of the build options STACK_OPTION_GW_VN_B, STACK_OPTION_NM_RC_B, STACK_OPTION_ROUTER_PHYSICAL (any of them turns on STACK_OPTION_ROUTER, the macro this function checks).

BACnet reference: ANSI/ASHRAE 135-2024 clause 6.4.2 (I-Am-Router-To-Network).

Parameters

Parameter	Direction	Description
networkNumbers, networkNumberCount	in	The network numbers to announce, or NULL/0 for this device’s full routing table (see above).
connectionString, connectionStringLength	in	The datalink address to send TO (the destination) - not the local address to send from. For IPv4 this is 6 bytes: 4 octets of IPv4 address followed by 2 octets of port, big-endian (e.g. 0xC0,0xA8,0x01,0x05,0xBA,0xC0 = 192.168.1.5:47808; see BACnetStack_SendRegisterForeignDevice() for a worked example); on BACnet/IPv4 the stack refuses to send to a connection string of any other length, except that a broadcast from a device registered as a foreign device goes to its BBMD and does not use the connection string. MS/TP and BACnet/SC use a different connection-string shape; see their respective Set/Send exports.
networkPortInstance	in	The Network Port object instance to send the message on, or BACNET_NETWORK_PORT_DEFAULT (4194303) for the default/single port.
broadcast, destinationNetwork, destinationAddress, destinationAddressLength	in	broadcast selects a broadcast or a unicast where the data link has the choice: on BACnet/IP an Original-Broadcast-NPDU or an Original-Unicast-NPDU (a broadcast from a device registered as a foreign device goes to its BBMD as a Distribute-Broadcast-To-Network); on BACnet/SC the broadcast VMAC; on MS/TP it is ignored and connectionString decides. destinationNetwork 0 keeps the message on the local network; 1 to 65534 routes it to that network, to the device whose MAC address is destinationAddress/destinationAddressLength or, with NULL and 0 there, to every device on that network; 65535 is a global broadcast to every network. Pass broadcast = true for a conformant announcement (see above).

Returns

True if the message was sent, otherwise false - including when networkNumberCount is 0 and there is no network to announce on this port (see above).

Topic: Routing and virtual networks. Declared in CASBACnetStackDLL.h.