op_pk_nfd_get()

DEPRECATED—Use explicitly typed op_pk_nfd_get_<type>()

Abstract

Obtains the value of a field in the specified packet, changing the status of some field types to unset; the field-of-interest is specified by name.

Syntax

op_pk_nfd_get (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_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, or an error will occur.]
value_ptr void* pointer to a variable to be filled in with the specified field's value
[This argument can accept a pointer to an integer, a double, a packet pointer, or any other data structure pointer. The data type of the argument pointer must match the data type of the specified field, or an error will occur.]

Return Type

Compcode

Completion code indicating if the specified field's value was successfully obtained.

The constant OPC_COMPCODE_FAILURE will be returned if an error occurs.

Example

	{
	/* variable declarations */
	int i; double d; Packet *pkptr, *enc_pkptr; struct Custom_DS *ds_ptr;

	/* obtain an arriving packet */
	pkptr = op_pk_get (0);

	/* obtain the simple field types */
	op_pk_nfd_get (pkptr, "int_value", &i);
	op_pk_nfd_get (pkptr, "double_value", &d);
	printf ("packet contents: integer (%d), double (%g)\n", i, d);

	/* decapsulate a higher-level packet from the arriving packet */
	op_pk_nfd_get (pkptr, "packet_value", &enc_pkptr);
	op_pk_print (enc_pkptr);

	/* extract a data structure from a packet field */
	op_pk_nfd_get (pkptr, "structure_value", &ds_ptr);

	op_pk_destroy (pkptr);
	}

Details

This KP supports value access for all five types of packet fields: integer, double, packet, information, and structure. However, the behavior differs depending on the type, as follows.

Integer and double fields

Simple packet fields (integers and doubles) have their values copied into the passed variable, but are otherwise unaffected by this KP (i.e., these types of fields remain set and accessible, and continue to contribute the same amount of bits to the packet's total size).

Packet and structure fields

Packet and structure fields of a packet also have their values (i.e., pointers to packets or data structures) copied into the passed variable.

Note: As a side-effect of accessing packet and structure values, the fields are effectively stripped from the packet: their status changes to unset, their contents become inaccessible to subsequent op_pk_nfd_get() calls, and their contribution to the packet's total size is subtracted. These side effects are intended to enforce strict ownership rules for the encapsulated field contents. Accessing the contents of these fields conceptually decapsulates the packet or data structure from within the packet.

Information fields

Accessing the value of an information field does not have a valid purpose since the field does not have a defined value; but instead of causing an error, the string “unspecified” is copied into the passed value pointer (the passed address must point to an array of characters of adequate length to contain this string).

Purpose

Provides a mechanism to obtain the value of a packet's field. This operation is fundamental to the goal of using packets as containers of data for inter-process communications. Usually, this KP will be called when a packet has arrived on an input stream of a processor or queue and the packet:

  • must be processed
  • must be stored
  • requires a response message

Data-type-specific versions of this KP exist. These alternate KPs are more efficient than this variable argument version. In addition, they allow the compiler to catch argument errors that are missed with this KP. For details, refer to op_pk_nfd_get_dbl(), op_pk_nfd_get_int32(), op_pk_nfd_get_int64(), op_pk_nfd_get_objid(), op_pk_nfd_get_pkid(), op_pk_nfd_get_pkt(), and op_pk_nfd_get_ptr().

Errors

  • Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
  • Program Abort: Packet pointer is NIL.
  • Program Abort: Packet pointer references destroyed packet.
  • Program Abort: Packet pointer references unowned packet (<pk_id>).

Reference

  • Use one of the variants of the KP op_pk_nfd_set() to assign a value to a packet field
  • Use the KP op_pk_nfd_get_dbl() to obtain the value of a double field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_int32() to obtain the value of a 32-bit integer field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_int64() to obtain the value of a 64-bit integer field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_objid() to obtain the value of an object ID field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_pkid() to obtain the value of a packet ID field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_pkt() to obtain the value of a packet field from a packet, using a numeric index to specify the field
  • Use the KP op_pk_nfd_get_ptr() to obtain the value of a structure field from a packet, using a numeric index to specify the field
  • Use one of the variants of the KP op_pk_fd_get() to obtain the value of a field from an unformatted (or formatted) packet, using a numeric index 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