CAA V5 Authorized API Identification, Usage, Deprecation, and Stability-理解 CAA 授权 API 机制与标记

摘要

本文介绍了有关 CAA 授权 API 限定符及使用的相关规则。
  • CAA 授权 API
  • CAA 授权 API 限定符
  • CAA 授权 API 弃用说明
  • CAA 授权 API 稳定性
  • CAA 授权 API 附加标记
  • 应用程序所需的 CAA 授权 API
  • CAA 授权与弃用 API 及达索系统（DS）内部资源处理
    • CAA 授权 API 处理
    • CAA 弃用 API 处理
    • 达索系统（DS）内部资源处理
  • 版本代码级别与市场命名之间的对应关系

CAA 授权 API

V5 配置及产品模块可包含授权 API，用于开发客户端应用程序。由某一配置或产品授权的 API，存放于该配置或产品所属一个或多个框架的 PublicInterfaces 目录中。在这些目录下还可能存在其他 API，例如：
  • 从 #include 语句角度，用部分达索系统（DS）内部资源补全授权 API 集合
  • 使不同工具生成的代码能够正常编译构建
客户端应用程序只能使用被标记为 CAA 授权 API 限定符 的授权 API。这些限定符有助于将它们与其他仅用于构建的 API 区分开来。此外，某些授权 API（如类或接口）可能仅被部分授权 **。例如，一个类可能只授权其方法中的一个子集。** 作为一名 CAA 开发者，若想了解你可以使用哪些 API，你可以：
  1. 查阅《CAA 百科全书》中的 CAA 授权 API 参考部分：
    • C++ API 参考
    • 自动化 API 参考
    • Java API 参考
  2. 查阅 C++ 或 IDL 头文件，并解读如下所述的 CAA 授权 API 限定符和标签。
请记住：未在《CAA 百科全书》中记载的内容均为达索系统（DS）内部资源，严禁在客户端应用程序中使用。
Java API 不包含 CAA 授权 API 限定符。只有已文档化的 Java API 才是授权可用的。

CAA 授权 API 限定符

这些限定符位于文件顶部，包含在 /** */ 注释块内。以下是此类标记的示例：
#ifndef CATTopologicalBlend_H
#define CATTopologicalBlend_H
// COPYRIGHT DASSAULT SYSTEMES 1999
/**
 * @CAA2Level L1
 * @CAA2Usage U1
 */
这些限定符的含义为：
@CAA2Level L1 　　将该头文件标记为授权 API
@CAA2Usage U1 　　定义头文件的预期用途。有效值范围为 U0 至 U6
取值含义目标说明
L0 授权 API ・向客户、商业合作伙伴和采纳者提供用于 Beta 测试的授权 API
 
・提供将在后续版本中升级为 L1 级别的授权 API，以便开展验证 / 评估流程		 ・不保证兼容性，但允许使用
 
・可能在无任何预警的情况下变更或移除
 
・不提供配套文档
L1 授权 API 向客户、商业合作伙伴和采纳者提供可用于应用开发的可靠 API ・除非该授权 API 已提前两个版本标记为弃用，否则跨版本保证编译期兼容性
 
・同一版本的不同服务包（SP）之间保证运行期兼容性
 
・提供配套文档		 















头文件的使用方式取决于其在客户端应用程序中的预期用途。





取值用法含义





U0
用法未指定，为 L0 授权接口预留。

 

不过 L0 授权接口也可指定 U1～U6 范围内的用法。		




U1
具体类：仅可直接使用（C++ 用法）

 

通常用法为实例化该类，或获取指向该类已有实例的指针，然后调用其方法。		




U2
具体类：允许被继承（C++ 用法）

 

通常用法为创建新类继承此类，可重写部分方法并新增方法，再在客户端程序中使用。		




U3
接口：不可重新实现，仅可直接使用（C++、IDL 用法）

 

通常用法为在实现该接口的 CAA 组件上获取接口指针，然后调用其方法。		




U4
接口：可通过 DS 适配器重新实现（C++ 用法）

 

通常用法为在客户端组件上实现该接口，一般在 C++ 扩展类中继承 DS 提供的专用适配器类（该适配器为 U2 用法）。只需实现接口方法的子集，其余由适配器实现，通常文档仅标注需要实现的方法。

 

U4 用法后会附带需使用的适配器。例如 CATIEdit 接口必须由继承适配器 CATExtIEdit 的类实现：

 

<code>/**

 

* @CAA2Level L1

 

* @CAA2Usage U4 CATExtIEdit

 

*/</code>		




U5
接口：必须完整重新实现（C++ 用法）

 

通常用法为在客户端组件上实现该接口的全部方法。		




U6
接口：必须被继承（C++ 用法）

 

通常用法为创建继承自此接口且不新增方法的新接口，并实现该派生接口。例如工作台或插件对外暴露的接口即属此类。		























CAA 授权 API 废弃说明




当某个 CAA 授权 API 不再适用时，该 API 将被标记为已废弃。尽管这种情况本应是特例，但由于 CAA 授权 API 数量庞大，废弃发生的频率往往高于预期。废弃流程如下：




    

  1. 废弃操作适用于 C++、自动化（Automation）及 Java API。
    2. 

  2. 可被废弃的授权 API 包括：类、接口、方法、全局函数、枚举、结构体、#define 宏定义等各类授权 API。
    3. 

  3. 授权 API 仅在 V5 新版本正式发布（GA，General Availability） 时被标记为废弃，绝不会在服务包（SP，Service Pack）更新中废弃。
    4. 

  4. 已废弃 API 自其被废弃的版本起，仍会在后续两个正式版本周期内保持可用。
    5. 

  5. 自 V5-6R2012 版本起，版本号可使用市场命名（如 V5-6R2012）或代码层级命名（如 V5R22）标识，二者对应关系可查阅相关文档。下文统一使用代码层级命名，便于理解版本先后顺序。

     
    
示例：某授权 API 自 V5R11 起被标记废弃，则该 API 在 V5R11 与 V5R12 整个生命周期内均保持不变且可用。
    6. 

  6. 每个已废弃 API 都会标注替代用授权 API，客户端应用必须改用该替代 API。替代 API 在原 API 废弃时已同步可用。这两个版本的过渡期，专供 CAA 开发者修改客户端代码，适配新的替代 API。

     
    
已废弃 API 可在 CAA 百科全书查阅，其中按开发语言分别提供废弃索引：

      

    • CAA C++ API 废弃索引
      • 

    • CAA IDL API 废弃索引
      • 

    • CAA Java API 废弃索引
      • 

    

    7. 

  7. 重新编译包含已废弃 API 的客户端应用模块时，编译器会抛出废弃警告。
    8. 

  8. 已废弃 API 将在其被废弃的版本之后的第三个正式版本中，从 CAA 授权 API 中彻底移除。

     
    
示例：某 API 自 V5R11 起废弃，则将在 V5R13 正式版（GA） 中被移除。
    9. 





CAA 授权 API 稳定性




客户端应用程序的兼容性取决于 CAA 授权 API 在服务包（SP）之间以及正式版本之间的稳定性。




CAA 授权 API 通过以下方式进行管控：




    

  • 

    在同一 V5 版本的各服务包（SP）之间保持运行时兼容。
    

    • 



这意味着客户端应用程序在新的 V5 版本上只需重新编译，无需修改代码；除非客户端使用了已标记为废弃的授权 API，且该 API 已废弃超过两个版本。


    

  • 

    重新编译应用时，每发现一个已废弃 API 都会发出警告。详见《CAA API 废弃机制》。
    

    • 









两个连续服务包（SP）之间允许的、可保持运行时兼容的修改：




    

  • 添加新的类和接口
    • 

  • 对于 U1 “直接使用” 类：新增具体的公有方法
    • 

  • 对于 U2 “可被继承” 类：新增具体的公有或保护方法
    • 

  • 对于 U1 和 U2 类：均可新增、修改或删除具体的私有方法
    • 

  • 对于接口：不允许任何修改
    • 









两个连续正式版本之间允许的、可保持编译时兼容的修改：




包含上述所有修改，另外允许：




    

  • 在功能已由其他 API 替代的前提下，将类 / 接口 / 方法声明为已废弃
    • 

  • 在废弃满两个版本后，删除或取消暴露已废弃的 API
    • 

  • 

    这意味着客户端应用程序无需在不同服务包下重新编译。
    

    • 

  • 

    在两个连续的 V5 正式版本之间保持编译时兼容，前提是未触发 API 废弃流程。
    

    • 



CAA 授权 API 附加标记


在扫描头文件时，你可能会在任意代码元素上方的注释中发现两个 CAA 标记，这些元素包括类、接口、枚举、类型定义、#define 或宏、结构体声明，以及全局函数或方法原型。该标记会针对此元素，局部重置头文件中设定的 CAA 授权 API 限定符。这两个标记分别是：







标记含义





@nodoc
禁止使用

 

表示该内容为达索（DS）内部资源，严禁使用。		




@deprecated
不再使用

 


表示该 API 曾为授权 API，但即将被移除。参见《CAA 授权 API 废弃机制》。标记语法如下：


/**
 * @deprecated V5R11 CATBaseUnknown
 * ...

V5R11 表示该授权 API 从 V5R11 版本开始被废弃，对应的替代 API 为 CATBaseUnknown。从 V5R13 版本开始，该 API 将被禁止使用。























应用程序所需的 CAA 授权 API


CAA 授权 API 由不同配置项和产品模块提供：


    

  • 运行时配置项或产品模块受许可证保护（例如 MD2 许可证）。该许可证授权构成此配置项或产品模块的部分 V5 框架。此配置项或产品模块中的 CAA 相关部分，由上述框架中至少包含一个 CAA V5 授权 API的子集组成。
    • 

  • 若某基于 CAA V5 开发的应用程序或产品需要与指定运行时许可证兼容，则必须基于上述框架子集进行开发。
    • 

  • 该基于 CAA V5 开发的应用程序或产品，必须在恰好包含此运行时许可证的环境中运行。
    • 



如需确定您的应用程序需要使用哪些 CAA 授权 API，请访问 CAA 官方网站。如尚未注册请先完成注册，然后进入开发者专区的 C++ 与 Java 主页。点击左侧框架中的 CONFIGURATION CONTENTS（配置内容），并选择对应的 V5 版本、介质以及配置项或产品模块，即可查看其提供的框架列表。
CAA 授权与废弃 API 及 DS 内部资源处理
RADE 工具对 CAA 授权 API、CAA 废弃 API 以及 DS 内部资源采用不同的处理方式。
CAA 授权 API 处理





领域编译构建文档未授权符号稳定性检查





行为
仅当 API 已废弃时才会产生警告，除此之外不生成任何警告。
授权 API 会出现在 CAA V5 百科全书中。
授权 API 不会存入 “未授权符号” 数据库中。
不同正式版本之间确保编译时兼容性，除非该授权 API 在此前两个版本已被标记废弃。

 


 

同一版本的不同服务包（SP）之间确保运行时兼容性：在同一版本内不允许做任何修改。		























CAA 废弃 API 处理





领域编译构建文档未授权符号稳定性检查





行为
仅当 API 已废弃时才会产生警告，除此之外不生成任何警告。
废弃 API 会在 CAA V5 百科全书中标注为已废弃，并显示对应的替代授权 API。
废弃 API 不会存入 “未授权符号” 数据库中。
不同正式版本之间确保编译时兼容性，除非该授权 API 在此前两个版本已被标记废弃。

 


 

同一版本的不同服务包（SP）之间确保运行时兼容性：在同一版本内不允许做任何修改。		






 















DS 内部资源处理


DS 内部资源严禁使用。







领域编译构建文档未授权符号稳定性检查





行为
向开发者显示警告，但库仍可编译构建。

 

无效库在运行时会被拒绝加载。		
DS 内部资源不会出现在 CAA 百科全书中。
DS 内部资源会被存入 “未授权符号” 数据库中。
不提供任何稳定性保障。























版本代码层级与市场名称对应关系


从 V5-6R2012 版本开始，一个版本可通过市场名称（例如：V5-6R2012）或代码层级（例如：V5R22）进行标识。市场名称与代码层级的对应关系如下表所示：







代码层级市场名称





V5R22
V5-6R2012





















 


 












            

            
posted @ 
2026-04-01 22:33 
Breadss 
阅读(5) 
评论(0) 
 
收藏 
举报