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 { } } }