设备库
Hcon 的 DCR 文件与 Hcon API 之间的纽带由“设备库”(Device Library)这一概念提供。设备库是 DCR 文件中指定的一组设备系列在内存中的表示。调用以下函数即可构建设备库:
HconT_Library*
Hcon_Library_Create (char* library_name, int num_levels,
PrgT_List* level_names);
该调用指定 DCH 的深度,以及层次结构中每一层设备的名称。例如,若一个站点可以有多台路由器,每台路由器又包含多块卡,每块卡支持若干接口端口,则上述函数的参数可如下所示:
Library_name = "Cisco_router_library"
num_levels = 4
level_names = ("port", "card", "router", "site")
设备库最初创建时是空的,即它不了解任何具体的设备系列。随后通过调用以下函数向库中加载设备知识:
void
Hcon_Library_Nth_Level_DCR_File_Load (HconT_Library* library,
char* file_name, int level);
该函数必须按层次结构中各层的升序(从 level 1 开始)逐层连续调用,我们的四层示例如下:
Hcon_Library_Nth_Level_DCR_File_Load
("Cisco_router_library",card_config_file1, 1);
Hcon_Library_Nth_Level_DCR_File_Load
("Cisco_router_library",router_config_file, 2);
Hcon_Library_Nth_Level_DCR_File_Load
("Cisco_router_library",site_config_file, 3);
对同一层连续调用该函数并不会相互覆盖,而是叠加生效。也就是说,对某一层最后一次调用会在该层库中已有的内容基础上再添加更多设备。
设置需求
应用程序在使用 Hcon 获取设备配置之前,必须先组装一组需要满足的需求(demand)。需求由设备构成,初看起来可能有些奇怪,但要知道这些设备可能是第零层设备,直接对应于服务。例如,一条需求可能只是一个 OC-3 端口。但需求也可以由层次结构中更高层的组件构成。例如,我们可以设置一条由特定卡组成的需求,然后用 Hcon 确定一台能够容纳所有所需卡的路由器。无论关注的是哪一层,组装需求时都要先调用以下函数创建一个空的需求容器:
HconT_Demand* Hcon_Demand_Create ();
然后通过反复调用以下函数,一次一种类型地向需求中添加所需设备:
void Hcon_Demand_Devices_Needed_Add (HconT_Demand* demand
HconT_Libary* library,
int level,
char* vendor,
char* model,
int num_needed);
例如,以下调用创建了一条包含 4 个 DS3 端口和 3 个 OC48 端口的需求。阅读此例时请记住,对于端口这样的第零层设备,其厂商被定义为该属性的名称(“Port”),其型号为该属性的值(“DS3”)。
Hcon_Demand_Devices_Needed_Add (demand, devlib, 0, "Port", "DS3", 4);
Hcon_Demand_Devices_Needed_Add (demand, devlib, 0, "Port", "OC48", 3);
构建硬件配置
现在我们有了反映设备全集的设备库,也有了需要满足的一组需求,可以着手解决眼前的“硬件配置问题”了。求解通过调用以下函数获得:
PrgT_List*
Hcon_Device_Build_From_Demand (HconT_Demand* demand, HconT_Library* device_library);
如果需求无法满足,该函数返回 NULL。否则,它会尝试在设备库中找出可满足指定需求、最具成本效益的设备集合。若调用成功,返回的列表由 HconT_Device 类型的结构组成;更准确地说,列表由指向这些结构的指针组成。列表中的元素是层次结构最高层的设备。例如,若 Hcon 找到由 3 台路由器组成的方案,则列表将包含 3 个 HconT_Device* 类型的元素。对每个设备,应用程序可以调用以下函数确定其属性:
void Hcon_Device_Model_Name_Get (HconT_Device*dev, char* buf) ;
void Hcon_Device_Vendor_Name_Get (HconT_Device* dev, char* buf) ;
double Hcon_Device_Cost_Get (HconT_Device* dev) ;
每个设备本身又可以进一步分析,以确定它在紧邻的下一层包含哪些设备。做法是先调用以下函数确定下一层组件的数量:
int Hcon_Device_Components_Count_Get (HconT_Device* dev);
然后通常在循环中对每个组件设备调用以下函数:
HconT_Device* Hcon_Device_Nth_Component_Get (HconT_Device* dev, int n);
这一过程可以逐层递归,分析构成 Hcon 推荐硬件配置的设备。此外,还提供了一些更高层的函数,便于更方便地提取有关推荐硬件配置的信息。
/* Get device cost, will recursively include cost of all its components */
/* plus the device itself. If the device is a router, this function will */
/* return the cost of the router plus the cost of all the cards installed */
/* in that router. */
double Hcon_Device_Cost_Get_Inclusive (HconT_Device* dev) ;
内存管理
需求(Demand)和设备(Device)占用内存,在计算出 Hcon 结果并提取、处理完所有相关信息之后(例如写入报告或用于计算网络成本),应当释放这些内存。如果需求还要在另一次 Hcon_Device_Build_From_Demand() 调用中重复使用,则可以保留。但无论如何,由 Hcon 函数生成的需求和设备最终都应通过调用以下函数销毁:
void Hcon_Demand_Destroy (HconT_Demand * demand);
/* Free the memory used by a device. This will also recursively destroy */
/* all its components */
void Hcon_Device_Destroy (HconT_Device* dev) ;
另请注意,Hcon_Device_Build_From_Demand() 返回给你的列表本身也必须销毁,因为列表结构本身占用内存。通常可以使用 prg_list_destroy(),并将其 dealloc_client_state 参数设为 0,这样只销毁列表而不销毁其中的设备(其中的设备应使用 Hcon_Demand_Destroy 释放)。具体做法参见下面的示例代码以及 Prg 包的文档。
最后,还需要通过调用以下函数销毁设备库:
Void Hcon_Library_Destroy (HconT_Library* library);