![]() | ParameterStyleRepCap::ExpandSingleSelector |
Translates a repeated capability selector into a single physical name.
static ViStatus ExpandSingleSelector(ViSession Vi, ViConstString szSelector, PhysicalName<T>& physicalName);
[in] ViSession handle for the driver session.
[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.
[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)); // ... }