|
|
Add a filter into the query specification builder.
Both Object IDs and Interface IDs can be added as a group into the query. If Object IDs are specified, the match is restricted to only that list of Objects. If Interface IDs are specified, the match is restricted to Objects that provide ALL of the specified Interfaces (Objects that have only a subset, or none, of the specified Interfaces will not match). An empty list (either Objects or Interfaces) is like a wildcard, where everything matches. This gives four options:
- No Objects, No Interfaces: Match all available Objects and Interfaces. This is the simplest filter, but may cause a query operation to show many unwanted Objects and/or Interfaces.
- n Objects, No Interfaces: Match any of the specified Objects, no matter what Interfaces they provide. If the set of Objects that are desired are already known, this is a quick way to learn of the available Objects in the system.
- No Objects, m Interfaces: Match any Objects that have ALL of the specified Interfaces. This is an easy way to find particular types of Objects (ones that provide a known set of Interfaces), but whose Object IDs are not known.
- n Objects, m Interfaces: Match any of the specified Objects, but only if they have ALL of the specified Interfaces. This is the most restrictive filter.
To add disjoint sets of filters (for example, "All Objects that provide I1
and I2 AND all Objects that provide I3 and I4", these must be added to the query as two separate filters (using two calls to this function).
- Note
- If an Object matches the query, then ALL Interfaces for that Object are disclosed, even if they are not explicitly listed in the query. This can significantly increase the number of unwanted Interfaces that are disclosed. Consider using the DOFQueryBuilder_AddRestriction method to restrict the system to only notify of Interfaces that the application desires.
- Parameters
-
| self | The QueryBuilder. If NULL, no action is taken. |
| objectIDCount | Number of Object IDs. |
| objectIDs | List of Object IDs. This must not be NULL if objectIDCount > 0, and should not contain NULL or the broadcast or multicast IDs. |
| interfaceIDCount | Number of Interface IDs. |
| interfaceIDs | List of Interface IDs. This must not be NULL if interfaceIDCount > 0, and should not contain NULL or the wildcard ID. |
- Return values
-
| Non-Zero | (TRUE) The filter was added. |
- Exceptions
-
| Zero | (FALSE) The filter could not be added. |
|
