op_pk_bcast_general()
Abstract
Assigns the broadcast property of the specified packet to permit its broadcast to eligible receivers in all network nodes.
Syntax
op_pk_bcast_general (pkptr)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest [A pointer to a packet can be obtained from many KPs, including op_pk_create(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
Return Type
void
No return value.
Example
/** this is the basis of a simple repeater node, which **/
/** receives uniquely broadcasted packets from terminal nodes **/
/** and repeats them at high power to all terminal nodes. **/
/* receive a uniquely broadcasted packet from terminal node */
pkptr = op_pk_get (IN_STRM);
/* restore general broadcast property of packet */
op_pk_bcast_general (pkptr);
/* send packet to transmitter, thus generally broadcasting it */
op_pk_send (pkptr, 0);
Details
Under default conditions, transmitting a packet using a bus transmitter or radio transmitter will result in a broadcast of the packet to all receivers which are eligible to receive the broadcast. In the case of a bus broadcast, any receiver attached to the same bus link will be eligible to receive. In the case of a radio broadcast, there are a number of transmitter and receiver attributes which must match for a receiver to be eligible to receive. In both cases, multiple receivers will typically be eligible and will receive broadcasted packets.
Each packet has an internal broadcast property; the default conditions discussed above are due to the broadcast property of a packet being set to be general (i.e., all eligible receivers pick up a broadcast). The opposite situation is for the broadcast property of a packet to be set to unique (i.e., only eligible receivers at a single specified node will pick up a broadcast). This KP sets the broadcast property of a packet to be general. The broadcast property of a packet may be set at any time; it will only affect the operation of the Simulation Kernel when the packet enters a bus or radio transmitter.
This KP requires a process context, so it must only be invoked from a process model, or a function that has been directly or indirectly invoked by a process model. Both unformatted and formatted packets can be operated on via this KP.
Purpose
Provides a mechanism to restore the broadcast property of a packet to be general. This is only necessary when a packet has been previously operated on by the related KP op_pk_bcast_unique(), and must now be reset to allow general broadcast.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: KP requires process context.
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Program Abort: Packet pointer references static packet (
<pk_id>).
Reference
- Use the KP op_pk_bcast_unique() to set a packet’s broadcast property to target a single node
- Use the KP op_pk_send() to forward a packet to a bus or radio transmitter for the actual broadcasting operation to take place