op_prg_odb_command_register()
摘要
允许用户向 ODB 添加自定义命令,这些命令会调用自定义回调函数。
语法
op_prg_odb_command_register (command_name, usage, category, short_desc, long_desc, callback, state_ptr, destroy_callback)
| 参数 | 类型 | 说明 |
|---|---|---|
command_name |
const char* |
要添加到 ODB 的命令名称。此处指定的命令名称可以在 ODB 提示符下输入,以激活用户指定的回调函数。 |
usage |
const char* |
描述命令用法的字符串。[如果用户在 ODB 中请求已注册命令的帮助,该字符串会出现。 |
category |
const char* |
命令所属的类别 |
short_desc |
cconst har* |
命令的简短描述 |
long_desc |
const char* |
命令的详细描述 |
callback |
Procedure |
新 ODB 命令要调用的函数。该过程使用的 typedef 是 Prg_Odb_Command_Callback。 |
state_ptr |
state_ptr |
传递给回调函数的指针。当用户调用已注册命令时,该指针会被传递给回调函数和销毁回调函数。 |
destroy_callback |
Procedure |
命令从 ODB 中移除时调用的函数。该过程使用的 typedef 是 Prg_Odb_State_Destroy。 |
返回类型
Compcode
完成代码,指示函数是否成功注册。可将该返回代码与常量 OPC_COMPCODE_SUCCESS 和 OPC_COMPCODE_FAILURE 比较,以判断命令是否注册成功。
示例
/* Register a command with ODB that will invoke the function */
/* tcp_connection_info_display(). Call the odb command "tcp_info" */
op_prg_odb_command_register ("tcp_info", "tcp_info [ip-address]",
"TCP Commands" /*category of commands */,
"This command will print out information on open TCP connections."
/*short description */,
"This command will print out information on open TCP connections\n"
"given an optional ip-address. Information includes source and\n"
"destination ip addresses, as well as statistics regarding the\n"
"currently open connection." /* long description */,
tcp_connection_info_display /* callback function */,
TcpI_Conn_Info_Ptr /* a pointer within this process model containing */
/* all necessary information needed for printing out connection information.*/,
tcp_connection_info_destroy /* destroy callback */ );
详情
本内核过程允许进程安装自己的命令,供仿真调试期间在 ODB 提示符下使用。用户调用该命令时,会激活模型开发者指定的回调函数。回调函数的原型为以下形式:
int
callback_function (const char *arguments, void *state_ptr)
传入的参数取自 ODB 命令行,由命令之后输入的任意字符组成。回调函数应返回一个整数。若返回的整数为 0,ODB 提示符会提示用户输入另一条命令;若整数不为 0,仿真继续执行。
销毁回调函数的定义如下:
void
destroy_callback (void *state_ptr)
销毁回调函数接收与回调函数所使用的相同的 state 指针。该函数释放命令专属的状态,以释放与已安装命令相关的资源。如果动态进程使用本内核过程安装了命令,而该进程随后被销毁,则会调用此函数来释放状态并将命令从 ODB 中移除。
usage、long_desc 和 short_desc 参数都通过 ODB 的各种帮助功能呈现信息。
本内核过程在优化仿真内核下使用时返回 OPC_COMPCODE_FAILURE。
用途
为状态提供了一种定义自己的 ODB 命令的机制。在 ODB 提示符下输入该命令时,会调用用户创建的函数。
错误
- 程序中止:内核过程需要进程上下文。
参考
- 使用内核过程 op_prg_odb_bkpt() 定义断点应在何时触发