Siemens NX二次开发
上QQ阅读APP看本书,新人免费读10天
设备和账号都新为新人

5.5 NXOpen C

NXOpen C开放了超过5000个API,面对如此多的API,如何快速找到自己期望的API?这需要开发者掌握两方面的知识,一是了解关于NXOpen C API名称的一些命名约定,二是掌握API帮助文档的搜索功能。

5.5.1 NXOpen C命名约定

NXOpen C API有两种命名约定,即标准命名约定与遗留命名约定。

(1)标准命名约定(Standard Naming Convention):根据API所在的模块与实现的功能赋予有意义的名称。这一类API格式是UF_<area>_<name>,UF是User Function的简写。<area>通常是对应用模块或功能领域的说明,例如:UF_MODL_create_sphere中的MODL就表示Modeling模块。<name>通常是对实现的具体功能的描述,一般由动词或名词组成,常见的词语有ask(查询)、get(获取)、create(创建)、new(新建)、edit(编辑)、delete(删除)、set(设置)、init(初始化)、remove(移除)等。

(2)遗留命名约定(Legacy Naming Convention):这一类API的名称格式是uc<××××>或者uf<××××>,<××××>通常是4位数字或者3位数字加一字母(NX早期采用FORTRAN语言开发,FORTRAN77中变量名长度限制为6)。这一类型的API大部分已经被其他标准命名约定的API替代,但还有一部分被开发者青睐,如uc1601、uf5947,它们的名字没有规律可循,需要开发者积累经验。

相关知识的介绍,开发者也可以参考官方帮助文档Open C Programmer's Guide中与“Command Line Arguments”相关的描述。

当开发者了解NXOpen C命名约定后,就可以从API帮助文档中去寻找期望的API。例如:期望利用NXOpen C中的API创建一个Sketch(草图),根据模块分类这个API应该是以UF_SKET开头的,很容易找到它“UF_SKET_create_sketch”。

也可以在API帮助文档中搜索关键词,如图5-6所示。如果您不太确定关键词是什么,可以考虑将NX切换为英文版,在其中找到相应功能所对应的英文单词,再利用这些单词在API帮助文档中搜索。

图5-6 NXOpen C API帮助文档界面

5.5.2 NXOpen C API分类

开发者在使用NXOpen C API时,应该添加对应的头文件,头文件与API分类一一对应。例如:新建一个部件使用的API是UF_PART_new,那就应该添加“uf_part.h”这个头文件,NXOpen C API分类如表5-4所示。

表5-4 NXOpen C API分类

续表

续表

续表

5.5.3 NXOpen C对象

NX中包含了很多对象,例如:Feature(特征)、Point(点)、Body(体)、Face(面)、Edge(边)等。到目前为止,常见的对象被定义在“%UGII_BASE_DIR%\UGOPEN\uf_object_types.h”文件中。

对象拥有Type(类型)与Subtype(子类型)两部分定义,Subtype可更详细地描述对象(可以利用UF_OBJ_ask_type_and_subtype来获取对象的Type与Subtype)。对于NX中已经存在的对象,如果期望找到它们,一般使用以下这些API:

如开发者期望遍历得到当前工作部件中所有的Body,可以参考以下代码格式:

NX对象存在四种状态,可以利用UF_OBJ_ask_status获取对象的状态。这四种状态分别是:

● UF_OBJ_ALIVE:表明该对象是活动的。

● UF_OBJ_DELETED:表明对象已删除。

● UF_OBJ_TEMPORARY:表明对象是临时的,不保存在部件中。例如:利用UF_CSYS_create_temp_csys创建的CSYS。

● UF_OBJ_CONDEMNED:这种状态的对象通常在NX中不显示,例如:矩阵对象、智能对象。

在开发应用程序时,为了保证代码更加健壮,一般情况下会先获取对象的状态,如果对象的状态为是“UF_OBJ_ALIVE”再执行相关操作。

5.5.4 NXOpen C数据类型

除C/C++标准的数据类型外,NXOpen C还大量使用结构体、联合结构体、枚举、指针等数据类型,常见的数据类型约定如表5-5所示。

表5-5 NXOpen C数据类型约定

除了后缀满足上表约定,数据类型的命名约定还与API命名约定一致,下面的结构体展示了这一点,它来自与建模相关的头文件(uf_modl_types.h)。

在NXOpen C中,使用最多的数据类型是tag_t,在文件“%UGII_BASE_DIR%\UGOPEN\uf_defs.h”中的定义如下:

这种数据类型,早期被称为“Eid”(实体标识符,Entity Identifier),如今统一称为“对象标识符”(Object Identifier)。

在NX系统中,每一个对象,都有唯一的标识符。可以理解为每一个对象都是由大于0的不重复整数来标识它,对象标识符是由NX系统根据一定的算法规则临时生成的,它不会随着部件的保存而保存。例如:开发者期望当前工作部件中指定的Face(面),在下次打开部件时,自动高亮显示它。而一般情况下,同一部件在不同的计算机上打开,或者被再次打开后,对象标识符的值是不相同的。此时,开发者可以考虑利用“handle”(句柄)来解决这个问题。Handle会随着部件的保存而保存,相关API如下:

5.5.5 NXOpen C API声明

NXOpen C提供的API符合ANSI/ISO C标准,在相应的头文件中定义的原型格式为:

● <return data type>:大部分的NXOpen C API返回都是一个整数(int),为0时,表明该API执行正常;非0时,表明API执行有异常。如果开发者期望获取非0整数所代表的意义,需要使用UF_get_fail_message这个API。需要注意的是,有部分API返回非0整数时,不表示执行有异常,例如:UF_PART_ask_num_parts这个API返回的是当前NX会话中加载部件的数量。

● <function name>:遵循前述的“NXOpen C命名约定”。

● (argument list):参考API帮助文档或者相应头文件说明。

在利用NXOpen C开发应用程序时,开发者需要仔细阅读理解API帮助文档。在API帮助文档中,API的描述一般由以下部分组成:

● Defined in:描述API被定义在哪个头文件中。

● Overview:描述API实现的功能等。

● Environment:描述API允许的运行模式。如果描述中不包含关键词“External”,说明这个API不允许以批处理模式(Batch,又称外部模式External)运行。例如:uc1601这个API不允许以批处理模式运行。

● See Also:描述与该API相关联或者类似的API。若描述中含有“Refer to example”关键字段,表明这个API有样例,点击它即可查看。

● History:描述API发布的NX版本。

● Required License(s):使用该API需要的License。

● API详细声明:一般格式如表5-6所示(以UF_MODL_create_plane为例)。

表5-6 API详细声明

在理解这些声明时,开发者可以根据NX工具本身的输入参数进行判断,如上表中关于创建Plane的声明。创建Plane需要一个点和一个法向量,所以在输入参数中,会要求指定Plane的原点及法向量,如果成功创建就输出创建Plane的标识符。

5.5.6 UF_CALL函数

在官方样例中(如“%UGII_BASE_DIR%\UGOPEN\ufd_curve_create_arc.c”),经常会看到在NXOpen C API的前面加上“UF_CALL”函数,如下所示,为什么要这样做呢?

在研究此问题之前,先设想一种场景,当应用程序代码上万行时,出现了BUG,如何快速找到问题?如前所述,大部分的NXOpen C API返回一个整数,如果非0表示有异常。有没有一种手段能在应用程序遇到异常时,自动告诉我们是哪行代码因为何种原因引起的呢?

官方样例中的UF_CALL为解决这一问题提供了可行性。UF_CALL是一个自定义的宏,开发者可以参考官方思路进行修改,以下通过实例进行说明。

(1)启动Visual Studio,利用NXOpen C++Wizard创建一个名为ch5_3的项目(本例代码保存在“D:\nxopen_demo\code\ch5_3”),删除原有内容再添加下列代码:

(2)编译链接生成*.dll文件。

(3)在NX中打开或新建一部件文件,单击“File”→“Execute”→“NX Open”按钮,在弹出的对话框中选择动态链接库“ch5_3.dll”,运行结果如图5-7所示。

图5-7 使用UF_CALL显示异常结果

从图中可以看出,当使用NXOpen C API时,添加UF_CALL遇到异常后会以Information窗口形式显示详细信息。

通过这种方式,可以快速定位异常代码,提高开发效率。这个样例仅展示了UF_CALL的一种用法,开发者可以根据实际需求进行调整,例如:将异常信息打印在日志文件中代替打印在Information窗口。

5.5.7 动态内存

使用动态内存是开发应用程序时常见的做法。动态分配内存与释放内存的API如下:

除以上这几个常用API外,还有一部分特定释放内存的API,如UF_CURVE_free_trim,开发者需要仔细查阅API帮助文档。

常见分配内存的代码格式如下:

5.5.8 NXOpen C对象转换

开发者在操作NX中的对象时,必须理解对象之间的区别与联系。例如:利用NXOpen C中的UF_MODL_create_block创建了一个Block,输出的是Block Feature的标识符,此时如果要对所有的Edge(边)进行Edge Blend操作,那传入的对象是每一条Edge的标识符,而不是Feature的标识符。这就涉及对象之间的相互转换,常见的对象转换API如下:

以下通过一个实例来说明对象转换的必要性,假定需求是:创建一个圆台,原点坐标为(15,20,30),旋转中心轴方向平行于绝对坐标系的Z方向;底面直径为50,顶面直径为25,高度为40,此时这个圆台拥有两个平面、一个锥面和两条边,需要找出直径最大的一边条再创建边倒圆特征,倒角半径值为5,如图5-8所示。

图5-8 创建结果

这个实例将展示:NXOpen C对象之间的转换;NXOpen C中链表的使用方法;如何通过一定的算法,找出期望的对象;如何合理地释放内存。

以下为实现本功能的核心代码(本例完整代码保存在“D:\nxopen_demo\code\ch5_4”)。