op_pk_fd_set_ptr()

Abstract

Assigns the value of a structure field in the specified packet, as well as the type, size, and procedures for structure copying and deallocation; the field-of-interest is specified by a numeric index.

Syntax

op_pk_fd_set_ptr (pkptr, field_index, value, field_size, copy_proc, dealloc_proc, alloc_size)
Argument Type Description
pkptr Packet* pointer to the packet-of-interest
field_index int numeric index of the field-of-interest
[This value must be non-negative, or an error will occur.]
value void* value to be assigned to the field
field_size OpT_Int64 modeled size (in bits) of the field contents, or OPC_FIELD_SIZE_UNCHANGED (see Details)
copy_proc SimT_Pk_Fd_Struct_Copy_Proc copy procedure for the specified data structure, typically the KP op_prg_mem_copy_create() (see Details)
dealloc_proc SimT_Pk_Fd_Struct_Dealloc_Proc deallocation procedure for the specified data structure, typically the KP op_prg_mem_free() (see Details)
alloc_size size_t actual size (in bytes) of the specified data structure

Return Type

Compcode

OPC_COMPCODE_SUCCESS if the field could be set; OPC_COMPCODE_FAILURE otherwise.

Example

	{
	/* declarations */
	Packet *uf_pkptr; struct Custom_DS *ds_ptr;

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

	/* allocate a new data structure */
	ds_ptr = (struct Custom_DS *) op_prg_mem_alloc (sizeof (Custom_DS));

	/* fill in certain data structure values */
	ds_ptr->int_value = 455;
	sprintf (ds_ptr->name, "Custom Data Structure #1");

	/* assign the data structure to a field in the packet */
	op_pk_fd_set_ptr (uf_pkptr, 0, ds_ptr, 256,
		op_prg_mem_copy_create, op_prg_mem_free, sizeof (Custom_DS));

	/* send the defined packet out of the processor */
	op_pk_send (uf_pkptr, OUTSTRM);
	}

Details

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

Structures assigned to fields are “encapsulated” within the packet, and the invoking process typically should not continue to use the structure pointer (this is occasionally useful as a means of remote inter-process communication, but structure memory must be handled very carefully).

The specified copy and deallocation procedures are invoked when the specified packet is copied or destroyed, respectively. The copy procedure is used to allocate memory for and copy the structure contained in the field. The prototype for copy_proc is:

typedef void * (*SimT_Pk_Fd_Struct_Copy_Proc)(void * org_ptr, size_t size)

When op_prg_mem_copy_create() is the specified copy procedure, alloc_size specifies the size in bytes necessary to reserve the correct amount of memory during allocation of structure copies. copy_proc must not be null; at the very least, it must be a stub function that simply returns org_ptr.

The deallocation procedure is used to deallocate the memory occupied by the structure contained in the field. The prototype for dealloc_proc is:

typedef void (*SimT_Pk_Fd_Struct_Dealloc_Proc)(void * ptr)

dealloc_proc can be null, in which case the memory is not freed.

Note: Because fields are not copied automatically when a packet is copied, the copy and deallocation procedures might not be invoked when expected. The copy procedure is invoked only when a structure field changes, not when a packet is copied. The deallocation procedure is invoked only when the structure field being destroyed is unique to the packet (that is, not referenced by a copy of the packet). See the description of op_pk_copy() for more details.

Purpose

Provides a way 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()).

Errors

Reference

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