[AUDIT] + [FORMATTING]

- Coding style applied (make file's header proper, add headers for every function)
- All functions except one are documented in MSDN
- One undocumented function will undergo further examination and documentation

svn path=/trunk/; revision=22948

reactos/ntoskrnl/io/iomgr/deviface.c

@@ -1,7 +1,7 @@
 /*
- * COPYRIGHT:       See COPYING in the top level directory
+ * PROJECT:         ReactOS Kernel
- * PROJECT:         ReactOS kernel
+ * LICENSE:         GPL - See COPYING in the top level directory
- * FILE:            ntoskrnl/io/deviface.c
+ * FILE:            ntoskrnl/io/iomgr/deviface.c
  * PURPOSE:         Device interface functions
  *
  * PROGRAMMERS:     Filip Navara (xnavara@volny.cz)
@@ -20,35 +20,92 @@
 
 static PWCHAR BaseKeyString = L"\\Registry\\Machine\\System\\CurrentControlSet\\Control\\DeviceClasses\\";
 
-/*
+/*++
+ * @name IoOpenDeviceInterfaceRegistryKey
  * @unimplemented
- */
+ *
-
+ * Provides a handle to the device's interface instance registry key.
-NTSTATUS STDCALL
+ * Documented in WDK.
-IoOpenDeviceInterfaceRegistryKey(
+ *
-   IN PUNICODE_STRING SymbolicLinkName,
+ * @param SymbolicLinkName
+ *        Pointer to a string which identifies the device interface instance
+ *
+ * @param DesiredAccess
+ *        Desired ACCESS_MASK used to access the key (like KEY_READ,
+ *        KEY_WRITE, etc)
+ *
+ * @param DeviceInterfaceKey
+ *        If a call has been succesfull, a handle to the registry key
+ *        will be stored there
+ *
+ * @return Three different NTSTATUS values in case of errors, and STATUS_SUCCESS
+ *         otherwise (see WDK for details)
+ *
+ * @remarks Must be called at IRQL = PASSIVE_LEVEL in the context of a system thread
+ *
+ *--*/
+NTSTATUS
+NTAPI
+IoOpenDeviceInterfaceRegistryKey(IN PUNICODE_STRING SymbolicLinkName,
                                  IN ACCESS_MASK DesiredAccess,
                                  OUT PHANDLE DeviceInterfaceKey)
 {
     return STATUS_NOT_IMPLEMENTED;
 }
 
-/*
+/*++
+ * @name IoGetDeviceInterfaceAlias
  * @unimplemented
- */
+ *
-
+ * Returns the alias device interface of the specified device interface
-NTSTATUS STDCALL
+ * instance, if the alias exists.
-IoGetDeviceInterfaceAlias(
+ * Documented in WDK.
-   IN PUNICODE_STRING SymbolicLinkName,
+ *
+ * @param SymbolicLinkName
+ *        Pointer to a string which identifies the device interface instance
+ *
+ * @param AliasInterfaceClassGuid
+ *        See WDK
+ *
+ * @param AliasSymbolicLinkName
+ *        See WDK
+ *
+ * @return Three different NTSTATUS values in case of errors, and STATUS_SUCCESS
+ *         otherwise (see WDK for details)
+ *
+ * @remarks Must be called at IRQL = PASSIVE_LEVEL in the context of a system thread
+ *
+ *--*/
+NTSTATUS
+NTAPI
+IoGetDeviceInterfaceAlias(IN PUNICODE_STRING SymbolicLinkName,
                           IN CONST GUID *AliasInterfaceClassGuid,
                           OUT PUNICODE_STRING AliasSymbolicLinkName)
 {
     return STATUS_NOT_IMPLEMENTED;
 }
 
+/*++
+ * @name IopOpenInterfaceKey
+ *
+ * Returns the alias device interface of the specified device interface
+ *
+ * @param InterfaceClassGuid
+ *        FILLME
+ *
+ * @param DesiredAccess
+ *        FILLME
+ *
+ * @param pInterfaceKey
+ *        FILLME
+ *
+ * @return Usual NTSTATUS
+ *
+ * @remarks None
+ *
+ *--*/
 static NTSTATUS
-IopOpenInterfaceKey(
+IopOpenInterfaceKey(IN CONST GUID *InterfaceClassGuid,
-   IN CONST GUID *InterfaceClassGuid,
                     IN ACCESS_MASK DesiredAccess,
                     OUT HANDLE *pInterfaceKey)
 {
@@ -133,26 +190,27 @@ cleanup:
     return Status;
 }
 
-/*
+/*++
- * IoGetDeviceInterfaces
+ * @name IoGetDeviceInterfaces
+ * @implemented
  *
  * Returns a list of device interfaces of a particular device interface class.
+ * Documented in WDK
  *
- * Parameters
+ * @param InterfaceClassGuid
- *    InterfaceClassGuid
+ *        Points to a class GUID specifying the device interface class
- *       Points to a class GUID specifying the device interface class.
  *
- *    PhysicalDeviceObject
+ * @param PhysicalDeviceObject
  *        Points to an optional PDO that narrows the search to only the
- *       device interfaces of the device represented by the PDO.
+ *        device interfaces of the device represented by the PDO
  *
- *    Flags
+ * @param Flags
  *        Specifies flags that modify the search for device interfaces. The
  *        DEVICE_INTERFACE_INCLUDE_NONACTIVE flag specifies that the list of
  *        returned symbolic links should contain also disabled device
  *        interfaces in addition to the enabled ones.
  *
- *    SymbolicLinkList
+ * @param SymbolicLinkList
  *        Points to a character pointer that is filled in on successful return
  *        with a list of unicode strings identifying the device interfaces
  *        that match the search criteria. The newly allocated buffer contains
@@ -164,14 +222,14 @@ cleanup:
  *        returns STATUS_SUCCESS and the string contains a single NULL
  *        character.
  *
- * Status
+ * @return Usual NTSTATUS
- *    @implemented
  *
- */
+ * @remarks None
-
+ *
-NTSTATUS STDCALL
+ *--*/
-IoGetDeviceInterfaces(
+NTSTATUS
-   IN CONST GUID *InterfaceClassGuid,
+NTAPI
+IoGetDeviceInterfaces(IN CONST GUID *InterfaceClassGuid,
                       IN PDEVICE_OBJECT PhysicalDeviceObject OPTIONAL,
                       IN ULONG Flags,
                       OUT PWSTR *SymbolicLinkList)
@@ -212,7 +270,9 @@ IoGetDeviceInterfaces(
             0,
             &Size);
         if (Status == STATUS_NO_MORE_ENTRIES)
+        {
             break;
+        }
         else if (!NT_SUCCESS(Status) && Status != STATUS_BUFFER_TOO_SMALL)
         {
             DPRINT("ZwEnumerateKey() failed with status 0x%08lx\n", Status);
@@ -281,7 +341,9 @@ IoGetDeviceInterfaces(
                 0,
                 &Size);
             if (Status == STATUS_NO_MORE_ENTRIES)
+            {
                 break;
+            }
             else if (!NT_SUCCESS(Status) && Status != STATUS_BUFFER_TOO_SMALL)
             {
                 DPRINT("ZwEnumerateKey() failed with status 0x%08lx\n", Status);
@@ -416,8 +478,10 @@ IoGetDeviceInterfaces(
             KeyName.Length = KeyName.MaximumLength = bip->DataLength - 4 * sizeof(WCHAR);
             KeyName.Buffer = &((PWSTR)bip->Data)[4];
             if (KeyName.Length && KeyName.Buffer[KeyName.Length / sizeof(WCHAR)] == UNICODE_NULL)
+            {
                 /* Remove trailing NULL */
                 KeyName.Length -= sizeof(WCHAR);
+            }
 
             /* Add new symbolic link to symbolic link list */
             if (ReturnBuffer.Length + KeyName.Length + sizeof(WCHAR) > ReturnBuffer.MaximumLength)
@@ -513,13 +577,39 @@ cleanup:
     return Status;
 }
 
-/*
+/*++
+ * @name IoRegisterDeviceInterface
  * @implemented
- */
+ *
-
+ * Registers a device interface class, if it has not been previously registered,
-NTSTATUS STDCALL
+ * and creates a new instance of the interface class, which a driver can
-IoRegisterDeviceInterface(
+ * subsequently enable for use by applications or other system components.
-   IN PDEVICE_OBJECT PhysicalDeviceObject,
+ * Documented in WDK.
+ *
+ * @param PhysicalDeviceObject
+ *        Points to an optional PDO that narrows the search to only the
+ *        device interfaces of the device represented by the PDO
+ *
+ * @param InterfaceClassGuid
+ *        Points to a class GUID specifying the device interface class
+ *
+ * @param ReferenceString
+ *        Optional parameter, pointing to a unicode string. For a full
+ *        description of this rather rarely used param (usually drivers
+ *        pass NULL here) see WDK
+ *
+ * @param SymbolicLinkName
+ *        Pointer to the resulting unicode string
+ *
+ * @return Usual NTSTATUS
+ *
+ * @remarks Must be called at IRQL = PASSIVE_LEVEL in the context of a
+ *          system thread
+ *
+ *--*/
+NTSTATUS
+NTAPI
+IoRegisterDeviceInterface(IN PDEVICE_OBJECT PhysicalDeviceObject,
                           IN CONST GUID *InterfaceClassGuid,
                           IN PUNICODE_STRING ReferenceString OPTIONAL,
                           OUT PUNICODE_STRING SymbolicLinkName)
@@ -818,13 +908,29 @@ IoRegisterDeviceInterface(
     return Status;
 }
 
-/*
+/*++
+ * @name IoSetDeviceInterfaceState
  * @implemented
- */
+ *
-
+ * Enables or disables an instance of a previously registered device
-NTSTATUS STDCALL
+ * interface class.
-IoSetDeviceInterfaceState(
+ * Documented in WDK.
-   IN PUNICODE_STRING SymbolicLinkName,
+ *
+ * @param SymbolicLinkName
+ *        Pointer to the string identifying instance to enable or disable
+ *
+ * @param Enable
+ *        TRUE = enable, FALSE = disable
+ *
+ * @return Usual NTSTATUS
+ *
+ * @remarks Must be called at IRQL = PASSIVE_LEVEL in the context of a
+ *          system thread
+ *
+ *--*/
+NTSTATUS
+NTAPI
+IoSetDeviceInterfaceState(IN PUNICODE_STRING SymbolicLinkName,
                           IN BOOLEAN Enable)
 {
     PDEVICE_OBJECT PhysicalDeviceObject;