IFunctionDiscovery::GetInstanceCollection-Methode (functiondiscoveryapi.h)

[Die Funktionsermittlung ist für die Verwendung in den im Abschnitt Anforderungen angegebenen Betriebssystemen verfügbar. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.]

Ruft die angegebene Auflistung von Funktionsinstanzen basierend auf Kategorie und Unterkategorie ab.

Syntax

HRESULT GetInstanceCollection(
  [in]  const WCHAR                 *pszCategory,
  [in]  const WCHAR                 *pszSubCategory,
  [in]  BOOL                        fIncludeAllSubCategories,
  [out] IFunctionInstanceCollection **ppIFunctionInstanceCollection
);

Parameter

[in] pszCategory

Der Bezeichner der aufzuzählenden Kategorie. Weitere Informationen finden Sie unter Kategoriedefinitionen.

[in] pszSubCategory

Der Bezeichner der zu enumerierten Unterkategorie. Weitere Informationen finden Sie unter Unterkategoriedefinitionen. Dieser Parameter kann NULL sein.

[in] fIncludeAllSubCategories

Wenn TRUE, listet diese Methode rekursiv alle Unterkategorien der in pszCategory angegebenen Kategorie auf und gibt eine Auflistung zurück, die Funktionsinstanzen aus allen Unterkategorien von pszCategory enthält.

Wenn FALSE, beschränkt sich diese Methode auf die Rückgabe von Funktionsinstanzen in der kategorie, die von pszCategory und der von pszSubCategory angegebenen Unterkategorie angegeben wird.

[out] ppIFunctionInstanceCollection

Ein Zeiger auf einen IFunctionInstanceCollection-Schnittstellenzeiger, der die Funktion instance Auflistung empfängt, die die angeforderten Funktionsinstanzen enthält. Die Auflistung ist leer, wenn keine qualifizierenden Funktionsinstanzen gefunden werden.

Rückgabewert

Mögliche Rückgabewerte sind u. a. die folgenden:

Rückgabecode/-wert	BESCHREIBUNG
S_OK	Die Methode wurde erfolgreich abgeschlossen.
E_INVALIDARG	Der Wert von pszCategory ist ungültig. Der im ppIFunctionInstanceCollection-Parameter zurückgegebene Wert ist NULL.
E_OUTOFMEMORY	Die -Methode kann den für diesen Vorgang erforderlichen Arbeitsspeicher nicht zuordnen.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	Der Wert von pszCategory oder pszSubCategory ist unbekannt.
E_PENDING	Der Aufruf wurde für einen Anbieter ausgeführt, der asynchron Ergebnisse zurückgibt.

Hinweise

Einige Funktionsermittlungsanbieter geben ihre Abfrageergebnisse mit der IFunctionDiscoveryNotification-Schnittstelle zurück. GetInstanceCollection findet keine Funktionsinstanzen, die auf diese Weise zurückgegeben werden, und schlägt mit E_PENDING fehl. Es wird empfohlen, dass Clients die CreateInstanceQuery-Methode der IFunctionDiscovery-Schnittstelle verwenden, um Funktionsinstanzen für solche Anbieter zu finden.

Wenn die Methode erfolgreich ist, aber keine Funktionsinstanzen gefunden wurden, die den Abfrageparametern entsprechen, wird S_OK zurückgegeben, und ppFunctionInstanceCollection verweist auf eine leere Auflistung (die GetCount-Methode der Auflistung gibt 0 zurück).

Unterkategorieabfragen werden nur für mehrstufige Kategorien und einige Anbieterkategorien unterstützt. Der Registrierungsanbieter, der PnP-X-Zuordnungsanbieter und der Veröffentlichungsanbieter unterstützen Unterkategorieabfragen. Benutzerdefinierte Anbieter können explizit für die Unterstützung von Unterkategorieabfragen entworfen werden. Bei anderen Anbietern können Funktions- instance-Auflistungen mithilfe von Abfrageeinschränkungen gefiltert werden. Eine Liste der Abfrageeinschränkungen finden Sie unter Einschränkungsdefinitionen.

Beispiele

Der folgende Code gibt die Funktionsinstanzen zurück, die dem SSDP-Anbieter im Microsoft.Networking.Devices-Namespace zugeordnet sind.

hr = spDisco->GetInstanceCollection(FCTN_CATEGORY_NETWORKDEVICES,
                                   FCTN_SUBCAT_NETWORKDEVICES_SSDP, 
                                   FALSE, 
                                   &spFunctionInstanceCollection);

Informationen zum gleichzeitigen Filtern nach mehreren Schnittstellen oder zum Filtern nach Anbietern, die keine Unterkategorieabfragen unterstützen, finden Sie unter Schnittstelleneinschränkungen für IFunctionInstanceQuery .

Anforderungen

Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	functiondiscoveryapi.h
DLL	FunDisc.dll

Weitere Informationen

IFunctionDiscovery