Retrieving All Function Instances in a Category

  • Article

[Function Discovery is available for use in the following versions of Windows: Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, and Windows Vista. It may be altered or unavailable in subsequent versions.]

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 &amp;&amp; dwItem < dwCount; dwItem++ )
            {
                hr = pIFunInstCollection->Item( dwItem, &amp;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.