Device Libraries
The link between Hcon’s DCR files and Hcon’s APIs is provided by the concept of a “Device Library”. A device library is the in-memory representation of a family of equipment specified in DCR files. A device library is formed by calling the following function:
HconT_Library*
Hcon_Library_Create (char* library_name, int num_levels,
PrgT_List* level_names);
The call specifies the depth of the DCH, and the names for devices at each level in the hierarchy. For example, if a site can have multiple routers, each of which contains multiple cards, and each card supports some interface ports, then the arguments to the above function would be as follows:
Library_name = "Cisco_router_library"
num_levels = 4
level_names = ("port", "card", "router", "site")
Initially, the device library is created empty, in the sense that it has no knowledge of specific lines of equipment. The library is then loaded with equipment knowledge by calling the following function:
void
Hcon_Library_Nth_Level_DCR_File_Load (HconT_Library* library,
char* file_name, int level);
This function must be called successively for each level in the hierarchy, in ascending order starting with level 1, as shown below for our four-level example:
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);
Successive calls to this function for the same level do not override each other, they are additive instead. That is, the last call for a given level will cause more devices to be added to the previous content of the library within that level.
Setting Up Demands
Before an application can use Hcon to obtain an equipment configuration, it must assemble a set of demands that need to be satisfied. Demands consist of devices, which may seem odd at first, but consider that these may be level-zero devices which correspond directly to services. For example, a single demand might be for an OC-3 port. However, demands can also consist of higher level components in the hierarchy. For example, we can set up a demand to consist of specific cards and then use Hcon to determine a router that can contain all of the desired cards. Regardless of the level of interest, to assemble demands, first create an empty demand container by calling:
HconT_Demand* Hcon_Demand_Create ();
Then add required devices to the demand, one type at a time, by calling the following function repeatedly:
void Hcon_Demand_Devices_Needed_Add (HconT_Demand* demand
HconT_Libary* library,
int level,
char* vendor,
char* model,
int num_needed);
For example, the following calls create a demand for 4 DS3 ports and 3 OC48 ports. Recall, when reading this example, that for a level-zero device like a port, the vendor is defined to be its property’s name (“Port”) and its model is its property’s value (“DS3”).
Hcon_Demand_Devices_Needed_Add (demand, devlib, 0, "Port", "DS3", 4);
Hcon_Demand_Devices_Needed_Add (demand, devlib, 0, "Port", "OC48", 3);
Building a Hardware Configuration
Now that we have a device library that reflects our equipment universe, and a set of demands we need to satisfy, we are ready to solve the “hardware configuration problem” at hand. The solution is obtained by calling:
PrgT_List*
Hcon_Device_Build_From_Demand (HconT_Demand* demand, HconT_Library* device_library);
If the demand cannot be fulfilled, this function returns NULL. Otherwise, it attempts to find the most cost-effective set of equipment available in the device library that satisfies the specified demand. If the call is successful, the returned list consists of structures of types HconT_Device. More precisely, the list consists of pointers to such structures. The elements in the list are devices at the highest level in the hierarchy. For example, if Hcon found a solution consisting of 3 routers, then the list would contain 3 elements of type HconT_Device*. For each device, the application can determine its properties by calling the following functions:
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) ;
Each device can in turn be analyzed to determine which devices it contains at the level immediately beneath it. This is accomplished by first calling the following function to determine the number of components at the next level:
int Hcon_Device_Components_Count_Get (HconT_Device* dev);
Then, typically within a loop, the following function is called for each component device:
HconT_Device* Hcon_Device_Nth_Component_Get (HconT_Device* dev, int n);
This process can recurse through each level in the hierarchy to analyze the devices that form the hardware configuration recommended by Hcon. In addition, certain higher-level functions are provided to allow you to more conveniently extract information about a recommended hardware configuration.
/* 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) ;
Memory Management
Demands and Devices occupy memory that should be freed once an Hcon result is computed and all of the relevant information has been extracted and processed (e.g., placed in a report or used to calculate the cost of a network). Demands may be preserved if they are to be used again in another call to Hcon_Device_Build_From_Demand(). However, in all cases, demands and devices generated by Hcon functions should eventually be destroyed by calling the following:
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) ;
Note also that you must also destroy the list returned to you by Hcon_Device_Build_From_Demand() as the list construct itself occupies memory. Typically prg_list_destroy() can be used with its dealloc_client_state argument set to 0 so we only destroys the list, not the devices in it which should be freed using Hcon_Demand_Destroy. See the sample code below and the Prg package documentation for information on how to do this.
Finally, you also need to destroy the device library by calling this:
Void Hcon_Library_Destroy (HconT_Library* library);