Retrieving All Function Instances in a Category
The following topic describes how to retrieve function instances using Function Discovery APIs.
To get a collection of function instances, use the IFunctionDiscovery::GetInstanceCollection method. To get a specified function instance and its index from the collection, use the IFunctionInstanceCollection::Get method. To get each function instance in the collection in order, use the IFunctionInstanceCollection::Item method.
If the GetInstanceCollection method succeeds but no function instances were found that matched the query parameters, then GetInstanceCollection returns S_OK, ppFunctionInstanceCollection points to an empty collection, and the collection's GetCount method returns 0.
Note Function Discovery network providers, such as the SSDP Provider, the WSD Provider, only return instances through the IFunctionDiscoveryNotification interface.
The following code snippet demonstrates how to get an instance from the collection using the IFunctionInstanceCollection::Item method. Implement the DisplayInstance function to display the returned function instance.
IFunctionDiscovery *pIFunDisc; IFunctionInstanceCollectionQuery *pIFunInstCollectionQuery; IFunctionInstanceCollection *pIFunInstCollection; IFunctionInstance *pIFunInst; BSTR _bstrCategory, _bstrSubCategory; BOOL bRecursive; DWORD dwCount; // some initialization code omitted here for brevity if ( S_OK == hr ) { hr = pIFunDisc->CreateInstanceCollectionQuery( _bstrCategory, _bstrSubCategory, bRecursive, NULL, NULL, &pIFunInstCollectionQuery ); if ( S_OK == hr ) { hr = pIFunInstCollectionQuery->Execute( &pIFunInstCollection ); if ( S_OK == hr ) { hr = pIFunInstCollection->GetCount( &dwCount ); for ( DWORD dwItem = 0; S_OK == hr && dwItem < dwCount; dwItem++ ) { hr = pIFunInstCollection->Item( dwItem, &pIFunInst ); if ( S_OK == hr ) { hr = DisplayInstance( pIFunInst ); // Implement DisplayInstance before using this sample code. pIFunInst->Release(); } } pIFunInstCollection->Release(); } pIFunInstCollectionQuery->Release(); } } // cleanup code omitted here for brevity
The IFunctionInstanceQuery interface implements the asynchronous query for a function instance based on category and subcategory. It is returned when IFunctionDiscovery::CreateInstanceQuery is invoked by the client program. Set interface constraints using IFunctionInstanceCollectionQuery to filter on multiple interfaces at one time.
Note The IFunctionInstanceCollectionQuery::Execute method must be invoked by the client program before any data can be retrieved from the query object.
Send comments about this topic to Microsoft
Build date: 2/3/2012
