Build a device selector
A device selector lets you limit the devices to search through when enumerating devices, which helps you get more relevant results and improve the performance of the system.
In most scenarios you get a device selector from a device stack. For example, you might use GetDeviceSelector for devices discovered over USB. These device selectors return an Advanced Query Syntax (AQS) string. For more details on the AQS format, see Using Advanced Query Syntax Programmatically.
Important APIs
Building the filter string
There are some cases where you need to enumerate devices and a provided device selector is not available for your scenario. A device selector is an AQS filter string that contains the following information. Before creating a filter string, you need to know some key pieces of information about the devices you want to enumerate.
- The DeviceInformationKind of the devices you are interested in. For more information about how DeviceInformationKind impacts enumerating devices, see Enumerate devices.
- How to build an AQS filter string (explained in this topic).
- The properties you are interested in. The available properties will depend upon the DeviceInformationKind. See Device information properties for more information.
- The protocols you are querying over. This is only needed if you are searching for devices over a wireless or wired network. For more information about doing this, see Enumerate devices over a network.
When using the Windows.Devices.Enumeration APIs, you frequently combine the device selector with the device kind that you are interested in. The available list of device kinds is defined by the DeviceInformationKind enumeration. This combination of factors helps you to limit the devices that are available to the ones that you are interested in. If you do not specify the DeviceInformationKind, or the method you are using does not provide a DeviceInformationKind parameter, the default kind is DeviceInterface.
The Windows.Devices.Enumeration APIs use canonical AQS syntax, but not all of the operators are supported. For a list of properties that are available when you are constructing your filter string, see Device information properties.
Caution
Custom properties that are defined using the {GUID} PID format cannot be used when constructing your AQS filter string. This is because the property type is derived from the well-known property name.
The following table lists the AQS operators and what types of parameters they support.
| Operator | Supported types |
|---|---|
| COP_EQUAL | String, boolean, GUID, UInt16, UInt32 |
| COP_NOTEQUAL | String, boolean, GUID, UInt16, UInt32 |
| COP_LESSTHAN | UInt16, UInt32 |
| COP_GREATERTHAN | UInt16, UInt32 |
| COP_LESSTHANOREQUAL | UInt16, UInt32 |
| COP_GREATERTHANOREQUAL | UInt16, UInt32 |
| COP_VALUE_CONTAINS | String, string array, boolean array, GUID array, UInt16 array, UInt32 array |
| COP_VALUE_NOTCONTAINS | String, string array, boolean array, GUID array, UInt16 array, UInt32 array |
| COP_VALUE_STARTSWITH | String |
| COP_VALUE_ENDSWITH | String |
| COP_DOSWILDCARDS | Not supported |
| COP_WORD_EQUAL | Not supported |
| COP_WORD_STARTSWITH | Not supported |
| COP_APPLICATION_SPECIFIC | Not supported |
You can specify NULL for COP_EQUAL or COP_NOTEQUAL. This translates to a property with no value, or that the value does not exist. In AQS, you specify NULL by using empty brackets [].
Important
When using the COP_VALUE_CONTAINS and COP_VALUE_NOTCONTAINS operators, they behave differently with strings and string arrays. In the case of a string, the system will perform a case-insensitive search to see if the device contains the indicated string as a substring. In the case of a string array, substrings are not searched. With the string array, the array is searched to see if it contains the entire specified string. It is not possible to search a string array to see if the elements in the array contain a substring.
If you cannot create a single AQS filter string that will scope your results appropriately, you can filter your results after you receive them. However, we recommend limiting the results from your initial AQS filter string as much as possible when you provide it to the Windows.Devices.Enumeration APIs. This will help improve the performance of your application.
AQS string examples
The following examples demonstrate how the AQS syntax can be used to limit the devices you want to enumerate. All of these filter strings are paired up with a DeviceInformationKind to create a complete filter. If no kind is specified, remember that the default kind is DeviceInterface.
When this filter is paired with a DeviceInformationKind of DeviceInterface, it enumerates all objects that contain the Audio Capture interface class and that are currently enabled. = translates to COP_EQUALS.
System.Devices.InterfaceClassGuid:="{2eef81be-33fa-4800-9670-1cd474972c3f}" AND
System.Devices.InterfaceEnabled:=System.StructuredQueryType.Boolean#True
When this filter is paired with a DeviceInformationKind of Device, it enumerates all objects that have at least one hardware id of GenCdRom. ~~ translates to COP_VALUE_CONTAINS.
System.Devices.HardwareIds:~~"GenCdRom"
When this filter is paired with a DeviceInformationKind of DeviceContainer, it enumerates all objects that have a model name containing the substring Microsoft. ~~ translates to COP_VALUE_CONTAINS.
System.Devices.ModelName:~~"Microsoft"
When this filter is paired with a DeviceInformationKind of DeviceInterface, it enumerates all objects that have a name starting with the substring Microsoft. ~< translates to COP_STARTSWITH.
System.ItemNameDisplay:~<"Microsoft"
When this filter is paired with a DeviceInformationKind of Device, it enumerates all objects that have a System.Devices.IpAddress property set. <>[] translates to COP_NOTEQUALS combined with a NULL value.
System.Devices.IpAddress:<>[]
When this filter is paired with a DeviceInformationKind of Device, it enumerates all objects that do not have a System.Devices.IpAddress property set. =[] translates to COP_EQUALS combined with a NULL value.
System.Devices.IpAddress:=[]