op_pk_fd_set_ptr()
摘要
为指定数据包中的某个结构字段赋值,并同时指定该结构的类型、大小以及结构复制与释放的处理过程;目标字段由数字索引指定。
语法
op_pk_fd_set_ptr (pkptr, field_index, value, field_size, copy_proc, dealloc_proc, alloc_size)
| 参数 | 类型 | 说明 |
|---|---|---|
pkptr |
Packet* |
目标数据包的指针 |
field_index |
int |
目标字段的数字索引 [该值必须为非负数,否则会发生错误。] |
value |
void* |
要赋给该字段的值 |
field_size |
OpT_Int64 |
字段内容的建模大小(以比特为单位),或 OPC_FIELD_SIZE_UNCHANGED(见详情) |
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 |
指定数据结构的实际大小(以字节为单位) |
返回类型
Compcode
字段设置成功时返回 OPC_COMPCODE_SUCCESS,否则返回 OPC_COMPCODE_FAILURE。
示例
{
/* 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);
}
详情
如果 field_size 与该字段原先的大小不同,数据包的总大小将相应改变。如果 field_size 指定为 OPC_FIELD_SIZE_UNCHANGED,则该字段的大小保持数据包中原有的定义不变。
被赋值给字段的结构会被“封装”在数据包之内,调用方进程通常不应继续使用指向该结构的指针(这偶尔可作为一种远程进程间通信的手段,但结构内存必须非常谨慎地处理)。
所指定的复制与释放过程分别在指定数据包被复制或销毁时被调用。复制过程用于为字段中包含的结构分配内存并复制该结构。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_name_to_index() 和 op_pk_nfd_name_to_index() 转换为数字索引)。
错误
- 与
op_pk_fd_set()(结构字段版本)相同。
参考
- 与
op_pk_fd_set()(结构字段版本)相同。