IFunctionDiscovery::AddInstance method (functiondiscoveryapi.h)

Article
10/13/2021

[Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]

Creates or modifies a function instance.

Syntax

HRESULT AddInstance(
  [in]  SystemVisibilityFlags enumSystemVisibility,
  [in]  const WCHAR           *pszCategory,
  [in]  const WCHAR           *pszSubCategory,
  [in]  const WCHAR           *pszCategoryIdentity,
  [out] IFunctionInstance     **ppIFunctionInstance
);

Parameters

[in] enumSystemVisibility

A SystemVisibilityFlags value that specifies whether the created function instance is visible system wide or only to the current user.

Note The function instance is stored in HKEY_LOCAL_MACHINE regardless of the enumSystemVisibility value. The user must have Administrator access to add a function instance.

[in] pszCategory

The category of the created function instance. See Category Definitions.

[in] pszSubCategory

The subcategory of the created function instance. See Subcategory Definitions. The maximum length of this string is MAX_PATH.

[in] pszCategoryIdentity

The provider instance identifier string. This string is returned from GetProviderInstanceID.

[out] ppIFunctionInstance

A pointer to an IFunctionInstance interface pointer that receives the function instance.

Return value

Possible return values include, but are not limited to, the following.

Return code/value	Description
S_OK	The method completed successfully.
E_INVALIDARG	The value of enumSystemVisibility, pszCategory, or pszCategoryIdentity is invalid.
E_OUTOFMEMORY	The method is unable to allocate the memory required to perform this operation.
E_ACCESSDENIED	The user has insufficient access permission to perform the requested action.
E_FAIL	The provider does not support adding function instances directly using the AddInstance method.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	The value of pszCategory or pszSubCategory is unknown.
STRSAFE_E_INVALID_PARAMETER	An invalid parameter was specified. This error is returned when the length of the pszSubCategory string exceeds MAX_PATH.

Remarks

This method temporarily creates a new function instance for the specified category and subcategory. The provider that implements the category is responsible for persisting the metadata associated with the newly created function instance using the IFunctionDiscoveryProviderFactory::CreateInstance method.

The function instance is not written to the registry if its associated property store does not have any values. Use the IFunctionInstance::OpenPropertyStore method to check the property store values.

If a function instance already exists for the specified category and subcategory, the existing registry entry is overwritten. The AddInstance method returns S_OK. The Function Discovery change notification process invokes the calling application's IFunctionDiscoveryNotification::OnUpdate method with enumQueryUpdateAction set to QUA_CHANGE.

Note The IFunctionDiscoveryNotification::OnUpdate method is not supported by any current provider.

Whether the new function instance is capable of being visible system-wide or only to the user depends on the provider. The registry provider initially sets its default function instance visibility to system wide.

Access permission to change HKEY_LOCAL_MACHINE\SYSTEM registry keys is required in order to add or remove function instances using the registry provider (Administrator or Power User access).

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	functiondiscoveryapi.h
DLL	FunDisc.dll