using System;
using System.Runtime.InteropServices;
using static Vanara.PInvoke.Ole32;
using static Vanara.PInvoke.PropSys;
namespace Vanara.PInvoke
{
/// Interfaces and constants from the Function Discovery API.
// https://docs.microsoft.com/en-us/previous-versions/windows/desktop/fundisc/fd-portal
public static partial class FunDisc
{
/// The type of event.
[PInvokeData("functiondiscoveryapi.h")]
public enum FD_EVENTID : uint
{
///
FD_EVENTID_PRIVATE = 100,
///
FD_EVENTID = 1000,
///
/// The search was completed by a provider. Typically, this notification is sent by network protocol providers where the
/// protocol specifies a defined interval in which search results will be accepted. Both the WSD and SSDP providers use this
/// event type. Once this notification is sent, a query ignores all incoming responses to the initial search or probe request.
/// However, the query will still monitor for Hello or Bye messages (used to indicate when a device is added or removed). The
/// query will continue to monitor for these events until Release is called on the query object. This notification will not be
/// sent if a catastrophic error occurs. For information about how this event is implemented or used by a specific provider,
/// follow the link to the provider documentation from the Built-in Providers topic.
///
FD_EVENTID_SEARCHCOMPLETE = FD_EVENTID,
/// Not used by Function Discovery clients.
FD_EVENTID_ASYNCTHREADEXIT = FD_EVENTID + 1,
/// Not used by Function Discovery clients.
FD_EVENTID_SEARCHSTART = FD_EVENTID + 2,
///
/// The IP address of the NIC changed. The WSD provider implements this notification. Events may be sent when a power event
/// occurs (for example, when machine wakes from sleep) or when roaming with a laptop.
///
FD_EVENTID_IPADDRESSCHANGE = FD_EVENTID + 3,
///
FD_EVENTID_QUERYREFRESH = FD_EVENTID + 4,
}
///
[PInvokeData("functiondiscoveryapi.h")]
public enum QueryCategoryType
{
///
QCT_PROVIDER = 0,
///
QCT_LAYERED = 1
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// Represents the type of action Function Discovery is performing on the specified function instance. This information is used by
/// the client program's change notification handler.
///
///
///
/// When a client program implements the IFunctionDiscoveryNotification interface and passes the address of the interface to one of
/// the Query methods, Function Discovery calls the client program's IFunctionDiscoveryNotification::OnUpdate method to notify the
/// client program when a function instance which meets the query parameters has been added, removed, or modified.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/ne-functiondiscoveryapi-queryupdateaction typedef enum
// tagQueryUpdateAction { QUA_ADD, QUA_REMOVE, QUA_CHANGE } QueryUpdateAction;
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NE:functiondiscoveryapi.tagQueryUpdateAction")]
public enum QueryUpdateAction
{
/// Function Discovery is adding the specified function instance.
QUA_ADD,
/// Function Discovery is removing the specified function instance.
QUA_REMOVE,
/// Function Discovery is modifying the specified function instance.
QUA_CHANGE,
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
/// Determines the visibility of the function instance's data.
///
///
/// All data operations and function instances are stored in HKEY_LOCAL_MACHINE. Access to a function instance or its data with
/// system-wide visibility must be performed with Administrator access permissions.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/ne-functiondiscoveryapi-systemvisibilityflags typedef
// enum tagSystemVisibilityFlags { SVF_SYSTEM, SVF_USER } SystemVisibilityFlags;
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NE:functiondiscoveryapi.tagSystemVisibilityFlags")]
public enum SystemVisibilityFlags
{
/// The function instance's data is available to all users on the system.
SVF_SYSTEM,
/// The function instance's data is accessible only to the current user.
SVF_USER,
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// This interface is used by client programs to discover function instances, get the default function instance for a category, and
/// create advanced Function Discovery query objects that enable registering Function Discovery defaults, among other things.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctiondiscovery
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionDiscovery")]
[ComImport, Guid("4df99b70-e148-4432-b004-4c9eeb535a5e"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(FunctionDiscovery))]
public interface IFunctionDiscovery
{
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the specified collection of function instances, based on category and subcategory.
///
/// The identifier of the category to be enumerated. See Category Definitions.
///
/// The identifier of the subcategory to be enumerated. See Subcategory Definitions. This parameter can be NULL.
///
///
///
/// If TRUE, this method recursively enumerates all the subcategories of the category specified in pszCategory, returning
/// a collection containing function instances from all the subcategories of pszCategory.
///
///
/// If FALSE, this method restricts itself to returning function instances in the category specified by pszCategory and
/// the subcategory specified by pszSubCategory.
///
///
///
/// A pointer to an IFunctionInstanceCollection interface pointer that receives the function instance collection containing the
/// requested function instances. The collection is empty if no qualifying function instances are found.
///
///
/// 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 pszCategory is invalid. The value returned in ppIFunctionInstanceCollection parameter is NULL.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002
/// The value of pszCategory or pszSubCategory is unknown.
///
/// -
/// E_PENDING
/// The call was executed for a provider that returns results asynchronously.
///
///
///
///
///
/// Some function discovery providers return their query results with the IFunctionDiscoveryNotification interface.
/// GetInstanceCollection does not find function instances that are returned in this way and will fail with E_PENDING. It
/// is recommended that clients use the CreateInstanceQuery method of the IFunctionDiscovery interface to find function
/// instances for such providers.
///
///
/// If the method succeeds but no function instances were found that matched the query parameters, then S_OK is returned
/// and ppFunctionInstanceCollection points to an empty collection (the collection's GetCount method returns 0).
///
///
/// Subcategory queries are only supported for layered categories and some provider categories. The Registry Provider, the PnP-X
/// association provider, and the publication provider support subcategory queries. Custom providers can be explicitly designed
/// to support subcategory queries. For other providers, function instance collections can be filtered using query constraints.
/// For a list of query constraints, see Constraint Definitions.
///
/// Examples
///
/// The following code returns the function instances associated with the SSDP provider in the Microsoft.Networking.Devices namespace.
///
///
/// hr = spDisco->GetInstanceCollection(FCTN_CATEGORY_NETWORKDEVICES, FCTN_SUBCAT_NETWORKDEVICES_SSDP, FALSE, &spFunctionInstanceCollection);
///
///
/// See interface constraints on IFunctionInstanceQuery to filter on multiple interfaces at one time or to filter on providers
/// that do not support subcategory queries.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-getinstancecollection
// HRESULT GetInstanceCollection( const WCHAR *pszCategory, const WCHAR *pszSubCategory, BOOL fIncludeAllSubCategories,
// IFunctionInstanceCollection **ppIFunctionInstanceCollection );
[PreserveSig]
HRESULT GetInstanceCollection([MarshalAs(UnmanagedType.LPWStr)] string pszCategory, [MarshalAs(UnmanagedType.LPWStr), Optional] string pszSubCategory,
[MarshalAs(UnmanagedType.Bool)] bool fIncludeAllSubCategories, out IFunctionInstanceCollection ppIFunctionInstanceCollection);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the specified function instance, based on identifier.
///
/// The identifier of the function instance (see GetID).
/// A pointer to an IFunctionInstance interface pointer used to return the interface.
///
/// 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 pszFunctionInstanceIdentity is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_OBJECT_NOT_FOUND) 0x800710d8
/// The function instance represented by the specified ID does not exist on this computer.
///
/// -
/// E_PENDING
/// The call was executed for a provider that returns results asynchronously.
///
///
///
///
/// Some function discovery providers return their query results with the IFunctionDiscoveryNotification interface.
/// GetInstance does not find function instances that are returned in this way and will fail with E_PENDING. It is
/// recommended that clients use the CreateInstanceQuery method of the IFunctionDiscovery interface to find function instances
/// for such providers.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-getinstance
// HRESULT GetInstance( const WCHAR *pszFunctionInstanceIdentity, IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT GetInstance([MarshalAs(UnmanagedType.LPWStr)] string pszFunctionInstanceIdentity, out IFunctionInstance ppIFunctionInstance);
///
///
/// [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 query for a collection of specific function instances.
///
/// The category for the query. See Category Definitions.
///
/// The subcategory for the query. See Subcategory Definitions. This parameter can be NULL.
///
/// Subcategory queries are only supported for layered categories and some provider categories. The Registry Provider, the PnP-X
/// association provider, and the publication provider support subcategory queries. Custom providers can be explicitly designed
/// to support subcategory queries. This means the pszSubCategory parameter should be set to a non- NULL value only when
/// the pszCategory parameter is set to FCTN_CATEGORY_REGISTRY, FCTN_CATEGORY_PUBLICATION,
/// FCTN_CATEGORY_PNPXASSOCIATION, or a custom category value defined for either a layered category or a custom provider
/// supporting subcategory queries.
///
///
///
///
/// If TRUE, this method recursively creates a query for all the subcategories of the category specified in pszCategory,
/// returning a collection containing function instances from all the subcategories of pszCategory.
///
///
/// If FALSE, this method restricts the created query to returning function instances in the category specified by
/// pszCategory and the subcategory specified by pszSubCategory.
///
///
///
/// A pointer to the IFunctionDiscoveryNotification interface implemented by the calling application. This parameter can be
/// NULL. This pointer is valid until the returned query object is released.
///
///
/// A pointer to the context in which the query was created. The type ulong is defined as a DWORDLONG.
///
/// A pointer to the IFunctionInstanceCollectionQuery interface pointer.
///
/// 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 pszCategory or pIID is invalid. The value returned in ppIFunctionInstanceCollectionQuery parameter is NULL.
///
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002
/// The value of pszCategory or pszSubCategory is unknown.
///
///
///
///
///
/// If pIFunctionDiscoveryNotification is specified, it enables the Function Discovery change notification process. This
/// parameter can be NULL. However, it is required for network providers since they do not return synchronous results.
/// Function Discovery network providers only return instances through the IFunctionDiscoveryNotification interface.
///
///
/// This method only initializes the query call. The Execute method of the IFunctionInstanceCollectionQuery interface returned
/// in ppIFunctionInstanceCollectionQuery must be called to perform the query and return any data.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-createinstancecollectionquery
// HRESULT CreateInstanceCollectionQuery( const WCHAR *pszCategory, const WCHAR *pszSubCategory, BOOL fIncludeAllSubCategories,
// IFunctionDiscoveryNotification *pIFunctionDiscoveryNotification, ulong *pfdqcQueryContext, IFunctionInstanceCollectionQuery
// **ppIFunctionInstanceCollectionQuery );
[PreserveSig]
HRESULT CreateInstanceCollectionQuery([MarshalAs(UnmanagedType.LPWStr)] string pszCategory,
[MarshalAs(UnmanagedType.LPWStr), Optional] string pszSubCategory,
[MarshalAs(UnmanagedType.Bool)] bool fIncludeAllSubCategories,
IFunctionDiscoveryNotification pIFunctionDiscoveryNotification, ref ulong pfdqcQueryContext,
out IFunctionInstanceCollectionQuery ppIFunctionInstanceCollectionQuery);
///
///
/// [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 query for a specific function instance.
///
/// The identifier of the function instance.
///
/// A pointer to the IFunctionDiscoveryNotification interface implemented by the calling application. If specified, it enables
/// the Function Discovery change notification process. This parameter can be NULL; however it is required for network providers.
///
///
/// A pointer to the context in which the query was created. The type ulong is defined as a DWORDLONG.
///
///
/// A pointer to an IFunctionInstanceQuery interface pointer used to return the generated query.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// ppIFunctionInstanceQuery is NULL.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
///
/// Function Discovery Network providers only return instances through the IFunctionDiscoveryNotification interface.
///
/// This method only initializes the query call. The Execute method of the IFunctionInstanceQuery interface returned in
/// ppIFunctionInstanceQuery must be called to perform the query and return any data.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-createinstancequery
// HRESULT CreateInstanceQuery( const WCHAR *pszFunctionInstanceIdentity, IFunctionDiscoveryNotification
// *pIFunctionDiscoveryNotification, ulong *pfdqcQueryContext, IFunctionInstanceQuery **ppIFunctionInstanceQuery );
[PreserveSig]
HRESULT CreateInstanceQuery([MarshalAs(UnmanagedType.LPWStr)] string pszFunctionInstanceIdentity,
IFunctionDiscoveryNotification pIFunctionDiscoveryNotification, ref ulong pfdqcQueryContext,
out IFunctionInstanceQuery ppIFunctionInstanceQuery);
///
///
/// [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.
///
///
///
/// 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.
///
///
/// The category of the created function instance. See Category Definitions.
///
/// The subcategory of the created function instance. See Subcategory Definitions. The maximum length of this string is MAX_PATH.
///
/// The provider instance identifier string. This string is returned from GetProviderInstanceID.
/// A pointer to an IFunctionInstance interface pointer that receives the function instance.
///
/// 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.
///
///
///
///
///
/// 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).
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-addinstance
// HRESULT AddInstance( SystemVisibilityFlags enumSystemVisibility, const WCHAR *pszCategory, const WCHAR *pszSubCategory, const
// WCHAR *pszCategoryIdentity, IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT AddInstance(SystemVisibilityFlags enumSystemVisibility, [MarshalAs(UnmanagedType.LPWStr)] string pszCategory,
[MarshalAs(UnmanagedType.LPWStr), Optional] string pszSubCategory,
[MarshalAs(UnmanagedType.LPWStr)] string pszCategoryIdentity, out IFunctionInstance ppIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Removes the specified function instance, based on category and subcategory.
///
///
/// A SystemVisibilityFlags value that specifies whether the function instance is removed system-wide or only for the current user.
///
/// The category of the function instance. See Category Definitions.
///
/// The subcategory of the function instance to be removed. See Subcategory Definitions. This parameter can be NULL.
///
/// The provider instance identifier string. This string is returned from GetProviderInstanceID.
///
/// 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 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.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002
/// The value of pszCategory or pszSubCategory is unknown.
///
///
///
///
///
/// 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 levels). The user must have Administrator access to remove a
/// function instance system-wide.
///
/// Note This method is not supported by all providers.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscovery-removeinstance
// HRESULT RemoveInstance( SystemVisibilityFlags enumSystemVisibility, const WCHAR *pszCategory, const WCHAR *pszSubCategory,
// const WCHAR *pszCategoryIdentity );
[PreserveSig]
HRESULT RemoveInstance(SystemVisibilityFlags enumSystemVisibility, [MarshalAs(UnmanagedType.LPWStr)] string pszCategory,
[MarshalAs(UnmanagedType.LPWStr), Optional] string pszSubCategory,
[MarshalAs(UnmanagedType.LPWStr)] string pszCategoryIdentity);
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// This interface is implemented by the client program to support asynchronous queries and is called by Function Discovery to
/// notify the client program when a function instance that meets the query parameters has been added or removed.
///
///
///
///
/// This interface must be implemented by the client program in order to receive notifications from Function Discovery. The address
/// of the client program's implementation is passed to one of the query methods to enable notifications for function instances
/// which meet the query parameters.
///
///
/// Function Discovery calls the client program's IFunctionDiscoveryNotification::OnUpdate method to perform the actual
/// notification, which is generated for a function instance when it is added or removed.
///
/// Examples
/// The examples that appear on individual method pages are based on the following class declaration.
///
/// class CMyNotificationListener : public CFunctionDiscoveryNotificationWrapper { public: CMyNotificationListener() { m_hAddEvent = CreateEvent( NULL, FALSE, FALSE, NULL ); m_hRemoveEvent = CreateEvent( NULL, FALSE, FALSE, NULL ); m_hChangeEvent = CreateEvent( NULL, FALSE, FALSE, NULL ); } ~CMyNotificationListener() { CloseHandle( m_hAddEvent ); CloseHandle( m_hRemoveEvent ); CloseHandle( m_hChangeEvent ); } private: HANDLE m_hAddEvent, m_hRemoveEvent, m_hChangeEvent; };
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctiondiscoverynotification
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionDiscoveryNotification")]
[ComImport, Guid("5f6c1ba8-5330-422e-a368-572b244d3f87"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IFunctionDiscoveryNotification
{
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
///
/// Indicates that a function instance has been added, removed, or changed. This method is implemented by the client program and
/// is called by Function Discovery.
///
///
///
/// A QueryUpdateAction value that specifies the type of action Function Discovery is performing on the specified function instance.
///
///
/// The context registered for change notification. The type ulong is defined as a DWORDLONG. This parameter can be NULL.
///
///
/// An IFunctionInstance interface pointer that represents the function instance being affected by the update.
///
///
///
/// The client program's implementation of the OnUpdate method should return one of the following HRESULT values
/// to the caller.
///
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of one of the input parameters is invalid.
///
///
///
///
///
/// Do not call Release on the query object from this method. Doing so could cause a deadlock. If Release is
/// called on a query object from another thread while a callback is in process, the object will not be released until the
/// callback has finished.
///
///
/// All notifications passed to Function Discovery by providers are queued and returned to the client one by one. Callbacks are
/// synchronized so that a client will only receive one notification at a time.
///
///
/// Because other IFunctionDiscoveryNotification method calls may be made in other threads, any changes made to the thread state
/// during the call must be restored before exiting the method.
///
/// Examples
///
/// The following code shows an OnUpdate handler implementation. The CMyNotificationListener class is defined in the
/// IFunctionDiscoveryNotification topic.
///
///
/// #include <windows.h> HRESULT STDMETHODCALLTYPE CMyNotificationListener::OnUpdate( IN QueryUpdateAction Action, IN ulong fdqcQueryContext, IN IFunctionInstance *pInstance) { HRESULT hr = S_OK; switch (Action) { case QUA_ADD: SetEvent( m_hAddEvent ); break; case QUA_REMOVE: SetEvent( m_hRemoveEvent ); break; case QUA_CHANGE: SetEvent( m_hChangeEvent ); break; } return S_OK; }
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscoverynotification-onupdate
// HRESULT OnUpdate( QueryUpdateAction enumQueryUpdateAction, ulong fdqcQueryContext, IFunctionInstance *pIFunctionInstance );
[PreserveSig]
HRESULT OnUpdate(QueryUpdateAction enumQueryUpdateAction, ulong fdqcQueryContext, IFunctionInstance pIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Receives errors that occur during asynchronous query processing.
///
/// The query error that is being reported.
///
/// The context registered for change notification. The type FDQUERYCONTEXT is defined as a DWORDLONG.
///
/// The name of the provider.
///
///
/// The client program's implementation of the OnError method should return one of the following HRESULT values to
/// the caller.
///
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of one of the input parameters is invalid.
///
///
///
///
///
/// Typically, clients will expect that any asynchronous error is fatal and that the query will stop returning results, but
/// custom provider documentation could indicate otherwise for specific error codes.
///
///
/// Do not call Release on the query object from this method. Doing so could cause a deadlock. If Release is
/// called on a query object from another thread while a callback is in process, the object will not be released until the
/// callback has finished.
///
///
/// All notifications passed to Function Discovery by providers are queued and returned to the client one by one. Callbacks are
/// synchronized so that a client will only receive one notification at a time.
///
///
/// Because other IFunctionDiscoveryNotification method calls may be made in other threads, any changes made to the thread state
/// during the call must be restored before exiting the method.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscoverynotification-onerror
// HRESULT OnError( HRESULT hr, FDQUERYCONTEXT fdqcQueryContext, const WCHAR *pszProvider );
[PreserveSig]
HRESULT OnError(HRESULT hr, ulong fdqcQueryContext, [MarshalAs(UnmanagedType.LPWStr)] string pszProvider);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Receives any add, remove, or update events during a notification.
///
///
/// The type of event.
///
///
/// Value
/// Meaning
///
/// -
/// FD_EVENTID_SEARCHCOMPLETE 1000
///
/// The search was completed by a provider. Typically, this notification is sent by network protocol providers where the
/// protocol specifies a defined interval in which search results will be accepted. Both the WSD and SSDP providers use this
/// event type. Once this notification is sent, a query ignores all incoming responses to the initial search or probe request.
/// However, the query will still monitor for Hello or Bye messages (used to indicate when a device is added or removed). The
/// query will continue to monitor for these events until Release is called on the query object. This notification will not be
/// sent if a catastrophic error occurs. For information about how this event is implemented or used by a specific provider,
/// follow the link to the provider documentation from the Built-in Providers topic.
///
///
/// -
/// FD_EVENTID_ASYNCTHREADEXIT 1001
/// Not used by Function Discovery clients.
///
/// -
/// FD_EVENTID_SEARCHSTART 1002
/// Not used by Function Discovery clients.
///
/// -
/// FD_EVENTID_IPADDRESSCHANGE 1003
///
/// The IP address of the NIC changed. The WSD provider implements this notification. Events may be sent when a power event
/// occurs (for example, when machine wakes from sleep) or when roaming with a laptop.
///
///
///
///
///
/// The context registered for change notification. The type FDQUERYCONTEXT is defined as a DWORDLONG. This
/// parameter can be NULL.
///
/// The name of the provider.
///
///
/// The client program's implementation of the OnEvent method should return one of the following HRESULT values to
/// the caller.
///
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of one of the input parameters is invalid.
///
///
///
///
/// Function Discovery providers (SSDP and WSD) use this method to implement notifications that a search pass is complete.
///
/// Do not call Release on the query object from this method. Doing so could cause a deadlock. If Release is
/// called on a query object from another thread while a callback is in process, the object will not be released until the
/// callback has finished.
///
///
/// All notifications passed to Function Discovery by providers are queued and returned to the client one by one. Callbacks are
/// synchronized so that a client will only receive one notification at a time.
///
///
/// Because other IFunctionDiscoveryNotification method calls may be made in other threads, any changes made to the thread state
/// during the call must be restored before exiting the method.
///
/// Examples
///
/// The following example shows an OnEvent handler implementation. The CMyNotificationListener class is defined in the
/// IFunctionDiscoveryNotification topic.
///
///
/// #include <windows.h> HRESULT CMyNotificationListener::OnEvent( IN DWORD dwEventID, IN FDQUERYCONTEXT fdqcQueryContext, IN const WCHAR * pszProvider ) { HRESULT hr = S_OK; HANDLE hSearchComplete = INVALID_HANDLE_VALUE; hSearchComplete = OpenEventW( EVENT_ALL_ACCESS, FALSE, L"SearchComplete" ); if( NULL == hSearchComplete ) { return hr; } if( FD_EVENTID_SEARCHCOMPLETE == dwEventID ) { SetEvent( hSearchComplete ); } CloseHandle( hSearchComplete ); return hr; }
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctiondiscoverynotification-onevent
// HRESULT OnEvent( DWORD dwEventID, FDQUERYCONTEXT fdqcQueryContext, const WCHAR *pszProvider );
[PreserveSig]
HRESULT OnEvent(FD_EVENTID dwEventID, ulong fdqcQueryContext, [MarshalAs(UnmanagedType.LPWStr)] string pszProvider);
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// A function instance is created as the result of calling one of the IFunctionDiscovery methods; client program do not create
/// these objects themselves.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctioninstance
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionInstance")]
[ComImport, Guid("33591c10-0bed-4f02-b0ab-1530d5533ee9"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IFunctionInstance
{
/// Performs as a factory for services that are exposed through an implementation of IServiceProvider.
/// A unique identifier of the requested service.
/// A unique identifier of the interface which the caller wishes to receive for the service.
/// The interface specified by the parameter.
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
[PreserveSig]
HRESULT QueryService(in Guid guidService, in Guid riid, [MarshalAs(UnmanagedType.Interface, IidParameterIndex = 1)] out object ppvObject);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
///
/// Gets the identifier string for the function instance. This identifier can be saved and later used to re-query for the same
/// function instance through IFunctionDiscovery::GetInstance.
///
///
///
/// The function instance identifier string. There is no upper limit on the size of this string.
///
/// This string is a composed string generated by Function Discovery. It has the provider instance identifier string as a
/// substring. For more information about provider identifiers, see IFunctionInstance::GetProviderInstanceID.
///
///
/// For function instances returned by a built-in provider, this identifier is guaranteed to uniquely identify a resource on a
/// system, even if the resource is disconnected and reconnected. For function instances returned by custom providers, the
/// function instance identifier is unique if the provider has a unique provider identifier.
///
///
/// This identifier should not be manipulated or manufactured programmatically. The string should only be used to retrieve
/// function instances and for comparison purposes.
///
/// Be sure to free this buffer using CoTaskMemFree.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of ppszCoMemID is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstance-getid
// HRESULT GetID( WCHAR **ppszCoMemIdentity );
[PreserveSig]
HRESULT GetID([MarshalAs(UnmanagedType.LPWStr)] out string ppszCoMemIdentity);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the identifier string for the provider instance. This string is the unique identifier for the provider instance.
///
///
/// The provider instance identifier string. For root devices, this string has the same value as PKEY_PNPX_GlobalIdentity.
/// Be sure to free this buffer using CoTaskMemFree.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of ppszCoMemProviderInstanceID is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstance-getproviderinstanceid
// HRESULT GetProviderInstanceID( WCHAR **ppszCoMemProviderInstanceIdentity );
[PreserveSig]
HRESULT GetProviderInstanceID([MarshalAs(UnmanagedType.LPWStr)] out string ppszCoMemProviderInstanceIdentity);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
///
/// Opens the property store for the function instance. The property store contains metadata about the function instance, such
/// as its name, icon, installation date, and other information.
///
///
///
/// The access mode to be assigned to the open stream. For this method, the following access modes are supported:
/// STGM_READ
/// STGM_READWRITE
/// STGM_WRITE
///
/// A pointer to an IPropertyStore interface pointer.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// STG_E_ACCESSDENIED
///
/// The method could not open a writeable property store because the caller has insufficient access or the discovery provider
/// does not allow write access to its property store.
///
///
/// -
/// E_INVALIDARG
/// The value of dwStgAccess is invalid.
///
/// -
/// E_POINTER
/// The ppIPropertyStore points to invalid memory.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
///
///
/// Only one property store per function instance can be open at a time. If OpenPropertyStore is called twice on the same
/// function instance, both ppIPropertyStore pointers would point to the same property store. Furthermore, the access mode (as
/// specified by the dwStgAccess parameter) would be determined by the most recent OpenPropertyStore call. Applications
/// should call Release to close a property store before opening another.
///
///
/// It is possible that OpenPropertyStore will return a property store for a device that has been removed. In this case,
/// the property keys in the store will be empty. This situation may occur if the device's devnode was deleted but the property
/// store associated with the device's function instance is still accessible. This situation occurs rarely.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstance-openpropertystore
// HRESULT OpenPropertyStore( DWORD dwStgAccess, IPropertyStore **ppIPropertyStore );
[PreserveSig]
HRESULT OpenPropertyStore(STGM dwStgAccess, out IPropertyStore ppIPropertyStore);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the category and subcategory strings for the function instance.
///
///
/// The null-terminated identifier string of the category. See Category Definitions.
/// Be sure to free this buffer using CoTaskMemFree.
///
/// The null-terminated identifier string of the subcategory. See Subcategory Definitions.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
///
/// The category and subcategory of a function instance always refer to the provider category from which a function instance comes.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstance-getcategory
// HRESULT GetCategory( WCHAR **ppszCoMemCategory, WCHAR **ppszCoMemSubCategory );
[PreserveSig]
HRESULT GetCategory([MarshalAs(UnmanagedType.LPWStr)] out string ppszCoMemCategory, [MarshalAs(UnmanagedType.LPWStr)] out string ppszCoMemSubCategory);
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// This interface represents a group of IFunctionInstance objects returned as the result of a query or get instance request through
/// one of the IFunctionDiscovery methods; client program do not create these collections themselves.
///
///
///
/// The IFunctionInstanceCollection interface allows a client program to enumerate a collection of IFunctionInstance objects.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctioninstancecollection
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionInstanceCollection")]
[ComImport, Guid("f0a3d895-855c-42a2-948d-2f97d450ecb1"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(FunctionInstanceCollection))]
public interface IFunctionInstanceCollection
{
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the number of function instances in the collection.
///
/// The number of function instances.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The pdwCount parameter is NULL.
///
///
///
///
/// The GetCount and Item methods enables you to enumerate all of the function instances contained in a collection using
/// a simple for or while loop.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-getcount
// HRESULT GetCount( DWORD *pdwCount );
[PreserveSig]
HRESULT GetCount(out uint pdwCount);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the specified function instance and its index from the collection.
///
/// The identifier of the function instance to be retrieved (see GetID).
/// The index number.
/// A pointer to an IFunctionInstance interface pointer that receives the function instance.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// S_FALSE
/// The function instance identified by pInstanceIdentity is not present in the function instance collection.
///
/// -
/// E_INVALIDARG
/// The value of pdwIndex or pInstanceIdentity is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-get
// HRESULT Get( const WCHAR *pszInstanceIdentity, DWORD *pdwIndex, IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT Get([MarshalAs(UnmanagedType.LPWStr)] string pszInstanceIdentity, out uint pdwIndex, out IFunctionInstance ppIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Gets the specified function instance, by index.
///
/// The zero-based index of the function instance to be retrieved.
/// A pointer to an IFunctionInstance interface pointer that receives the function instance.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The ppFunctionInstance parameter is NULL or dwIndex is out of range.
///
///
///
///
/// The GetCount and Item methods enables you to enumerate all of the function instances contained in a collection using
/// a simple for or while loop.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-item
// HRESULT Item( DWORD dwIndex, IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT Item(uint dwIndex, out IFunctionInstance ppIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Adds a function instance to the collection.
///
///
/// A pointer to an IFunctionInstance interface for the function instance to be added to the collection.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of pIFunctionInstance is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-add
// HRESULT Add( IFunctionInstance *pIFunctionInstance );
[PreserveSig]
HRESULT Add(IFunctionInstance pIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Deletes the specified function instance and returns a pointer to the function instance being removed.
///
/// The index number within the collection.
/// A pointer to an IFunctionInstance interface pointer that receives the function instance.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of dwIndex is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-remove
// HRESULT Remove( DWORD dwIndex, IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT Remove(uint dwIndex, out IFunctionInstance ppIFunctionInstance);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Removes the specified function instance from the collection.
///
/// The index number of the item to be removed from the collection.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The value of dwIndex is invalid.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-delete
// HRESULT Delete( DWORD dwIndex );
[PreserveSig]
HRESULT Delete(uint dwIndex);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Removes all function instances from the collection.
///
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollection-deleteall
// HRESULT DeleteAll();
[PreserveSig]
HRESULT DeleteAll();
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// This interface implements the asynchronous query for a collection of function instances based on category and subcategory. A
/// pointer to this interface is returned when the collection query is created by the client program.
///
///
/// The Execute method must be invoked by the client program before any data can be retrieved from the query object.
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctioninstancecollectionquery
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionInstanceCollectionQuery")]
[ComImport, Guid("57cc6fd2-c09a-4289-bb72-25f04142058e"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IFunctionInstanceCollectionQuery
{
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// The AddQueryConstraint method adds a query constraint to the query.
/// This method enables the application to filter the result set to only those instances that fulfill this constraint.
///
/// The query constraint.
/// The constraint value.
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
///
///
///
/// If multiple constraints are added, all constraints must be supported to satisfy the query.
///
/// AddQueryConstraint will fail with an error if the IFunctionInstanceCollectionQuery object includes all subcategories
/// and the AddQueryConstraint method is called with the pszConstraintName parameter set to
/// FD_QUERYCONSTRAINT_PROVIDERINSTANCEID. To avoid this error, create a IFunctionInstanceCollectionQuery object
/// that does not include all subcategories. You can create such an object by calling CreateInstanceCollectionQuery with the
/// fIncludeAllSubCategories parameter set to false.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollectionquery-addqueryconstraint
// HRESULT AddQueryConstraint( const WCHAR *pszConstraintName, const WCHAR *pszConstraintValue );
[PreserveSig]
HRESULT AddQueryConstraint([MarshalAs(UnmanagedType.LPWStr)] string pszConstraintName, [MarshalAs(UnmanagedType.LPWStr)] string pszConstraintValue);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Adds a property constraint to the query.
/// This method limits query results to only function instances with a property key (PKEY) matching the specified constraint.
///
/// The property key (PKEY) for the constraint. For more information about PKEYs, see Key Definitions.
///
/// A PROPVARIANT used for the constraint. This type must match the PROPVARIANT type associated with Key.
///
/// The following shows possible values. Note that only a subset of the PROPVARIANT types supported by the built-in providers
/// can be used as a property constraint.
///
/// VT_BOOL
/// VT_I2
/// VT_I4
/// VT_I8
/// VT_INT
/// VT_LPWSTR
/// VT_LPWSTR|VT_VECTOR
/// VT_UI2
/// VT_UI4
/// VT_UI8
/// VT_UINT
///
///
/// A PropertyConstraint value that specifies the type of comparison to use when comparing the constraint's PKEY to the function
/// instance's PKEY.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)
///
/// The constraint specified for the query is not supported. Either the constraint is not supported for a specific VARENUM type,
/// or the VARENUM type is not supported at all.
///
///
///
///
///
///
/// A function instance will only match a property constraint when the PROPVARIANT type of the function instance's PKEY matches
/// the PROPVARIANT type of the constraint's PKEY and the function instance's PKEY value matches the constraint's PKEY value
/// using the comparison operator specified by enumPropertyConstraint.
///
/// If multiple constraints are added, all constraints must be supported to satisfy the query.
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollectionquery-addpropertyconstraint
// HRESULT AddPropertyConstraint( REFPROPERTYKEY Key, const PROPVARIANT *pv, PropertyConstraint enumPropertyConstraint );
[PreserveSig]
HRESULT AddPropertyConstraint(in PROPERTYKEY Key, PROPVARIANT pv, PropertyConstraint enumPropertyConstraint);
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Performs the query defined by IFunctionDiscovery::CreateInstanceCollectionQuery.
///
///
/// A pointer to an IFunctionInstanceCollection interface pointer that receives the requested function instance collection.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
/// The method completed successfully. Results are returned synchronously in ppIFunctonInstanceCollecton.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// E_PENDING
/// Some of the results will be returned by asynchronous notification. See the remarks for details.
///
///
///
/// A predefined query is a query of a layered category. When a predefined query is executed, each provider that returns a
/// function instance also returns an HRESULT value. The provider HRESULT values are aggregated, and the value returned by the
/// Execute method reflects these aggregate results. Results are aggregated as follows:
///
///
/// -
/// If all providers return S_OK, Execute returns S_OK.
///
/// -
///
/// If at least one provider returns E_PENDING, and all other providers return either S_OK or E_PENDING,
/// Execute returns E_PENDING.
///
///
/// -
///
/// If all providers return an error value (that is, a value other than S_OK or E_PENDING), Execute returns
/// the error value returned by the network provider that was last queried. Also, if the client's IFunctionDiscoveryNotification
/// callback routine was provided to IFunctionDiscovery::CreateInstanceCollectionQuery, an OnError notification is sent for each
/// provider. Each OnError notification contains the HRESULT returned by the provider.
///
///
/// -
///
/// If at least one provider returns an error value, and all other providers return S_OK, Execute returns
/// S_OK. OnError notifications are sent as described above.
///
///
/// -
///
/// If at least one provider returns an error value, and at least one provider returns E_PENDING, Execute returns
/// E_PENDING. OnError notifications are sent as described above.
///
///
///
///
/// When Execute returns S_OK, ppIFunctionInstanceCollection contains the results of the query. If an
/// IFunctionDiscoveryNotification interface is provided to the CreateInstanceCollectionQuery method of IFunctionDiscovery, then
/// changes to the results will be communicated using that interface.
///
///
/// When Execute returns E_PENDING, the result set will be returned asynchronously through the
/// IFunctionDiscoveryNotification interface provided to the CreateInstanceCollectionQuery method of IFunctionDiscovery.
/// ppIFunctionInstanceCollection may be NULL or may contain a partial result set. The enumeration is complete once the
/// OnEvent method of IFunctionDiscoveryNotification is called with FD_EVENTID_SEARCHCOMPLETE. After the
/// FD_EVENTID_SEARCHCOMPLETE event is received, additional notifications are updates to the results.
///
///
///
///
/// This method must be must be invoked by the client program before any data can be retrieved from the query object. When
/// called, this method performs the following:
///
///
/// -
/// Retrieves the function instance collection object.
///
/// -
/// Queries the provider of the category that is passed into IFunctionDiscovery::CreateInstanceCollectionQuery.
///
/// -
/// Retrieves the category provider.
///
/// -
/// Queries the category provider using the subcategory data to generate the collection using query constraints.
///
/// -
///
/// Initiates the update notification mechanism if the address of the client program's IFunctionDiscoveryNotification callback
/// routine is provided to IFunctionDiscovery::CreateInstanceCollectionQuery.
///
///
/// -
/// Caches the collection data and returns.
///
///
///
/// Function Discovery network providers only return function instances through the IFunctionDiscoveryNotification interface.
/// They return no function instances directly when this method is invoked. Instead, Execute simply initiates an entirely
/// asynchronous retrieval operation and returns E_PENDING to indicate that the results will be returned asynchronously.
/// Notifications must be used to retrieve function instances from Function Discovery network providers.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancecollectionquery-execute
// HRESULT Execute( IFunctionInstanceCollection **ppIFunctionInstanceCollection );
[PreserveSig]
HRESULT Execute(out IFunctionInstanceCollection ppIFunctionInstanceCollection);
}
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
///
/// This interface implements the asynchronous query for a function instance based on category and subcategory. A pointer to this
/// interface is returned when the query is created by the client program.
///
///
/// The Execute method must be invoked by the client program before any data can be retrieved from the query object.
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nn-functiondiscoveryapi-ifunctioninstancequery
[PInvokeData("functiondiscoveryapi.h", MSDNShortId = "NN:functiondiscoveryapi.IFunctionInstanceQuery")]
[ComImport, Guid("6242bc6b-90ec-4b37-bb46-e229fd84ed95"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IFunctionInstanceQuery
{
///
///
/// [Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered
/// or unavailable in subsequent versions.]
///
/// Performs the query defined by IFunctionDiscovery::CreateInstanceQuery.
///
///
/// A pointer to an IFunctionInstance interface pointer that receives the requested function instance.
///
///
/// Possible return values include, but are not limited to, the following.
///
///
/// Return code/value
/// Description
///
/// -
/// S_OK
/// The method completed successfully.
///
/// -
/// E_INVALIDARG
/// The ppIFunctionInstance parameter is NULL.
///
/// -
/// E_OUTOFMEMORY
/// The method is unable to allocate the memory required to perform this operation.
///
/// -
/// E_PENDING
/// The results to be returned by a provider will come through asynchronous notification.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_OBJECT_NOT_FOUND) 0x800710d8
/// The function instance represented by the specified ID does not exist on this computer.
///
/// -
/// HRESULT_FROM_WIN32(ERROR_KEY_DELETED) 0x800703fa
///
/// The function instance could not be returned because the key corresponding to the function instance was deleted by another
/// process. This error is returned by the registry provider if a key is deleted while query processing is taking place.
///
///
/// -
/// HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002
///
/// The function instance could not be returned because the key corresponding to the function instance could not be found. This
/// error is returned by the registry provider when the provider could not find matching instances for an instance query.
///
///
///
///
/// A predefined query is a query of a layered category. When a predefined query is executed, each provider that returns a
/// function instance also returns an HRESULT value. The provider HRESULT values are aggregated, and the value returned by the
/// Execute method reflects these aggregate results. Results are aggregated as follows:
///
///
/// -
/// If all providers return S_OK, Execute returns S_OK.
///
/// -
///
/// If at least one provider returns E_PENDING, and all other providers return either S_OK or E_PENDING, Execute returns E_PENDING.
///
///
/// -
///
/// If all providers return an error value (that is, a value other than S_OK or E_PENDING), Execute returns the error value
/// returned by the network provider that was last queried. Also, if the client's IFunctionDiscoveryNotification callback
/// routine was provided to IFunctionDiscovery::CreateInstanceCollectionQuery, an OnError notification is sent for each
/// provider. Each OnError notification contains the HRESULT returned by the provider.
///
///
/// -
///
/// If at least one provider returns an error value, and all other providers return S_OK, Execute returns S_OK. OnError
/// notification(s) are sent as described above.
///
///
/// -
///
/// If at least one provider returns an error value, and at least one provider returns E_PENDING, Execute returns E_PENDING.
/// OnError notification(s) are sent as described above.
///
///
///
///
///
///
/// This method must be must be invoked by the client program to retrieve data from the query object. When called, this method
/// performs the following:
///
///
/// -
/// Retrieves the function instance.
///
/// -
///
/// Initiates the update notification mechanism if the address of the client program's IFunctionDiscoveryNotification callback
/// routine is provided to IFunctionDiscovery::CreateInstanceQuery.
///
///
///
///
/// Function Discovery network providers only return function instances through the IFunctionDiscoveryNotification interface.
/// They return no function instances directly when this method is invoked. Instead, Execute simply initiates an entirely
/// asynchronous retrieval operation and returns E_PENDING to indicate that the results will be returned asynchronously.
/// Notifications must be used to retrieve function instances from Function Discovery network providers.
///
///
/// If Execute is called twice on the same query object, the first query is terminated before the second query executes.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/functiondiscoveryapi/nf-functiondiscoveryapi-ifunctioninstancequery-execute
// HRESULT Execute( IFunctionInstance **ppIFunctionInstance );
[PreserveSig]
HRESULT Execute(out IFunctionInstance ppIFunctionInstance);
}
/// CLSID_FunctionDiscovery
[PInvokeData("functiondiscoveryapi.h")]
[ComImport, Guid("C72BE2EC-8E90-452c-B29A-AB8FF1C071FC"), ClassInterface(ClassInterfaceType.None)]
public class FunctionDiscovery { }
/// CLSID_FunctionInstanceCollection
[PInvokeData("functiondiscoveryapi.h")]
[ComImport, Guid("ba818ce5-b55f-443f-ad39-2fe89be6191f"), ClassInterface(ClassInterfaceType.None)]
public class FunctionInstanceCollection { }
}
}