IoRegisterDeviceInterface IoSetDeviceInterfaceState routine

 

 

 

一、IoRegisterDeviceInterface

如果它之前没有被注册，那么IoRegisterDeviceInterface注册一个设备接口类，且创建一个此接口类的实例，这样驱动能被应用程序或其它系统组件按顺序使用能。

NTSTATUS IoRegisterDeviceInterface(
  __in      PDEVICE_OBJECT PhysicalDeviceObject,
  __in      const GUID *InterfaceClassGuid,
  __in_opt  PUNICODE_STRING ReferenceString,
  __out     PUNICODE_STRING SymbolicLinkName
);

IoRegisterDeviceInterface的第一个参数必须是设备PDO的地址。第二个参数指出与接口关联的GUID，第三个参数指出额外的接口细分类名。只有Microsoft的代码才使用名称细分类方案。第四个参数是一个UNICODE_STRING串的地址，该串用于接收设备对象的符号连接名。

参数：

PhysicalDeviceObject [in]

一个指向设备FDO的指针。

InterfaceClassGuid [in]

一个指向GUID的指针，它表示了注册的功能（设备接口类）。

ReferenceString [in, optional]

Optionally points to a UNICODE_STRING. The string must not contain any path separator characters ("/" or "\"). Function drivers typically specifyNULL for this parameter. Filter drivers must specifyNULL.

Reference strings are only used by a few bus drivers, such as swenum, which is a bus driver that uses device interface instances as placeholders for software devices created on demand. When an instance of an interface is opened, the I/O manager passes the instance's reference string to the driver. The string becomes part of the interface instance's name (as an appended path component). The driver can then use the reference string to differentiate between two interface instances of the same class for a single device.

On Microsoft Windows 98/Me systems, the ReferenceString value can be no longer than MAX_PATH characters. There is no length limit on Windows 2000 and later versions of Windows.

SymbolicLinkName [ out ]

A pointer to a Unicode string structure allocated by the caller. If this routine is successful, it initializes the Unicode string and allocates the string buffer containing the kernel-mode path to the symbolic link for an instance of the specified device interface class.

调用者必须把SymboliLinkName看作为一个不透明的，且不能拆开它。

The caller is responsible for freeing SymbolicLinkName with RtlFreeUnicodeString when it is no longer needed.

IoRegisterDeviceInterface的返回值是一个Unicode串，这样在不知道驱动程序编码的情况下，应用程序能用该串确定并打开设备句柄。顺便说一下，这个名字比较丑陋；后面例子是我在Windows 98中为Sample设备生成的名字：\DosDevices\0000000000000007#{CAF53C68-A94C-11d2-BB4A-00C04FA330A6}。

 

Return value

IoRegisterDeviceInterface returns STATUS_SUCCESS if the call was successful. Possible error return values include the following.

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	The parameters are invalid. Possibilities include that PhysicalDeviceObject does not point to a valid PDO, or that theReferenceString string contains an invalid character.

 

Remarks

IoRegisterDeviceInterface registers a device interface class, if it has not been previously registered, and creates a new instance of the interface class. A driver can call this routine several times for a given device to register several interface classes and create instances of the classes. A function or filter driver typically registers device interfaces in itsAddDevice routine. For example, a fault-tolerant volume driver might register an instance of a fault-tolerant-volume interface and an instance of a volume interface for a particular volume.

If the device interface class has not been registered previously, the I/O manager creates a registry key for it, along with instance-specific persistent storage under the key. Drivers can access this persistent storage usingIoOpenDeviceInterfaceRegistryKey.

A driver registers an interface instance once and then calls IoSetDeviceInterfaceState to enable and disable the interface.

Registered interfaces persist across operating system reboots. If the specified interface is already registered, the I/O manager passes its name inSymbolicLinkNameand returns the informational success status STATUS_OBJECT_NAME_EXISTS.

Most drivers use a NULL reference string for a device interface instance. If a driver uses a non-NULL reference string, it must do additional work, including possibly managing its own namespace and security. A filter driver that exposes a device interface must use a NULL ReferenceString to avoid conflicts with other drivers in the device stack.

Callers of this routine are not required to remove the registration for a device interface when it is no longer needed. Device interface registrations can be removed from user mode, if necessary.

Callers of IoRegisterDeviceInterface must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

 

二、IoSetDeviceInterfaceState routine

IoSetDeviceInterfaceState使能或禁用一个之前注册过的设备接口类的实例。

NTSTATUS IoSetDeviceInterfaceState(
  __in  PUNICODE_STRING SymbolicLinkName,
  __in  BOOLEAN Enable
);

 

Parameters

SymbolicLinkName [in]

Pointer to a string that identifies the device interface instance that is being enabled or disabled. This string was obtained from a previous call to IoRegisterDeviceInterface or IoGetDeviceInterfaces.

Enable [in]

TRUE indicates that the device interface is being enabled. FALSE indicates that the device interface is being disabled.

Return value

IoSetDeviceInterfaceState returns STATUS_SUCCESS if the call was successful. This routine returns an informational status of STATUS_OBJECT_NAME_EXISTS if the caller requested to enable a device interface that was already enabled. Possible error return values are described following.

Return code	Description
STATUS_OBJECT_NAME_NOT_FOUND	The caller tried to disable a device interface that was not enabled.

 

Remarks

IoSetDeviceInterfaceState enables an instance of a registered device interface for use by applications and other system components. The interface class must have been previously registered with IoRegisterDeviceInterface or from user mode.

Applications and other system components can open only interfaces that are enabled.

A function or a filter driver typically calls this routine with Enable set to TRUE after it successfully starts a device in response to an IRP_MN_START_DEVICE IRP. Such a driver should disable the device interface instance (that is, call IoSetDeviceInterfaceState and set Enable to FALSE) when it removes the device in response to an IRP_MN_REMOVE_DEVICE IRP or an IRP_MN_SURPRISE_REMOVAL IRP. If a driver does not disable a device interface when it processes these removal IRPs, the driver should not subsequently attempt to do so because the PnP manager will disable the interface when the PnP manager removes the device.

If a device is removed suddenly (for example, by a surprise removal) but still has a valid device interface instance, a problem will occur if the device is reattached. This problem occurs when the PnP manager enumerates the newly attached device and enables a device interface instance, which will exist at the same registry path as the existing device interface instance.

Note that if the driver calls IoRegisterDeviceInterface to disable a device interface instance in response to an IRP_MN_SURPRISE_REMOVAL IRP, the driver must not attempt to disable the same device interface instance in response to an IRP_MN_REMOVE_DEVICE IRP.

If a call to IoSetDeviceInterfaceState successfully exposes a device interface instance, the system notifies any components that registered for PnP notification of a device class change. Similarly, if a call to this routine disables an existing device interface instance, the system sends appropriate notifications.

The PnP manager does not send notification of interface instance arrivals until the IRP_MN_START_DEVICE IRP completes, indicating that all the drivers for the device have completed their start operations. In addition, the PnP manager fails create requests for the device until the IRP_MN_START_DEVICE IRP completes.

Callers of IoSetDeviceInterfaceState must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.