op_pk_format_print_proc_set()
摘要
为指定格式的任意有格式数据包的指定字段关联一个自定义打印过程。
语法
op_pk_format_print_proc_set (format_name, fd_name, print_proc)
| 参数 | 类型 | 说明 |
|---|---|---|
format_name |
const char* |
目标数据包格式的名称。 |
fd_name |
const char* |
目标字段的名称。 [该名称应当是数据包格式中已定义的字段,字段类型可以是除 information 之外的任意类型。] |
print_proc |
Procedure |
打印过程;其原型见「详情」一节。 |
返回类型
Compcode
如果打印过程安装成功,返回 OPC_COMPCODE_SUCCESS;如果发生错误,返回 OPC_COMPCODE_FAILURE。
示例
/* Install a print procedure for the "address" field of all packet */
/* with the "data_req" packet format. */
/* 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_format_print_proc_set ("data_req", "address", 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 类型数据包字段内的数据结构创建文本表示。这类数据结构可能很复杂,因此文本表示对调试很有用。
错误
- 可恢复错误:格式
<format_name>中没有名为<field name>的字段。 - 可恢复错误:数据包格式
<format_name>无法识别
参考
- 使用内核过程 op_pk_create_fmt() 创建一个新的有格式数据包,其结构由指定的数据包格式描述。
- 使用内核过程 op_pk_print() 将关于指定数据包的信息(包括数据包字段的内容和字段属性的值)打印到标准输出设备