op_pk_fd_print_proc_set()
摘要
为指定非格式化数据包的指定字段关联一个自定义打印过程;目标字段由数字索引指定。
语法
op_pk_fd_print_proc_set (pkptr, field_index, print_proc)
| 参数 | 类型 | 说明 |
|---|---|---|
pkptr |
Packet* |
指向目标数据包的指针。 [指向数据包的指针可以从许多内核过程中获得,包括 op_pk_create()、op_pk_create_fmt()、op_pk_copy()、op_pk_get()、op_subq_pk_access() 和 op_subq_pk_remove()。] |
field_index |
int |
目标字段的数字索引。可以标识除 information 之外的任意字段类型。 [该值应当为非负数;但即使为负数也不会发生错误,而是返回 OPC_COMPCODE_FAILURE,表明指定的字段未被设置。] |
print_proc |
Procedure |
打印过程;更多信息见详情一节 |
返回类型
Compcode
如果打印过程安装成功,返回 OPC_COMPCODE_SUCCESS;如果发生错误,返回 OPC_COMPCODE_FAILURE。
示例
/* Install a print procedure for the 5th field of a particular */
/* unformatted packet. The 5th field is the "address" field. */
/* address_print_proc is defined in the function block as follows: */
/* */
/* void address_print_proc (void *structure_ptr, PrgT_List *dest_lptr) */
/* { */
/* char *char_line; */
/* ReqT_Address *addr_ptr; */
/* addr_ptr = (ReqT_Address *) structure_ptr; */
/* char_line = op_prg_mem_alloc (sizeof (char) * 60); */
/* sprintf (char_line, "subnet: %d", addr_ptr->subnet); */
/* op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); */
/* char_line = op_prg_mem_alloc (sizeof (char) * 60); */
/* sprintf (char_line, "node : %s", addr_ptr->node_name); */
/* op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); */
/* } */
op_pk_fd_print_proc_set (pkptr, 5, address_print_proc);
详情
当数据包被打印时(使用 ODB 中的 pkprint 命令或内核过程 op_pk_print()),仿真内核将调用指定的 print_proc,为指定的数据包字段获取自定义文本。
print_proc 必须具有以下原型:
void
Pk_Fd_Print_Proc (void *field_value_ptr, PrgT_List *dest_lptr);
print_proc 必须向 PrgT_List *dest_lptr 中添加新条目。使用 prg_mem_alloc() 为要加入列表的字符串分配内存。仿真内核负责释放所有内存。
字段的内容通过 *field_value_ptr 传入。该参数随数据类型而异:
| 字段数据类型 | *field_value_ptr 参数 |
|---|---|
int32, int64, double, pktid, objid |
值的地址(转换为相应类型) |
packet |
数据包的地址 |
structure |
结构的地址 |
用途
使用该内核过程可以指定一个函数,当指定数据包的指定字段被 ODB 的 pkprint 命令或内核过程 op_pk_print() 打印时,该函数将被调用。该字段可以是除 information 之外的任意类型。除索引、名称、大小、类型和值之外,打印过程还允许打印关于字段的额外自定义信息。
如果字段值以某种方式编码,打印过程函数会很有用。例如,如果一个 int32 字段包含以位图表示的信息,打印过程可以打印便于调试的解码版本。打印过程还可用于为存储在 structure 类型数据包字段内的数据结构创建文本表示。这类数据结构可能很复杂,因此文本表示对调试很有用。
错误
- 可恢复错误:数据包 (
<id>) 的内容是值向量。该数据包不允许字段操作。 - 可恢复错误:字段索引
<index>对数据包<id>而言超出范围。 - 可恢复错误:数据包 (
<id>) 中不存在索引为 (<index>) 的字段。 - 程序中止:段错误。(由于无效的数据包指针或格式错误的数据包)
- 程序中止:数据包指针为 NIL。
- 程序中止:数据包指针指向已被销毁的数据包。
- 程序中止:数据包指针指向无主的数据包 (
<pk_id>)。
参考
- 使用内核过程 op_pk_create() 创建一个新的非格式化数据包,其 bulk 数据大小为指定值;该数据包的任何字段均未被设置。
- 使用内核过程 op_pk_print() 将关于指定数据包的信息(包括数据包字段的内容和字段属性的值)打印到标准输出设备。