op_pk_nfd_access_read_only_ptr()
Abstract
Accesses a structure stored in the specified packet for reading only; the field-of-interest is specified by name.
Syntax
op_pk_nfd_access_read_only_ptr (pkptr, fd_name, value_ptr)
| 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().] |
fd_name |
const char* |
name of the field-of-interest [This name must be a defined field within the packet’s format.] |
value_ptr |
const void** |
pointer to a variable to be filled in with the structure being accessed. The variable itself must be a pointer to some data structure. |
Return Type
Compcode
OPC_COMPCODE_FAILURE if the field is not obtained; OPC_COMPCODE_SUCCESS otherwise.
Example
/* Access the datagram field information structure */
/* to check destination address. */
op_pk_nfd_access_read_only_ptr (pk_copy_ptr, “fields”, (void**)&pkt_fields_ptr);
if (pkt_fields_ptr->dest_== my_addr)
. . . ;
Details
If successful, *value_ptr is set to the address of the structure stored in the packet. The structure is not removed from the packet (as is the case with op_pk_nfd_get_ptr()) and sharing, if any, is not disabled.
Note: This KP should be used only to access structure packet fields. Accessing other kinds of fields will result in an error. Use one of the typed op_pk_nfd_get… KPs for numerical fields.
Purpose
Provides a mechanism for efficient read-only access to a structure stored inside a packet. It can be used only when the client will not modify the structure content in any way.
Models with packet broadcasts, such as radio and bus models, normally clone each broadcast packet so that every receiver gets its own copy of the original packet. For simulation efficiency, however, the simulation kernel shares actual packet content and delays cloning until a KP is invoked that can potentially modify packet content. This KP allows access to a structure without triggering cloning of the packet.
This KP is particularly useful when a client on the receiver end wants to examine the content of a structure to see if certain criteria (such as destination address) are met, and either drop the packet (if it’s not destined for the node that received it) or pass it up the protocol stack. Use of op_pk_nfd_access_read_only_ptr() in this case ensures that packet contents do not have to be duplicated as a result of accessing the field’s structure, just to be discarded right away if structure content does satisfy the criteria.
Errors
- Program Abort: Segmentation violation. (due to invalid
pkptrorvalue_ptrarguments) - Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Recoverable Error: Field (
<field_name>) of packet (<pk_id>) is of type (<field_type>); can’t set its value as void *. - Recoverable Error: Return address for structure field is NIL.
Reference
- Use the KP
op_pk_nfd_get_ptr()to obtain the value of a structure field from a packet, using a name to specify the field - Use the KP
op_pk_nfd_access()to obtain the value of an integer, double, structure, or information field, leaving the field unchanged - Use one of the variants the KP
op_pk_nfd_get()to obtain the value of a field from a formatted packet, using a name to specify the field to be accessed - Use one of the variants of the KP
op_pk_nfd_set()to assign a value to a packet field, using a name to specify the field to be accessed - Use the KP
op_pk_nfd_type()to determine the type of a packet field - Use the KP
op_pk_nfd_size()to determine the size of a packet field - Use the KP
op_pk_nfd_is_set()to determine if a packet field is set