IFunctionDiscoveryProviderFactory::CreateInstance method (functiondiscoveryprovider.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 a function instance. All function instances should be created using this method. Other implementations that support IFunctionInstance should not be used.

Syntax

HRESULT CreateInstance(
  [in]  const WCHAR                *pszSubCategory,
  [in]  const WCHAR                *pszProviderInstanceIdentity,
  [in]  INT_PTR                    iProviderInstanceContext,
  [in]  IPropertyStore             *pIPropertyStore,
  [in]  IFunctionDiscoveryProvider *pIFunctionDiscoveryProvider,
  [out] IFunctionInstance          **ppIFunctionInstance
);

Parameters

[in] pszSubCategory

The subcategory string for the function instance. See Subcategory Definitions.

[in] pszProviderInstanceIdentity

The provider instance identifier.

Function Discovery uses this identifier to ensure that function instance identifiers returned by IFunctionInstance::GetID are unique. To that end, Function Discovery attaches a prefix to the identifier passed to pszProviderInstanceIdentity to ensure that a given function instance identifier is unique across all providers. Implementers only need to ensure that pszProviderInstanceIdentity uniquely identifies the device, resource, or instance within the scope of the provider.

This string is returned to client applications that call IFunctionInstance::GetProviderInstanceID.

There is no upper limit on the size of this string.

[in] iProviderInstanceContext

The context associated with the specific function instance.

[in] pIPropertyStore

A pointer to an IPropertyStore interface.

[in] pIFunctionDiscoveryProvider

A pointer to the IFunctionDiscoveryProvider provider instance creating this function instance.

[out] ppIFunctionInstance

A pointer to an IFunctionInstance interface.

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The provider should specify the subcategory (may be NULL), the instance identifier, a provider-allocated context (if required), and an optional property store.

CreateInstance returns an appropriately initialized function instance to the provider.

The context specified by the provider will be passed back to the provider for all subsequent function instance related methods, such as InstanceReleased, InstancePropertyStoreOpen, InstancePropertyStoreFlush, and InstanceQueryService.

The provider must guarantee that the provider reference count does not go to zero, possibly on another thread, while CreateInstance is being called.

Requirements

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

Share via