ParameterStyleRepCap::ExpandSingleSelector

Vi

[in] ViSession handle for the driver session.

szSelector

[in] A repeated capability selector, which can be a virtual name. An error results if more than one physical name is represented by this parameter.

physicalName

[out] A PhysicalName object containing the physical name corresponding to the supplied szSelector.

Returns a VI_SUCCESS if the operation was successful or a failure ViStatus otherwise. If the szSelector parameter represents more than one physical name, the the error code IVIC_ERROR_BADLY_FORMED_SELECTOR is returned. That same error code is also returned if the szSelector parameter contains invalid physical name characters.

If the szSelector parameter represents a virtual name, this function translates that virtual name to the corresponding physical name.

Repeated capability selectors are widely used in IVI-C drivers, and this function performs critical validation and error checking required by the IVI specifications. Thus, this function should be used whenever a repeated capability selector is passed by the user as a driver function parameter AND only a single selector is expected. For instance, whenever a user calls the getter for an attribute (e.g. GetAttributeViInt32), the implementation can only supply a single value, so the function must validate that the RepCapIdentifier parameter represents only a single physical name. Such cases can be handled using the ExpandSingleSelector function.

If the szSelector parameter is VI_NULL or whitespace, then this function validates that the repeated capability has only a single physical name defined. If more than one physical name is defined when szSelector is VI_NULL or whitespace, then this function returns a ViStatus value of IVIC_ERROR_CHANNEL_NAME_REQUIRED, as required by the IVI specifications.

The following example demonstrates use of the ExpandSingleSelector function.

ViStatus _VI_FUNC acme4321_get_BANDWIDTH(ViSession Vi, ViConstString RepCapIdentifier, ViReal64* AttributeValue)
{
    PhysicalName<Channel> physicalName;
    ReturnOnError(Channel::ExpandSingleSelector(Vi, RepCapIdentifier, physicalName));

    // ...
}