Property Identifiers

Simple property identifers are the most common form of property identifiers and are used to reference properties that are defined on the same class. Drivers that contain no repeated capabilities use a single class to implement all properties, so these drivers need only use this form of property identifiers. More complex drivers may need to use extended property identifers to reference properties implemented on different classes.

Simple property identifiers have the following form:

<interface>.<property>`

Since only the interface name and property name are specified, it is implied that the referenced property exists on the same class. When Nimbus attempts to resolve a simple property identifier, it will only look on the class of the calling function to locate the specified interface and property.

The following example shows use of the InvalidateCacheEntry with a simple property identifier to manually implement a coupling between the Bandwidth property and the Frequency property.

STDMETHODIMP Acme4321::IAcme4321_put_Bandwidth(double dVal)
{
   HRESULT hr = S_OK;

   InvalidateCacheEntry("IAcme4321.Frequency");

   return S_OK;
};

In some instances, it may be necessary for implementation code in one class to reference a property that resides on a completely different class. Typically this situation arises when the driver contains repeated capabilities, such as the channels repeated capability of the IviScope instrument class. Nimbus supports a special syntax called extended property identifiers to deal with precisely this situation.

Extended property identifers prepend the simple property identifier with a repeated capability identifier to denote the class on which the property exists.

<repeated capability identifier>.<interface>.<property>

The repeated capability identifier includes the name of the repeated capability class as well as the index of the specific instance of that class. For example, the repeated capability identifier Acme4321Channel[2] identifies the third instance of the Acme4321Channel repeated capability class.

In the case of nested repeated capabilities, the repeated capability identifier may include more than one class name. For instance, if the channel repeated capability contained a child Trace repeated capability, then a valid repeated capability identifier to reference properties on a trace class might look like Acme4321Channel[1].Acme4321Trace[0].

Note

Repeated capability identifiers are always interpreted as being relative to the class from which it is used. The first class listed in the repeated capability identifier is understood to be an immediate child repeated capability of the calling class. If it is necessary to reference a property on a repeated capabilility that is not a direct descendant of the calling class, then the repeated capability identifier must start with the class name "Driver" (representing the main driver class) and explicitly list all parent classes of the referenced property. The last example below demonstrates this particular situation.

The following example shows use of the InvalidateCacheEntry with an extended property identifier to manually implement a coupling between the Bandwidth property of the Acme4321Channel repeated capability and the Span property on the second instance of the Acme54600Trace repeated capability.

STDMETHODIMP Acme4321::IAcme4321_put_Bandwidth(double dVal)
{
   HRESULT hr = S_OK;

   InvalidateCacheEntry("Acme4321Trace[1].IAcme4321.Span");

   return S_OK;
};

This example demonstrates referencing a property on a nested repeated capability. The implemenation of the put_Frequency method on the main driver class uses the InvalidateCacheEntry function to invalidate the cache entry for the Amplitude property on the fourth instance of the Trace child repeated capability on the third instance of the Measurement repeated capability.

STDMETHODIMP Acme4321::IAcme4321_put_Frequency(double dVal)
{
   HRESULT hr = S_OK;

   InvalidateCacheEntry("Acme4321Measurement[2].Acme4321Trace[3].IAcme4321Trace.Amplitude");

   return S_OK;
};

In the final example below, the Amplitude property is implemented on a Trace repeated capability that is a direct child repeated capability of the main driver class. This Amplitude property references the Frequency property on a channel repeated capability that is also a direct child repeated capability of the main driver class. Hence, the "Driver" prefix must be used to access the Channel repeated capability since that repeated capability is not a child of the Trace repeated capability.

STDMETHODIMP Acme4321::IAcme4321Trace_put_Amplitude(double dVal)
{
   HRESULT hr = S_OK;

   InvalidateCacheEntry("Driver.Acme4321Channel[2].IAcme4321Channel.Frequency");

   return S_OK;
};

Other Resources