Repeated Capabilities

The simplest type of repeated capability is the parameter style. Parameter-style repeated capabilities are used most commonly in IVI-C drivers, though they can also appear in IVI-COM drivers. As the name implies, parameter-style repeated capabilities are supported by simply adding an extra string parameter to any function that applies to a repeated capability (as opposed to a function that applies to the driver as a whole). The client application passes in either a valid physical or virtual repeated capability name for this parameter to identify the particular repeated capability instance to access.

The code below shows an IVI.NET driver client using the SetOperationMode function from the IviFGen class specification:

var fgen = IviFgen.Create("MyLogicalName");
// ...
fgen.SetOperationMode("Output1", OperationMode.Burst);

In the code above, the second parameter is the repeated capability name. The repeated capability name almost always appears as the second parameter to a function that applies to a repeated capability. The example is setting the operation mode to burst for only the output channel identified by Output1. The name Output1 could be a physical name or a virtual name.

Drivers that expose a parameter-style repeated capability always expose a couple of additional functions and attributes that allow you to programmatically determine the number of repeated capabilities instances (e.g. "channels") and the physical names supported (e.g. channel names). The names of these support functions are also standardized, so that they can easily be identified when the name of the capability is know. IVI-COM drivers and IVI-C drivers differ slightly in the repeated capability support functions they expose for parameter-style repeated capabilities.

For IVI.NET drivers exposing parameter-style repeated capabilities, the following are required to be present:

• Count property

• Get<Capability>Name property (Ex: GetChannelName)

The client code simply reads the value of the Count property and then uses this value to iterate through the repeated capability instances. The GetName method accepts a zero-based index parameter to identify which repeated capability instance name is desired. The code below shows how to iterate through all of the physical names supported by an IVI.NET FGen driver that exposes a "Channel" repeated capability.

var fgen = IviFgen.Create("MyLogicalName");
// ...
for (int i = 0; i < fgen.Output.Count; i++)
{
  Console.WriteLine(fgen.GetChannelName(i));
}

Selector-style repeated capabilities use a special selector function to set the "active" repeated capability. Subsequent function calls that apply to a repeated capability are understood to apply to the active instance. The active instance remains active until the client code sets the active instance to another repeated capability name. Selector-style repeated capabilities have the advantage of not requiring a repeated capability name to be passed to every function that applies to the repeated capability.

As with parameter-style repeated capabilities, drivers that expose a selector-style repeated capability always expose additional functions for managing the repeated capability instances. Indeed, the selector-style repeated capability uses the same functions and attributes as the parameter style, with the addition of one property and one function for setting and getting the active instance.

For IVI.NET drivers, the following are required to be present:

• Count property

• Get<Capability>Name method (Ex: GetChannelName)

• Active<Capability> property (Ex: ActiveChannel)

Since the selector-style repeated capability uses the same Count attribute and GetName function as the parameter style, the code required to iterate through the instance names for a selector-style repeated capability is identical to that shown above for the parameter style.

The most common type of repeated capability for IVI.NET drivers is the collection-style repeated capability.

As with the parameter and collection style, collection-style repeated capabilities always expose a Count and Name attribute for iterating through the list of available repeated capability names. Unique to collection-style repeated capabilities is the Item property, which provides access to individual repeated capability instances. The Item property accepts a repeated capability name (physical name or virtual name) and returns an interface pointer to the desired repeated capability instance. All method and property calls on the returned interface pointer implicitly apply to the repeated capability instance chosen with the Item property.

The C# code below demonstrates how to use the Item property to access a channel called CH1 and enable it.

var scope = IviScope.Create("MyLogicalName");
// ...
var channel = scope.Channels["CH1"];
channel.Enabled = true;

Note that declaring the intermediate variable for the IIviScopeChannel interface returned by indexer is not necessary. Depending upon the client application, it may be more convenient to write the code as follows:

var scope = IviScope.Create("MyLogicalName");
// ...
scope.Channels["CH1"].Enabled = true;