Chapter 3: Opening Configurations

Home Prev	InControl 4.00.02 SDK Guide	Next

This chapter discusses how to obtain and check out a cOS Core configuration in preparation for editing.

It is useful at this point to look at the relationships between the classes involved in obtaining a cOS Core configuration.

The C# code to retrieve a Configuration object is as follows:

Domain global = server.get_Root();
		
Device sgwStockholm =
	server.GetConfigObjectByName(global, "sgwStockholm") as Device;
		
server.CheckOutConfiguration(sgwStockholm);

Configuration cfg = server.GetLatestConfiguration(sgwStockholm);

Let us now break the steps in this code down.

Checking Out Gateways

Once the Configuration object is obtained we can perform a check out of the firewall in order to start editing the configuration. This is a suggested ordering and the check out of the gateway could be done before obtaining the configuration.

	Note
	Checking out a firewall is not necessary if the operations performed on the configuration only involve reading the configuration's contents. If modifications are to be made then the firewall has to be checked out.

Get the root domain of the server which will provide the methods to access individual firewalls:
```
Domain global = server.get_Root();
```
Assuming that there is a NetWall firewall in the root domain named sgwStockholm, get the Device object for this gateway:
```
Device sgwStockholm =
	server.GetConfigObjectByName(root, "sgwStockholm") as Device;
```
At this point the application is able to read configuration information but cannot change it until a check out operation is performed.
Check out this firewall by invoking the CheckOutConfiguration method of the Device class.
```
server.CheckOutConfiguration(sgwStockholm);
```
After the checkout, the application will have exclusive access to the firewall's configuration and no other client will be able to check it out.

Checking back in the firewall is discussed in Chapter 5, Check In and Deployment.

Opening a Configuration

Before we can work with a configuration we must obtain a specific version, usually the latest, as a Configuration object instance. To get the latest version we would use the code:

Configuration cfg = server.GetLatestConfiguration(sgw);

This code retrieves the latest version of the specific firewall's configuration. The InControl server maintains a database of past versions and it is also possible to get a list of all available versions and select a particular version.

Enumerating Domains and Gateways

Sometimes, the name of a gateway may not be known beforehand. In that case, it is useful to be able to enumerate all the objects under the global domain. This is done by first obtaining the global domain, as was done above:

Domain global = server.get_Root();

Next, obtain an array of all the child objects under the global domain:

System.Guid[] children = GetConfigObjectChildIds(global.Id);

Now it is possible to go through the array of all the children:

foreach(Guid g in children)
	{ConfigObject object = server.GetConfigObjectById(global, g)
		"
		"
	}

Each instance of object could be either a domain or gateway. To determine if object is a gateway in this loop, use the boolean expression:

if (object is Device)....

Similarly, to determine if object is a domain, use the expression:

if (object is Domain)....

To determine if an object has a particular name, for example My_GW, use the expression:

if (object.Name == "My_GW")....