IFunctionDiscovery::AddInstance method (functiondiscoveryapi.h)

  • Article

[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

See also

IFunctionDiscovery