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() 取消数据包中某字段的设置,并从数据包总大小中减去其贡献