op_pk_nfd_set()

已弃用——请使用显式指定类型的 op_pk_nfd_set_<type>()

摘要

为指定数据包中的某个结构字段赋值,并同时指定结构的复制与释放处理过程;目标字段通过名称指定。

注意:该形式仅用于结构字段。对于其他字段类型,请使用其他形式(详情参见目的部分)。

语法

op_pk_nfd_set (pkptr, fd_name, value, copy_proc, dealloc_proc, alloc_size)
参数 类型 说明
pkptr Packet* 指向目标数据包的指针(详情参见前一个内核过程条目)。
fd_name const char* 目标字段的名称
[该名称必须是数据包格式中已定义的字段,否则会发生错误。]
value void* 要赋给指定字段的数据结构指针
copy_proc SimT_Pk_Fd_Struct_Copy_Proc 指定数据结构的复制过程,通常使用内核过程 op_prg_mem_copy_create()(见详情)
dealloc_proc SimT_Pk_Fd_Struct_Dealloc_Proc 指定数据结构的释放过程,通常使用内核过程 op_prg_mem_free()(见详情)
alloc_size size_t 传递给 copy_proc 的参数
[该参数可表示指定数据结构的实际大小(以字节为单位)。]

返回类型

Compcode

完成代码,指示是否为指定字段成功赋了新值。如果发生可恢复错误,将返回 OPC_COMPCODE_FAILURE。

示例

{
typedef struct {
	int    int_value;
	char   name[100];
	} custom_DS;

/* declarations */
Packet *f_pkptr; Custom_DS *ds_ptr;

/* create a formatted packet */
f_pkptr = op_pk_create_fmt ("struct_pkt");

/* allocate a new data structure */
ds_ptr = (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_nfd_set (f_pkptr, "ds_field", ds_ptr, op_prg_mem_copy_create,
	op_prg_mem_free, sizeof (Custom_DS));

/* send the defined packet out of the processor */
op_pk_send (f_pkptr, 0);
}

详情

value 参数可以接受指向任何类型数据结构的指针。如果指定字段此前未被设置过,新字段的大小也将由数据包格式确定,并累加到数据包的总大小中。

对于结构字段类型,必须指定字段的值。被赋值给字段的结构会被“封装”(encapsulated)在该内核过程所操作的数据包内部,调用方进程通常不应继续引用被赋值的结构指针(这偶尔可作为一种远程进程间通信的手段,但结构内存必须非常谨慎地处理)。

所指定的复制与释放过程分别在指定数据包被复制或销毁时被调用。复制过程用于为字段中包含的结构分配内存并复制该结构。copy_proc 的原型为:

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

当指定的复制过程为 op_prg_mem_copy_create() 时,alloc_size 指定了在分配结构副本的内存时、为预留正确内存量所需的字节数。copy_proc 不能为空;至少必须是一个仅返回 org_ptr 的桩函数。

释放过程用于释放字段中包含的结构所占用的内存。dealloc_proc 的原型为:

typedef void (*SimT_Pk_Fd_Struct_Dealloc_Proc)(void * ptr)

dealloc_proc 可以为空,此时内存不会被释放。

**注意:**由于数据包被复制时字段并不会被自动复制,复制与释放过程可能不会在预期的时机被调用。复制过程仅在结构字段发生变化时被调用,而不是在数据包被复制时被调用。释放过程仅在即将被销毁的结构字段为该数据包所独有(即未被该数据包的任何副本引用)时被调用。详见 op_pk_copy() 的说明。

目的

提供一种设置数据包内部某个结构字段值的机制。由于数据包是格式化的,只需指定字段的值和分配信息;字段的类型和大小(若使用未格式化版本的内核过程 op_pk_fd_set() 则需要指定)会自动从格式中获取。

**注意:**该内核过程只应应用于格式化数据包;否则会发生错误。

op_pk_nfd_set() 的该形式仅支持结构字段类型。该内核过程的其他形式支持整型、双精度或数据包字段类型(op_pk_nfd_set())以及信息字段类型(op_pk_nfd_set())。

该内核过程存在针对特定数据类型的版本。该替代内核过程比这种可变参数版本更高效;此外,它还能让编译器捕获该内核过程遗漏的参数错误。详情参见 op_pk_nfd_set_ptr()。

错误

  • 程序中止:段违例。(由无效的数据包指针或 fd_name 参数引起)
  • 程序中止:数据包指针为 NIL。
  • 程序中止:数据包指针指向已被销毁的数据包。
  • 程序中止:数据包指针指向无主数据包 (<pk_id>)。
  • 可恢复错误:数据包 (<pk_id>) 中没有名为 (<fd_name>) 的字段。

参考

  • 使用该内核过程的其他形式为数据包的整型、双精度、数据包或信息字段赋值
  • 使用内核过程 op_pk_fd_set() 的变体,通过数字索引指定要赋值的字段,为未格式化(或格式化)数据包中的字段赋值
  • 使用内核过程 op_pk_nfd_get() 的变体,获取数据包中字段的值
  • 使用内核过程 op_pk_nfd_strip() 取消数据包中某字段的设置,并从数据包总大小中减去其贡献

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