Edit

Build a device selector

  • Article

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.

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:=[]

See Also