Property Filtering

A PropertyCollector can have one or more associated PropertyFilter objects. A PropertyFilter object has one associated PropertyFilterSpec object.

Some differences apply when filtering properties for RetrievePropertiesEx or for WaitForUpdatesEx.

When you call RetrievePropertiesEx, you supply a specSet parameter that can specify more than one PropertyFilterSpec. When you call CreateFilter you can specify only one PropertyFilterSpec.

A call to CreateFilter creates a persistent server-side filter belonging to the PropertyCollector. These filters are for use with successive calls to WaitForUpdatesEx, made for the same PropertyCollector instance. A call to RetrievePropertiesEx creates a set of nonpersistent filters that the server uses to select properties for the RetrievePropertiesEx call and for any associated ContinueRetrievePropertesEx calls made with the returned token.

To create persistent property filter specifications, use the CreateFilter method. When you call CreateFilter, you pass a PropertyFilterSpec object to the method. The method adds the new filter to the PropertyCollector associated with the method invocation and returns a reference to the new filter. After you have created the filter, you can add additional PropertyFilterSpec objects. You cannot share a filter with a PropertyCollector in another session.

A RetrievePropertiesEx call returns a change set consisting of the union of results for all the filter specifications in the specSet parameter of the call. A WaitForUpdatesEx call returns a change set consisting of individual results, one result set for each persistent PropertyFilter attached to the PropertyCollector.

You can call WaitForUpdatesEx when the PropertyCollector has no PropertyFilter objects, but the call will block until you create a filter or until the call times out.