The IoRegisterDeviceInterface routine registers a device interface class, if it has not been previously registered, and creates a new instance of the interface class, which a driver can subsequently enable for use by applications or other system components.

NTSTATUS 
  IoRegisterDeviceInterface(
    IN PDEVICE_OBJECT  PhysicalDeviceObject,
    IN CONST GUID  *InterfaceClassGuid,
    IN PUNICODE_STRING  ReferenceString  OPTIONAL,
    OUT PUNICODE_STRING  SymbolicLinkName
    );

Parameters

PhysicalDeviceObject

Pointer to the PDO for the device.

InterfaceClassGuid

Pointer to the class GUID that identifies the functionality (the device interface class) being registered.

ReferenceString

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

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 systems.

SymbolicLinkName

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.

The caller must treat SymbolicLinkName as opaque and must not disassemble it.

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

Return Value

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

Comments

IoRegisterDeviceInterface registers a device interface class, if it as not been previously registered, and creates a new instances 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 its AddDevice 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 using IoOpenDeviceInterfaceRegistryKey.

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 in SymbolicLinkName and 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.

Requirements

IRQL: PASSIVE_LEVEL (see Comments section)

Headers: Declared in Wdm.h. Include Wdm.h, Ntddk.h, or Ntifs.h.

See Also

IoGetDeviceInterfaces, IoOpenDeviceInterfaceRegistryKey, IoSetDeviceinterfaceState, RtlFreeUnicodeString