MsiSetFeatureState

[This is preliminary documentation and subject to change.]

The MsiSetFeatureState function sets a feature to a specified state.

UINT MsiSetFeatureState(
  MSIHANDLE hInstall,     // installer handle
  LPCTSTR szFeature,      // name of feature
  INSTALLSTATE iState     // install state
);
 

Parameters

hInstall

Handle to the installation.

szFeature

Specifies the name of the feature.

iState

Specifies the state to set. This parameter can be one of the following values.

Value	Meaning
INSTALLSTATE_ABSENT	The feature was uninstalled.
INSTALLSTATE_LOCAL	The feature was installed on the local drive.
INSTALLSTATE_SOURCE	The feature will run from source, CD, or network.

Return Values

ERROR_FUNCTION_FAILED

The function failed.

ERROR_INVALID_HANDLE

An invalid or inactive handle was supplied.

ERROR_INVALID_PARAMETER

One of the parameters was invalid.

ERROR_SUCCESS

The function succeeded.

ERROR_UNKNOWN_FEATURE

An unknown feature was requested.

Remarks

The MsiSetFeatureState function requests a change in the select state of a feature in the Feature table and its children. In turn, the Action state of all the components linked to the changed Feature records are also updated appropriately, based on the new feature Select state.

The MsiSetInstallLevel function must be called before calling MsiSetFeatureState.

When MsiSetFeatureState is called, the installer attempts to set the Action state of each component tied to the specified feature to the specified state. However, there are common situations when the request cannot be fully implemented. For example, suppose a feature is tied to two components, component A and component B, through the FeatureComponents table. Also suppose that component A is authored with a RunFromSource option of IRSLOCALONLY and component B is authored with a RunFromSource option of IRSSOURCEONLY. In this case, if MsiSetFeatureState is called with a requested state of either INSTALLSTATE_LOCAL or INSTALLSTATE_SOURCE, the request cannot be fully implemented for both components. However, both components are turned ON, with component A set to Local and component B set to Source.

If more than one feature is linked to a single component (a common scenario), the final Action state of that component is determined as follows.

• If at least one feature requires the component to be installed locally, the feature is installed with a state of Local.
• If at least one feature requires the component to be run from source , the feature is installed with a state of Source.
• If at least one feature requires the removal of the component, the action state is Absent.

QuickInfo

  Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in msiquery.h.
  Import Library: Use msi.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Selection Functions