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 pkptr or value_ptr arguments)
  • 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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com