op_pk_fd_set()
摘要
为指定数据包中的 structure 字段指定值,同时指定结构复制与释放的过程以及类型和大小;目标字段由数字索引指定。
注意: 该 KP 格式仅用于 structure 字段。其他字段类型请使用替代格式(详见用途一节)。
语法
op_pk_fd_set (pkptr, fd_index, type, value, size, copy_proc, dealloc_proc, alloc_size)
| 参数 | 类型 | 说明 |
|---|---|---|
pkptr |
Packet* |
指向目标数据包的指针 [指向数据包的指针可以从许多内核过程中获得,包括 op_pk_create()、op_pk_create_fmt()、op_pk_copy()、op_pk_get()、op_subq_pk_access() 和 op_subq_pk_remove()。] |
fd_index |
int |
目标字段的数字索引 |
type |
int |
要分配给字段的类型 [这是一个指定字段类型的整数代码(参见表 55 “Field Type Symbolic Constants“ 第 14 页);该 KP 格式唯一可接受的值为 OPC_FIELD_TYPE_STRUCT。] |
value |
void* |
要分配给字段的数据结构指针 |
size |
int、double 或 OpT_Int64 |
字段内容的大小(以比特计),或 OPC_FIELD_SIZE_UNCHANGED [如果该参数的类型为 double 或 OpT_Int64,必须对 type 参数进行增强。更多信息见详情一节。] |
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 (uf_pkptr, 0, OPC_FIELD_TYPE_STRUCT, 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);
}
详情
value 参数可以接受任何类型数据结构的指针。fd_index 参数的值必须为非负数,否则会发生错误。如果指定的字段大小与其先前的大小不同,数据包的总大小将按比例变化。
对于 structure 字段类型,必须同时指定字段的值和大小。被赋值给字段的结构会被“封装”在数据包内,而调用进程通常不应继续使用结构指针(这偶尔可作为一种远程进程间通信的手段,但结构内存必须非常谨慎地处理)。
如果 size 的类型为 double,必须通过添加 OR 运算符 (|) 和标志 OPC_FIELD_SIZE_IS_DOUBLE 来增强 type 参数;否则底层代码会将 size 参数解释为整数值。如果 size 参数的类型为 OpT_Int64,必须通过添加 OR 运算符 (|) 和 OPC_FIELD_SIZE_IS_INT64 标志来增强 type 参数。例如,
op_pk_fd_set (pkptr, 0, OPC_FIELD_TYPE_STRUCT, val_ptr, 16, copy,free, alloc_size) |
使用类型为 integer 的 size 参数(将值 16 作为整数(四字节)参数) |
op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_DOUBLE, val_ptr,16.0, copy, free, alloc_size) |
使用类型为 double 的 size 参数(将值 16.0 作为 double(八字节)参数) |
OpT_Int64 the_size = 16;op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_INT64, val_ptr,the_size, copy, free, alloc_size) |
使用类型为 64 位整数的 size 参数(将值 16 作为 64 位整数(八字节)参数) |
如果 size 与字段的先前大小不同,数据包的总大小将相应变化。如果 size 为 OPC_FIELD_SIZE_UNCHANGED,字段的大小将保持数据包中原有的定义。
注意: OPC_FIELD_SIZE_UNCHANGED 是一个 64 位值。使用它时,必须为 OpT_Int64 参数增强 type 参数,如下所示:
op_pk_fd_set (pkptr, field_index,
OPC_FIELD_TYPE_STRUCT|OPC_FIELD_SIZE_IS_INT64, val_ptr,
OPC_FIELD_SIZE_UNCHANGED, copy_proc, dealloc_proc,
alloc_size)
所指定的复制和释放过程分别在指定数据包被复制或销毁时被调用。复制过程用于为字段中包含的结构分配内存并复制该结构。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 不能为 null;至少必须是一个仅返回 org_ptr 的桩函数。
释放过程用于释放字段中包含的结构所占用的内存。dealloc_proc 的原型为:
typedef void (*SimT_Pk_Fd_Struct_Dealloc_Proc)(void * ptr)
dealloc_proc 可以为 null,此时内存不会被释放。
注意: 由于数据包被复制时字段不会被自动复制,复制和释放过程可能不会在预期时被调用。复制过程仅在 structure 字段发生变化时被调用,而不是在数据包被复制时被调用。释放过程仅当被销毁的 structure 字段为该数据包所独有(即未被该数据包的副本引用)时才被调用。更多细节参见 op_pk_copy() 的说明。
用途
提供一种设置数据包中字段值的机制。该内核过程通常用于非格式化数据包,但也可以用于有格式数据包(有格式数据包的字段名称可以使用内核过程 op_pk_name_to_index() 和 op_pk_nfd_name_to_index() 转换为数字索引)。
op_pk_fd_set() 的该格式仅支持 structure 字段类型。该内核过程的替代格式支持 integer、double 或 packet 字段类型(op_pk_fd_set())和 information 字段类型(op_pk_fd_set())
该内核过程存在按数据类型区分的版本。该替代内核过程比该可变参数版本更高效。此外,它使编译器能够捕获该内核过程遗漏的参数错误。详情参见 op_pk_fd_set_ptr()。
错误
- 程序中止:段错误。(由于无效的数据包指针或格式错误的数据包)
- 程序中止:数据包指针为 NIL。
- 程序中止:数据包指针指向已被销毁的数据包。
- 程序中止:数据包指针指向无主的数据包 (
<pk_id>)。 - 程序中止:内存分配失败。
- 可恢复错误:字段类型 (
<type>) 无法识别。 - 可恢复错误:字段大小 (
<size>) 超出范围。 - 可恢复错误:字段索引 (
<fd_index>) 对数据包 (<pk_id>) 而言超出范围。
参考
- 使用该内核过程的替代格式为数据包的 integer、double、packet 或 information 字段赋值
- 使用内核过程 op_pk_nfd_set() 的变体之一,通过名称指定要赋值的字段,为有格式数据包中的字段赋值
- 使用内核过程 op_pk_fd_get() 的变体之一,获取数据包中字段的值
- 使用内核过程 op_pk_fd_strip() 取消设置数据包字段,并从数据包总大小中减去其贡献