[This is preliminary documentation and subject to change.]
The COM objects described in this document allow device query and management using any COM aware language, for example, Visual Basic, VBScript and JScript.
Right-click on "devcon.inf" and click "install". The COM objects will be installed and made available for use. The following document describes the objects available and samples on how to use them in context of VBScript.
Root object that can be created via CreateObject either locally or remote.
RebootRequired (Get/Set)
This property is set if any derived objects indicate a reboot is required.
AllDevices([flags],[machine])
Returns a Devices collection of all devices for local or specified machine. Flags include 1 (Include not-present devices), 2 (In context of current hardware profile rather than globally).
DevicesBySetupClasses(classList,[flags],[machine])
Returns a Devices collection of all devices of the specified setup classes, otherwise similar to AllDevices. The classes may either be GUID's in string form or class names. ClassList may be either a single string, a collection of strings or an array of strings.
DevicesByInterfaceClasses(classList,[flags],[machine])
Returns a Devices collection of all devices that currently support any of the specified interface classes. Interface classes must be specified as GUID's in string form. Classlist may be either a single string, a collection of strings or an array of strings.
DevicesByInstanceIds(idList,[machine])
Same as CreateEmptyDeviceList followed by an "Add" on that device list.
SetupClasses([classList],[machine])
Create a SetupClasses collection from the specified classlist. Classlist may be either a single string, a collection of strings or an array of strings. If classlist is omitted or is "", all classes for local/specified machine is returned.
CreateEmptyDeviceList([machine])
Create a Devices collection that contains no devices for specified machine. Creating the collection object this way (or by any of the other methods in this object) associates the collection with this object and allows child objects to be associated with this object. Creating the collection object directly will not associate it with this object or a machine.
CreateEmptySetupClassList([machine])
Create a SetupClasses collection that contains no setup classes for specified machine. Creating the collection object this way (or by any of the other methods in this object) associates the collection with this object and allows child objects to be associated with this object. Creating the collection object directly will not associate it with this object or a machine.
UpdateDriver(scriptName,hardwareId,[flags])
Updates all devices that have specified hardwareId with best driver in either specified script or system scripts (currently only INF files are supported). A failure must be caught with appropriate error handling. Reboot status can be checked via RebootRequired property. Appropriate permissions are required.
CheckReboot
Prompts user for reboot if one is required. Reboots machine if user says ok, otherwise returns. Appropriate permissions are required.
RebootReasonHardware
Unconditionally reboots the machine logging the reason as planned "hardware". Appropriate permissions are required.
AttachEvent(event,handler)
Attach an event handler for the specified event. This function returns 'true' to indicate success. currently no other value is returned. Handler is a function pointer. If multiple handlers are specified, there is no guarantee on order of execution. In VBScript, the handler parameter must be obtained using "getRef". The following events are currently defined:
Event name Parameters Action OnDeviceNodesChanged none Indicates a device change (inserted/deleted/started/stopped) akin to DBT_DEVNODES_CHANGED.
DetachEvent(event,handler)
Detach event handler previously attached by AttachEvent. Handler and event must be exactly the same as that specified in AttachEvent.
Root object that can be created via CreateObject, also may be returned by methods/properties. Provides a dynamic collection of strings. This dynamic collection may be enumerated and/or indexed. Default method is "Item".
CaseSensative (Get/Set)
Normally the strings collection is lenient on case when indexing by string or when finding strings. Leniency may be changed using this property. All strings are stored case sensitive.
Count (Get)
Number of items in the collection. The Collection is indexed 1..Count inclusive.
Item([index/value]) (Default)
If no index specified, a snapshot of the collection is returned as a 1-based array, otherwise the indexed string is returned. Either a numerical or string index may be specified.
Add(items)
A string, collection of strings or array of strings may be added to the collection. Multi-dimension arrays are flattened.
Insert(index/value,items)
A string, collection of strings or array of strings may be inserted before the specified index (which may be a string in the collection or a numeric index).
Remove(index/value)
Remove a string either by numeric index or by value.
Find(value)
Returns index of string if it exists, otherwise 0.
Root object that can be created via CreateObject (although creation via DeviceConsole is preferred). Provides a dynamic collection of setup classes. This dynamic collection may be enumerated and/or indexed. Default method is "Item". This object may be associated with a machine and is typically associated with a DeviceConsole object.
Count (Get)
Returns number of SetupClass objects in the collection.
Item(index/guid) (Default)
Returns SetupClass object at specified index. Index is 1-based numeric, or the class GUID may be supplied.
Add(classNames)
Add one or more classes to the collection. If a single GUID string is specified, then only one SetupClass object will be added. If a class name is specified, it is possible for multiple SetupClass objects to be associated with the class name.
Remove(index/guid)
Remove a class from the collection.
Devices([flags])
Return Devices collection that contains the union of the devices of all the device classes specified in this collection.
A single object in the SetupClasses collection. Inherits any information associated with the SetupClasses collection it was derived from. Default property is "Guid".
Guid (Get, Default)
Returns class Guid.
Name (Get)
Returns simple name of the setup class.
Description (Get)
Returns class description.
Security (Get/Set)
Default device security for class in SDDL format. Setting it to null or nothing will delete setting. Not yet implemented.
DeviceTypeOverride (Set/Get)
Default device type for class (eg FILE_DEVICE_CDROM = 0x02). Setting it to null or nothing will delete setting. Not yet implemented.
ForceExclusive (Set/Get)
If TRUE, sets default to force all devices in the class to only be opened in exclusive mode. Setting it to null or nothing will delete setting. Not yet implemented.
CharacteristicsOverride (Get/Set)
Allows forcing (setting) of FILE_REMOVABLE_MEDIA (1) FILE_READ_ONLY_DEVICE (2) FILE_FLOPPY_DISKETTE (4) FILE_WRITE_ONCE_MEDIA (8) FILE_DEVICE_SECURE_OPEN (256)
If specified, sets default for the class. Setting it to null or nothing will delete setting. Not yet implemented.
Machine (Get)
Name of remote machine (usually prefixed by '\\').
Devices([flags])
Return Devices collection for devices of this specific setup class.
CreateEmptyDeviceList()
Creates an empty device list that is locked to this setup class. (That is, no devices can be added to it unless that device has the same setup class).
RegRead(keyPath)
If keyPath ends in "\" then read key's default value, otherwise read named value. Supports reading of REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ and REG_DWORD values.
RegWrite(keyPath,value,[type])
If keyPath ends in "\" then write key's default value, otherwise write named value. Supports writing of REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_DWORD and REG_BINARY values. If type is specified, it should be a string "REG_SZ", "REG_EXPAND_SZ", "REG_MULTI_SZ", "REG_DWORD" or "REG_BINARY" and explicitly indicates the type of value to be written. If not specified, type is determined from value (collections will be written as REG_MULTI_SZ, strings as REG_SZ, integers as REG_DWORD). If "REG_BINARY" is specified, value must be numeric.
RegDelete(keyPath)
Delete class specific value.
Root object that can be created via CreateObject (although creation via DeviceConsole or derived objects is preferred). Provides a dynamic collection of devices. This dynamic collection may be enumerated and/or indexed. This object may be associated with a machine and is typically associated with a DeviceConsole object. Default method is "Item".
Count (Get)
Returns number of Device objects in the collection.
Item(index/instanceId) (Default)
Return specified Device object. Index is 1-based.
Add(instanceId/instanceIdCollection)
Add one or more devices with specified instance ID's to this collection. This operation will fail if the specified device does not exist, or if the collection is locked to a specific setup class and the devi ce is of a different setup class.
Remove(index/instanceId)
Remove a device from collection. Index is 1-based. Does not delete the device itself.
CreateRootDevice([hardwareId])
Create a root-enumerated device and add to the collection. If the collection is locked to a specific setup class, the new device is associated with that setup class. The device will have the specified hardware id. Returns a Device object for the newly created device.
A single object representing a device. Usually associated with a DeviceConsole object and may be associated with a specific machine. Default property is "InstanceId"
InstanceId (Default,Get)
Instance Id of the device.
RebootRequired (Get/Set)
Indicates if this device requires a reboot to start. Setting this property will also set the RebootRequired property of the associated DeviceConsole object if any.
Description (Get)
Description of device as it would appear in device manager. If friendly name is available, that is returned instead.
HardwareIds (Get/Set)
Strings collection of all hardware Id's reported by the device. May be modified for root-enumerated devices. Setting it to null or nothing will delete it.
CompatibleIds (Get/Set)
Strings collection of all compatible Id's reported by the device. May be modified for root-enumerated devices. Setting it to null or nothing will delete it.
ServiceName (Get)
Name of FDO service.
Class (Get)
GUID of SetupClass that device is associated with.
Manufacturer (Get)
Name of manufacturer of device if known.
FriendlyName (Get/Set)
Friendly name of device. Setting it to null or nothing will delete it.
LocationInformation (Get/Set)
Informative information about where the device is located. Setting it to null or nothing will delete it.
UpperFilters (Get/Set)
Strings collection of all upper filter services. Setting it to null or nothing will delete it.
LowerFilters (Get/Set)
Strings collection of all lower filter services. Setting it to null or nothing will delete it.
EnumeratorName (Get)
Indicates bus enumerator type.
Security (Get/Set)
Device security in SDDL format. Setting it to null or nothing will delete it.
DeviceTypeOverride (Set/Get)
Allows device type to be specified (eg FILE_DEVICE_CDROM = 0x02). If specified overrides class settings. Setting it to null or nothing will delete it.
ForceExclusive (Set/Get)
If TRUE, forces the device to only be opened in exclusive mode. If specified, overrides class settings. Setting it to null or nothing will delete it.
CharacteristicsOverride (Get/Set)
Allows forcing (setting) of FILE_REMOVABLE_MEDIA (1) FILE_READ_ONLY_DEVICE (2) FILE_FLOPPY_DISKETTE (4) FILE_WRITE_ONCE_MEDIA (8) FILE_DEVICE_SECURE_OPEN (256)
If specified, overrides class settings. Setting it to null or nothing will delete it.
IsRunning (Get)
True if device is up and running.
IsDisabled (Get)
True if device is disabled.
HasProblem (Get)
True if device has any kind of problem.
ProblemCode (Get)
Non-zero problem code if available, otherwise 0 (including if the device has a private problem).
HasPrivateProblem (Get)
True if device has a private problem that no code is available for.
IsRootEnumerated (Get)
True if device is root enumerated.
IsDisableable (Get)
True if device can be disabled.
IsRemovable (Get)
True if device supports being removed while OS is running.
Machine (Get)
Name of remote machine (usually prefixed by '\\').
Delete
Delete (remove) the device. If successful, this object is invalid and the device is removed.
Enable
Enable the device. If reboot is required, it is reported through the RebootRequired property.
Disable
Disable the device. If reboot is required, it is reported through the RebootRequired property.
Start
Start a stopped device.
Stop
Stop a running device.
Restart
Stop and then Start a device (property-change). This may succeed in cases where Stop-Start would not.
HasInterface(interfaceClass)
Return true if the device supports the specified interface (and that interface is currently active).
RegRead(keyPath)
If keyPath is prefixed with "SW\" then read the devices software key. If it is prefixed with "HW\" then read the devices hardware key. If keyPath ends in "\" then read key's default value, otherwise read named value. Supports reading of REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ and REG_DWORD values.
RegWrite(keyPath,value,[type])
If keyPath is prefixed with "SW\" then write to the devices software key. If it is prefixed with "HW\" then write to the devices hardware key. If keyPath ends in "\" then write key's default value, otherwise write named value. Supports writing of REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_DWORD and REG_BINARY values. If type is specified, it should be a string "REG_SZ", "REG_EXPAND_SZ", "REG_MULTI_SZ", "REG_DWORD" or "REG_BINARY" and explicitly indicates the type of value to be written. If not specified, type is determined from value (collections will be written as REG_MULTI_SZ, strings as REG_SZ, integers as REG_DWORD). If "REG_BINARY" is specified, value must be numeric.
RegDelete(keyPath)
If keyPath is prefixed with "SW\" then delete the specified device software value. If it is prefixed with "HW\" then delete the specified device hardware value.
CurrentDriverPackage
Determine driver package that was used for device. Return a DriverPackage object or "nothing" if no driver package found for this device.
FindDriverPackages([pathList])
Obtain a DriverPackages collection of all viable drivers by searching system directories and specified pathList (string/collection/array) for driver packages. PathList may contain directories to search for installation scripts, or may specify installation scripts by name (currently only INF files). Sub-directories are not searched. An empty collection is returned if no compatible drivers were found. If a path list is specified, only those files/directories are searched unless one of the paths is "*" (search default paths).
A collection of Driver Packages for a specific device. This collection may be enumerated and/or indexed. This object is always associated with a device. Default method is "Item".
Count
Number of drivers.
Item([index])
Returns a specific DriverPackage object. Index is 1-based.
BestDriver
Returns best DriverPackage object for device.
Add([pathlist])
Add more drivers. Not implemented.
An individual driver package.
Description (Get)
Default description for the device. (Note that this may be different to DriverDescription).
Manufacturer (Get)
Manufacturer of the device.
Provider (Get)
Provider of the install script.
Date (Get)
Driver date (returned as a date/time type).
Version (Get)
Version of driver (returned as a string in format "a.b.c.d").
ScriptFile (Get)
Name of file that determines how driver is to be installed. Currently only INF files are supported.
ScriptName (Get)
In context of INF files, this is the decorated "DDInstall" section.
HardwareIds (Get)
Zero or more hardware ID's returned as a collection of strings. These are devices the package was designed for.
CompatibleIds (Get)
Zero or more compatible ID's returned as a collection of strings. These are devices the package will work with.
DriverDescription (Get)
A description of the driver (vs. the default description of the device).
Reject (Get/Set)
Mark the driver that it should not be considered when using "BestDriver" method in containing collection.
IsClassDriver (Get)
Indicates this is a class driver.
IsCompatibleDriver (Get)
Indicates this is a compatible driver.
DescriptionIsDuplicate (Get)
Indicates there is another driver with same description in the containing collection.
ProviderIsDuplicate (Get)
Indicates there is another driver with same provider in the containing collection.
ExcludeFromList (Get)
Exclude this driver when using (future) DisplayAndSelectDriver method on the containing collection.
FromInternet (Get)
Indicates this driver is from the internet.
NoDriver (Get)
No physical driver will be installed with this driver package.
OldDriver (Get)
Driver presently/previously controlled device.
OldInternetDriver (Get)
Driver was from internet but source files are no longer available.
Rank (Get/Set)
Obtains/modifies ranking of driver prior to searching using "BestDriver" method in containing collection. The value '0' indicates ideal driver. Values 0x8000-0xFFFF indicate an un-trusted driver.
DriverFiles
For an installed package, the files that are used by the driver. For other drivers, the files that would be used by the driver once installed.
Manifest
Source location of the files. Not implemented correctly, needs rethinking.
ActiveX control to display a device/class icon. Control is windowless and transparent.
ObtainIcon(deviceObject/classObject)
Pass in a device or class object. An appropriate icon will be displayed.
We welcome your comments, problem reports and wish-list requests. Please submit them by pointing your Internet browser to http://www.microsoft.com/ddk.
© Microsoft Corporation 2001