op_pk_fd_get()

Abstract

Obtains the value of a field in the specified packet; the field-of-interest is specified by a numeric index.

Syntax

op_pk_fd_get (pkptr, field_index, 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().]
field_index int numeric index of the field-of-interest
[This value must be non-negative.]
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.]

Return Type

Compcode

OPC_COMPCODE_FAILURE if the field is not obtained; OPC_COMPCODE_SUCCESS otherwise.

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_fd_get (pkptr, 0, &i);
	op_pk_fd_get (pkptr, 1, &d);
	printf ("packet contents: integer (%d), double (%g)\n", i, d);

	/* decapsulate a higher-level packet from the arriving packet */
	op_pk_fd_get (pkptr, 2, &enc_pkptr);
	op_pk_print (enc_pkptr);

	/* extract a data structure from a packet field */
	op_pk_fd_get (pkptr, 3, &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 (integer and double) 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 successive op_pk_fd_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, stored, or it requires a response message.

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 index (<field_index>) is out-of-range for packet (<pk_id>).

Reference

  • Use one of the variants of the KP op_pk_fd_set() to assign a value to a packet field
  • Use the KP op_pk_fd_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_fd_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_fd_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_fd_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_fd_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_fd_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_fd_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 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 the KP op_pk_fd_type() to determine the type of a packet field
  • Use the KP op_pk_fd_size() to determine the size of a packet field
  • Use the KP op_pk_fd_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