op_radio_txch_rxgroup_get()
Note: Requires Wireless functionality
Abstract
Gets the receiver group of a transmitter channel.
Syntax
op_radio_txch_rxgroup_get (txch_objid, count_ptr, rxgroup_pptr)
| Argument | Type | Description |
|---|---|---|
txch_objid |
Objid |
transmitter channel whose receiver group is requested |
count_ptr |
unsigned int * |
pointer to a counter that this function will set to the number of receivers in the receiver group. This will indicate the size of the rxgroup_pptr array. |
rxgroup_pptr |
Objid ** |
pointer to an array of the receiver object IDs from the receiver group of the transmitter channel, or OPC_NIL if no receivers are present. The resulting array should be freed with op_prg_mem_free() after use. |
Return Type
Compcode
Completion code indicating success or failure in retrieving the receiver group. The procedure returns OPC_COMPCODE_SUCCESS if the receiver group was successfully retrieved; otherwise, it returns OPC_COMPCODE_FAILURE.
Example
unsigned int num_receivers;
Objid * receivers;
if (op_radio_txch_rxgroup_get (txch, &num_receivers, &receivers)
== OPC_COMPCODE_SUCCESS)
{
if (num_receivers == 0)
{
printf ("Transmitter channel %d has an empty receiver group\n", txch);
}
else
{
unsigned int i;
printf ("Transmitter channel%d has %d receivers in its group:",
txch, num_receivers);
for (i = 0; i < num_receivers; i++)
printf ("%d%s", receivers [i],(i+1 == num_receivers ? "" : ", "));
printf ("\n");
op_prg_mem_free (receivers);
}
}
Details
The number of receivers in the group for the specified transmitter channel is set in count_ptr. If the group contains receivers, this procedure will use op_prg_mem_alloc() to dynamically allocate an array of object IDs, fill it with the object IDs of the receivers in the group, and return it via rxgroup_pptr.
Note: This array must be deallocated (using op_prg_mem_free()) by the caller of this Kernel Procedure.
Purpose
Provides a mechanism to obtain the current receiver group of a transmitter channel.
Errors
- Recoverable Error: Object ID (
<objid>) does not correspond to a transmitter channel. - Recoverable Error: Transmitter object ID (
<objid>) refers to a restricted object. - Recoverable Error: Return address for size of receiver group is NIL.
- Recoverable Error: Return address for array of receiver channel IDs is NIL.
Reference
- Use the KP op_radio_txch_rxgroup_compute() to compute the receiver group using a filter
- Use the KP op_radio_txch_rxgroup_set() to set the receiver group to a provided array of object IDs
- Use the KP op_radio_txch_rxch_add() to add one receiver channel to a transmitter channel’s group
- Use the KP op_radio_txch_rxch_remove() to remove one receiver channel from a transmitter channel’s group