可变参数打印函数说明

可变参数打印函数说明 【文件号:】 系统平台数据管理分册 可变参数打印 函数#说明# VER 1.00.081104 项目代码:SimIED 1、 设计目的: 为满足平台各个模块对于含有多个参数的格式化字符串打印输出的需求，提供统一的函 数接口，以满足以下两方面的需要: (1)、调用该函数后，可对格式化字符串进行注册并保存，函数如下: ST_INT SYS_outputFormat(const ST_CHAR *fmt); (2)、调用该函数后，可按照格式化字符串对应的ID及参数打印输出，函数如下: ST_VOID SYS_outputCov(ST_INT nID, …); 2、 设计原理: 设计时主要参考了printf和sprintf等函数的实现代码，考虑到需要将格式化字符串保存 并返回一个对应格式化字符串的ID，因此在SYS_outputFormat函数内部调用了一个函数来执行保存格式化字符串并返回ID的功能。 对于SYS_outputFormat函数，当传递格式化字符串时，调用InsertFormatNode函数来将该字符串添加到格式化字符串链中，并返回该字符串在该链表的数组索引; 对于SYS_outputCov函数，根据nID在格式化字符串链表对应的数组中找到该字符串并与函数的其他参数一起工作; 3、 宏说明: 宏名称 意义 MAX_FORMAT_NUM 最大格式化字符串结点个数 MAX_FORMAT_LENGTH 最大格式化字符串长度 4、 函数说明: (1)、打印注册函数: 原型:ST_INT SYS_outputFormat(const ST_CHAR *fmt, ...); 参数:参数名称 参数类型 参数意义 fmt const ST_CHAR * 格式化字符串 … 任意 可变参数 返回值:类型 意义 ST_INT 返回格式化字符串在数组中的索引 说明:传递格式化字符串及其他参数，保存格式化字符串返回其对应的ID 用法:SYS_outputFormat(“value=%d, %d”, 2, 3); 注意:可变参数的个数任意，与printf函数相同 (2)、打印显示函数: 原型:ST_VOID SYS_outputCov(ST_INT nID, ...); 参数:参数名称 参数类型 参数意义 nID ST_INT 格式化字符串对应的ID(即其在数组中的索引) … 任意 可变参数 返回值:无 说明:传递格式化字符串对应的索引，将格式化字符串及其他参数按照要求显示出来; 用法:int nID = 0; nID = SYS_outputFormat(“value=%d, %d”, 2, 3); SYS_outputCov(nID, 3, 5); 注意:可变参数的个数任意，与printf函数相同 (3)、初始化格式化字符串链: 原型:ST_VOID InitFormatArray(ST_VOID); 参数:无 返回值:无 说明:初始化未用格式化字符串链表及相关指针，方便后面动态申请格式化字符串结点，该函数在首次使用InsertFormatNode函数时会调用一次; 用法:内部调用，略。 (4)、分配格式化字符串结点: 原型:ST_VOID MallocFormatNode(LPFORMAT_NODE *lpMalloc); 参数:参数名称 参数类型 参数意义 lpMalloc LPFORMAT_NODE 预分配结点的指针 返回值:无 说明:为当前新的格式化字符串分配一个格式化字符串结点，如果分配空间已用完，那么将最早使用的格式化字符串结点释放再分配; 用法:内部调用，略。 (5)、释放格式化字符串结点: 原型:ST_VOID FreeFormatNode(LPFORMAT_NODE lpFree); 参数:参数名称 参数类型 参数意义 lpFree LPFORMAT_NODE 预释放结点的指针 返回值:无 说明:释放要释放的格式化字符串结点，在分配格式化字符串结点的空间使用完时调用; 用法:内部调用，略。 (6)、添加格式化字符串结点: 原型:ST_INT InsertFormatNode(const ST_CHAR *buf); 参数:参数名称 参数类型 参数意义 buf const ST_CHAR * 指向格式化字符串的指针 返回值:类型 意义 ST_INT 返回该格式化字符串保存在数组中的索引 说明:根据所给的格式化字符串，将该字符串保存到格式化字符串链表中，在打印函数中保存格式化字符串时调用; 用法:内部调用，略。 (7)、查找格式化字符串结点(内部调用): 原型:ST_INT SearchFormatNode(const ST_CHAR *buf); 参数:参数名称 参数类型 参数意义 buf const ST_CHAR * 指向格式化字符串的指针 返回值:类型 意义 ST_INT 如果找到该字符串对应的结点，则返回该结点的索引，否则返回-1; 说明:根据所给的格式化字符串，在格式化字符串中查询该字符串所对应的格式化字符串结点，若能找到，则返回该字符串在数组中的索引，若不能找到则返回-1，在添加格式化字符串结点时首先会调用该函数遍历一下格式化字符串链表，看有没有该字符串; 用法:内部调用，略。 (8)、更新格式化字符串结点(内部调用): 原型:ST_VOID UpdateFormatNode(LPFORMAT_NODE lpPrev, LPFORMAT_NODE lpCurr); 参数:参数名称 参数类型 参数意义 lpPrev LPFORMAT_NODE 当前结点的前序结点 lpCurr LPFORMAT_NODE 当前结点 返回值:无 说明:如果能找到与已给定的格式化字符串相对应的结点，那么需要将该结点从链表中原来的位置移至链表尾，以表明该字符串是最新调用的，同时避免在动态分配结点空间不足时最先被删除，在查找格式化字符串结点成功时调用; 用法:内部调用，略。 5、 备注: 宏MAX_FORMAT_NUM限定了程序中最多可以保存10个字符串，其是可以修改的; 在分配结点时，如果发现10个结点已经分配完，这时候将把最早的结点空间释放再进行分配，所以从 分配的角度上讲，分配是无限制的，但对于格式化字符串对应的ID是有实效性的，当出现覆盖分配时，这时候最早得到的ID可能已经不是其所代表的格式化字符串，所以在获取ID值时应该将其赋给局部变量而不是全局变量;