op_pk_fd_set()

Abstract

Assigns the type, value, and size of an integer, double, or packet field in the specified packet; the field-of-interest is specified by a numeric index.

Note: This KP format is used for integer, double, and packet fields only. For other field types, use an alternate format (see the Purpose section for details).

Syntax

op_pk_fd_set (pkptr, fd_index, type, value, size)
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_index int numeric index of the field-of-interest
type int type to be assigned to the field
[This is an integer code which specifies the field type (see Table 55 “Field Type Symbolic Constants“ on page 14); acceptable values for this KP format are OPC_FIELD_TYPE_INTEGER, OPC_FIELD_TYPE_INT64, OPC_FIELD_TYPE_DOUBLE, OPC_FIELD_TYPE_PACKET_ID, OPC_FIELD_TYPE_OBJECT_ID, and OPC_FIELD_TYPE_PACKET.]
See Details section for information about usage.
value void* value to be assigned to the field
[This value can be an integer, a 64-bit integer, a double, a packet ID, an object ID, or a packet pointer.]
size int, double, or OpT_Int64 modeled size (in bits) of the field contents, or OPC_FIELD_SIZE_UNCHANGED
[If this argument is of type double or OpT_Int64, you must augment the type argument. See the Details section for more information.]

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the field could be set; OPC_COMPCODE_FAILURE otherwise.

Example

/* create an unformatted packet */
uf_pkptr = op_pk_create (64);

/* assign integer fields in the packet */
op_pk_fd_set (uf_pkptr, 0, OPC_FIELD_TYPE_INTEGER, 2511, 16);
int64_value = 5 * 200000000000;
op_pk_fd_set (uf_pkptr, 1, OPC_FIELD_TYPE_INT64, int64_value, 16);

...
/* encapsulate a higher-level packet in the packet */
enc_pkptr = op_pk_create (24);
op_pk_fd_set (uf_pkptr, 4, OPC_FIELD_TYPE_PACKET, enc_pkptr, -1);

Details

The value argument of this KP can accept either an integer, a double, or a packet pointer value. The logic within this KP determines the type of the passed argument using the integer code passed to the type argument, and alters its field assignment technique accordingly. The value of the fd_index argument must be non-negative, or an error will occur. If the specified size of the field is different from its previous size, the total size of the packet will change accordingly.

For the integer, double, and packet field types, both the value and size of the field must be specified. Packets that are assigned to fields are encapsulated within the higher-level packet, and the invoking process loses ownership of the encapsulated packet. These encapsulated packets are not accessible until they are decapsulated by op_pk_fd_get() (or op_pk_nfd_get(), if the packet is formatted). If the specified size of a packet field is set to a negative value, the size of the field will be set to the size of the encapsulated packet, thus accurately modeling the aggregate packet size. If the specified size of a packet field is zero or positive, it overrides the size of the assigned packet, thus supporting the modeling of stripping or compression.

If size is of type double, you must augment the type argument by adding an OR operator (|) and the flag OPC_FIELD_SIZE_IS_DOUBLE; otherwise the underlying code will interpret the size argument as an integer value. If the size argument is of type OpT_Int64, you must augment the type argument by adding an OR operator (|) and the OPC_FIELD_SIZE_IS_INT64 flag. For example,

op_pk_fd_set (pkptr, 0, OPC_FIELD_TYPE_INTEGER, 24, 16) uses a size argument of type integer (the value 16 as an integer (four-byte) argument)
op_pk_fd_set (pkptr, 0,
OPC_FIELD_TYPE_INTEGER|OPC_FIELD_SIZE_IS_DOUBLE, 24, 16.0)
uses a size argument of type double (the value 16.0 as a double (eight-byte) argument)
OpT_Int64 the_size = 16;
op_pk_fd_set (pkptr, 0,
OPC_FIELD_TYPE_INTEGER|OPC_FIELD_SIZE_IS_INT64, 24,
the_size)
uses a size argument of type 64-bit integer (the value 16 as a 64-bit integer (eight-byte) argument)

If size is different from the previous size of the field, the total size of the packet will change accordingly. If size is OPC_FIELD_SIZE_UNCHANGED, the size of the field will remain as defined in the packet.

Note: OPC_FIELD_SIZE_UNCHANGED is a 64-bit value. When it is used, the type argument must be augmented for an OpT_Int64 argument, as follows:

op_pk_fd_set (pkptr, field_index,
	OPC_FIELD_TYPE_INTEGER|OPC_FIELD_SIZE_IS_INT64, value,
	OPC_FIELD_SIZE_UNCHANGED)

Purpose

Provides a mechanism to set the value of a field within a packet. This KP is usually applied to unformatted packets, but it can be applied to formatted packets as well (formatted packet field names can be converted into numeric indices using the KPs op_pk_name_to_index() and op_pk_nfd_name_to_index()).

This format of op_pk_fd_set() supports integer, double, and packet field types. Alternate formats of this KP support information field types (op_pk_fd_set()) and structure field types (op_pk_fd_set()).

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_fd_set_int32(), op_pk_fd_set_int64(), op_pk_fd_set_dbl(), op_pk_fd_set_objid(), op_pk_fd_set_pkid(), and op_pk_fd_set_pkt().

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>).
  • Program Abort: Allocation of memory failed.
  • Recoverable Error: Field type (<type>) is unrecognized.
  • Recoverable Error: Field size (<size>) is out-of-range.
  • Recoverable Error: Field index (<fd_index>) is out-of-range for packet (<pk_id>).

Reference

  • Use the alternate forms of this KP to assign values to information or structure fields of a packet
  • Use one of the variants of the KP op_pk_nfd_set() to assign the value of a field in a formatted packet, utilizing a name to specify the field to be assigned
  • Use one of the variants of the KP op_pk_fd_get() to obtain the value of a field in a packet
  • Use the KP op_pk_fd_strip() to unset a field within a packet, subtracting out its contribution to total packet size

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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