[akhaldi] 59973: [DDK] * Annotate scsiwmi.h.

Author: akhaldi
Date: Tue Sep  3 12:04:47 2013
New Revision: 59973

URL: http://svn.reactos.org/svn/reactos?rev=59973&view=rev
Log:
[DDK]
* Annotate scsiwmi.h.

Modified:
    trunk/reactos/include/ddk/scsiwmi.h

Modified: trunk/reactos/include/ddk/scsiwmi.h
URL:
http://svn.reactos.org/svn/reactos/trunk/reactos/include/ddk/scsiwmi.h?rev=…
==============================================================================
--- trunk/reactos/include/ddk/scsiwmi.h	[iso-8859-1] (original)
+++ trunk/reactos/include/ddk/scsiwmi.h	[iso-8859-1] Tue Sep  3 12:04:47 2013
@@ -20,8 +20,10 @@
  *
  */
 
-#ifndef __SCSIWMI_H
-#define __SCSIWMI_H
+#pragma once
+
+#ifndef _SCSIWMI_
+#define _SCSIWMI_
 
 #include "srb.h"
 
@@ -32,12 +34,12 @@
 #pragma pack(push,4)
 
 typedef struct _SCSIWMI_REQUEST_CONTEXT {
-  PVOID  UserContext;
-  ULONG  BufferSize;
-  PUCHAR  Buffer;
-  UCHAR  MinorFunction;
-  UCHAR  ReturnStatus;
-  ULONG  ReturnSize;
+  PVOID UserContext;
+  ULONG BufferSize;
+  PUCHAR Buffer;
+  UCHAR MinorFunction;
+  UCHAR ReturnStatus;
+  ULONG ReturnSize;
 } SCSIWMI_REQUEST_CONTEXT, *PSCSIWMI_REQUEST_CONTEXT;
 
 #ifdef _GUID_DEFINED
@@ -47,129 +49,142 @@
 #if ! (defined _GUID_DEFINED || defined GUID_DEFINED)
 #define GUID_DEFINED
 typedef struct _GUID {
-    unsigned long  Data1;
-    unsigned short Data2;
-    unsigned short Data3;
-    unsigned char  Data4[ 8 ];
+  unsigned long  Data1;
+  unsigned short Data2;
+  unsigned short Data3;
+  unsigned char Data4[8];
 } GUID;
 #endif
 
 typedef struct _SCSIWMIGUIDREGINFO {
-  LPCGUID  Guid;
-  ULONG  InstanceCount;
-  ULONG  Flags;
+  LPCGUID Guid;
+  ULONG InstanceCount;
+  ULONG Flags;
 } SCSIWMIGUIDREGINFO, *PSCSIWMIGUIDREGINFO;
 
-typedef UCHAR
+typedef
+_Must_inspect_result_
+UCHAR
 (NTAPI *PSCSIWMI_QUERY_REGINFO)(
-	IN PVOID  DeviceContext,
-	IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-	OUT PWCHAR  *MofResourceName);
-
-typedef BOOLEAN
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _Out_ PWCHAR *MofResourceName);
+
+typedef
+_Must_inspect_result_
+BOOLEAN
 (NTAPI *PSCSIWMI_QUERY_DATABLOCK)(
-  IN PVOID  Context,
-  IN PSCSIWMI_REQUEST_CONTEXT  DispatchContext,
-  IN ULONG  GuidIndex,
-  IN ULONG  InstanceIndex,
-  IN ULONG  InstanceCount,
-  IN OUT PULONG  InstanceLengthArray,
-  IN ULONG  BufferAvail,
-  OUT PUCHAR  Buffer);
-
-typedef BOOLEAN
+  _In_ PVOID Context,
+  _In_ PSCSIWMI_REQUEST_CONTEXT DispatchContext,
+  _In_ ULONG GuidIndex,
+  _In_ ULONG InstanceIndex,
+  _In_ ULONG InstanceCount,
+  _Inout_ PULONG InstanceLengthArray,
+  _In_ ULONG BufferAvail,
+  _Out_writes_bytes_(BufferAvail) PUCHAR Buffer);
+
+typedef
+_Must_inspect_result_
+BOOLEAN
 (NTAPI *PSCSIWMI_SET_DATABLOCK)(
-  IN PVOID  DeviceContext,
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN ULONG  GuidIndex,
-  IN ULONG  InstanceIndex,
-  IN ULONG  BufferSize,
-  IN PUCHAR  Buffer);
-
-typedef BOOLEAN
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ ULONG GuidIndex,
+  _In_ ULONG InstanceIndex,
+  _In_ ULONG BufferSize,
+  _In_reads_bytes_(BufferSize) PUCHAR Buffer);
+
+typedef
+_Must_inspect_result_
+BOOLEAN
 (NTAPI *PSCSIWMI_SET_DATAITEM)(
-  IN PVOID  DeviceContext,
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN ULONG  GuidIndex,
-  IN ULONG  InstanceIndex,
-  IN ULONG  DataItemId,
-  IN ULONG  BufferSize,
-  IN PUCHAR  Buffer);
-
-typedef BOOLEAN
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ ULONG GuidIndex,
+  _In_ ULONG InstanceIndex,
+  _In_ ULONG DataItemId,
+  _In_ ULONG BufferSize,
+  _In_reads_bytes_(BufferSize) PUCHAR Buffer);
+
+typedef
+_Must_inspect_result_
+BOOLEAN
 (NTAPI *PSCSIWMI_EXECUTE_METHOD)(
-  IN PVOID  DeviceContext,
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN ULONG  GuidIndex,
-  IN ULONG  InstanceIndex,
-  IN ULONG  MethodId,
-  IN ULONG  InBufferSize,
-  IN ULONG  OutBufferSize,
-  IN OUT PUCHAR  Buffer);
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ ULONG GuidIndex,
+  _In_ ULONG InstanceIndex,
+  _In_ ULONG MethodId,
+  _In_ ULONG InBufferSize,
+  _In_ ULONG OutBufferSize,
+  _Inout_updates_bytes_to_(InBufferSize, OutBufferSize) PUCHAR Buffer);
 
 typedef enum _SCSIWMI_ENABLE_DISABLE_CONTROL {
-	ScsiWmiEventControl,
-	ScsiWmiDataBlockControl
+  ScsiWmiEventControl,
+  ScsiWmiDataBlockControl
 } SCSIWMI_ENABLE_DISABLE_CONTROL;
 
-typedef BOOLEAN
+typedef
+_Must_inspect_result_
+BOOLEAN
 (NTAPI *PSCSIWMI_FUNCTION_CONTROL)(
-  IN PVOID  DeviceContext,
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN ULONG  GuidIndex,
-  IN SCSIWMI_ENABLE_DISABLE_CONTROL  Function,
-  IN BOOLEAN  Enable);
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ ULONG GuidIndex,
+  _In_ SCSIWMI_ENABLE_DISABLE_CONTROL Function,
+  _In_ BOOLEAN Enable);
 
 typedef struct _SCSIWMILIB_CONTEXT {
-  ULONG  GuidCount;
-  PSCSIWMIGUIDREGINFO  GuidList;
-  PSCSIWMI_QUERY_REGINFO  QueryWmiRegInfo;
-  PSCSIWMI_QUERY_DATABLOCK  QueryWmiDataBlock;
-  PSCSIWMI_SET_DATABLOCK  SetWmiDataBlock;
-  PSCSIWMI_SET_DATAITEM  SetWmiDataItem;
-  PSCSIWMI_EXECUTE_METHOD  ExecuteWmiMethod;
-  PSCSIWMI_FUNCTION_CONTROL  WmiFunctionControl;
+  ULONG GuidCount;
+  PSCSIWMIGUIDREGINFO GuidList;
+  PSCSIWMI_QUERY_REGINFO QueryWmiRegInfo;
+  PSCSIWMI_QUERY_DATABLOCK QueryWmiDataBlock;
+  PSCSIWMI_SET_DATABLOCK SetWmiDataBlock;
+  PSCSIWMI_SET_DATAITEM SetWmiDataItem;
+  PSCSIWMI_EXECUTE_METHOD ExecuteWmiMethod;
+  PSCSIWMI_FUNCTION_CONTROL WmiFunctionControl;
 } SCSI_WMILIB_CONTEXT, *PSCSI_WMILIB_CONTEXT;
 
+_Must_inspect_result_
 SCSIPORTAPI
 BOOLEAN
 NTAPI
 ScsiPortWmiDispatchFunction(
-  IN PSCSI_WMILIB_CONTEXT  WmiLibInfo,
-  IN UCHAR  MinorFunction,
-  IN PVOID  DeviceContext,
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN PVOID  DataPath,
-  IN ULONG  BufferSize,
-  IN PVOID  Buffer);
-
-#define ScsiPortWmiFireAdapterEvent(  \
-  HwDeviceExtension,                  \
-  Guid,                               \
-  InstanceIndex,                      \
-  EventDataSize,                      \
-  EventData)                          \
-    ScsiPortWmiFireLogicalUnitEvent(  \
-	  HwDeviceExtension,                \
-	  0xff,                             \
-	  0,                                \
-	  0,                                \
-	  Guid,                             \
-	  InstanceIndex,                    \
-	  EventDataSize,                    \
-	  EventData)
+  _In_ PSCSI_WMILIB_CONTEXT WmiLibInfo,
+  _In_ UCHAR MinorFunction,
+  _In_ PVOID DeviceContext,
+  _In_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ PVOID DataPath,
+  _In_ ULONG BufferSize,
+  _In_ PVOID Buffer);
+
+#define ScsiPortWmiFireAdapterEvent(    \
+  HwDeviceExtension,                    \
+  Guid,                                 \
+  InstanceIndex,                        \
+  EventDataSize,                        \
+  EventData)                            \
+    ScsiPortWmiFireLogicalUnitEvent(    \
+      HwDeviceExtension,                \
+      0xff,                             \
+      0,                                \
+      0,                                \
+      Guid,                             \
+      InstanceIndex,                    \
+      EventDataSize,                    \
+      EventData)
 
 /*
  * ULONG
  * ScsiPortWmiGetReturnSize(
- *   PSCSIWMI_REQUEST_CONTEXT  RequestContext);
+ *   PSCSIWMI_REQUEST_CONTEXT RequestContext);
  */
 #define ScsiPortWmiGetReturnSize(RequestContext) \
   ((RequestContext)->ReturnSize)
 
 /* UCHAR
  * ScsiPortWmiGetReturnStatus(
- *   PSCSIWMI_REQUEST_CONTEXT  RequestContext);
+ *   PSCSIWMI_REQUEST_CONTEXT RequestContext);
  */
 #define ScsiPortWmiGetReturnStatus(RequestContext) \
   ((RequestContext)->ReturnStatus)
@@ -178,22 +193,22 @@
 VOID
 NTAPI
 ScsiPortWmiPostProcess(
-  IN PSCSIWMI_REQUEST_CONTEXT  RequestContext,
-  IN UCHAR  SrbStatus,
-  IN ULONG  BufferUsed);
+  _Inout_ PSCSIWMI_REQUEST_CONTEXT RequestContext,
+  _In_ UCHAR SrbStatus,
+  _In_ ULONG BufferUsed);
 
 SCSIPORTAPI
 VOID
 NTAPI
 ScsiPortWmiFireLogicalUnitEvent(
-  IN PVOID  HwDeviceExtension,
-  IN UCHAR  PathId,
-  IN UCHAR  TargetId,
-  IN UCHAR  Lun,
-  IN LPGUID  Guid,
-  IN ULONG  InstanceIndex,
-  IN ULONG  EventDataSize,
-  IN PVOID  EventData);
+  _In_ PVOID HwDeviceExtension,
+  _In_ UCHAR PathId,
+  _In_ UCHAR TargetId,
+  _In_ UCHAR Lun,
+  _In_ LPGUID Guid,
+  _In_ ULONG InstanceIndex,
+  _In_ ULONG EventDataSize,
+  _In_ PVOID EventData);
 
 #pragma pack(pop)
 
@@ -201,4 +216,4 @@
 }
 #endif
 
-#endif /* __SCSIWMI_H */
+#endif /* _SCSIWMI_ */