[reactos] 02/02: [CSRLIB] Add SAL annotations to the CSR client functions.

[Hermès Bélusca-Maïto]

https://git.reactos.org/?p=reactos.git;a=commitdiff;h=8cd01eaf2566c3ed22352…

commit 8cd01eaf2566c3ed223525251da339e545a86e61
Author:     Hermès Bélusca-Maïto <hermes.belusca-maito(a)reactos.org>
AuthorDate: Sun Oct 23 03:09:41 2022 +0200
Commit:     Hermès Bélusca-Maïto <hermes.belusca-maito(a)reactos.org>
CommitDate: Sat Oct 29 17:17:30 2022 +0200

    [CSRLIB] Add SAL annotations to the CSR client functions.
---
 sdk/include/reactos/subsys/csr/csr.h | 103 ++++++++++++++++++++---------------
 subsystems/csr/csrlib/api.c          |   5 +-
 subsystems/csr/csrlib/capture.c      |  69 +++++++++++++----------
 subsystems/csr/csrlib/connect.c      |  34 ++++++------
 4 files changed, 121 insertions(+), 90 deletions(-)

diff --git a/sdk/include/reactos/subsys/csr/csr.h b/sdk/include/reactos/subsys/csr/csr.h
index ae531e2a0ae..bfa59b60465 100644
--- a/sdk/include/reactos/subsys/csr/csr.h
+++ b/sdk/include/reactos/subsys/csr/csr.h
@@ -1,10 +1,9 @@
 /*
- * COPYRIGHT:       See COPYING in the top level directory
- * PROJECT:         ReactOS Client/Server Runtime SubSystem
- * FILE:            include/reactos/subsys/csr/csr.h
- * PURPOSE:         Public definitions for CSR Clients
- * PROGRAMMERS:     Alex Ionescu (alex.ionescu(a)reactos.org)
- *                  Hermes Belusca-Maito (hermes.belusca(a)sfr.fr)
+ * PROJECT:     ReactOS Client/Server Runtime SubSystem
+ * LICENSE:     GPL-2.0-or-later (https://spdx.org/licenses/GPL-2.0-or-later)
+ * PURPOSE:     Public definitions for CSR Clients
+ * COPYRIGHT:   Copyright 2005 Alex Ionescu <alex(a)relsoft.net>
+ *              Copyright 2012-2022 Hermès Bélusca-Maïto
<hermes.belusca-maito(a)reactos.org>
  */
 
 #ifndef _CSR_H
@@ -14,71 +13,88 @@
 
 NTSTATUS
 NTAPI
-CsrClientConnectToServer(IN PWSTR ObjectDirectory,
-                         IN ULONG ServerId,
-                         IN PVOID ConnectionInfo,
-                         IN OUT PULONG ConnectionInfoSize,
-                         OUT PBOOLEAN ServerToServerCall);
+CsrClientConnectToServer(
+    _In_ PCWSTR ObjectDirectory,
+    _In_ ULONG ServerId,
+    _In_ PVOID ConnectionInfo,
+    _Inout_ PULONG ConnectionInfoSize,
+    _Out_ PBOOLEAN ServerToServerCall);
 
 NTSTATUS
 NTAPI
-CsrClientCallServer(IN OUT PCSR_API_MESSAGE ApiMessage,
-                    IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer OPTIONAL,
-                    IN CSR_API_NUMBER ApiNumber,
-                    IN ULONG DataLength);
+CsrClientCallServer(
+    _Inout_ PCSR_API_MESSAGE ApiMessage,
+    _Inout_opt_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_ CSR_API_NUMBER ApiNumber,
+    _In_ ULONG DataLength);
 
 PCSR_CAPTURE_BUFFER
 NTAPI
-CsrAllocateCaptureBuffer(IN ULONG ArgumentCount,
-                         IN ULONG BufferSize);
+CsrAllocateCaptureBuffer(
+    _In_ ULONG ArgumentCount,
+    _In_ ULONG BufferSize);
 
 ULONG
 NTAPI
-CsrAllocateMessagePointer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                          IN ULONG MessageLength,
-                          OUT PVOID* CapturedData);
+CsrAllocateMessagePointer(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_ ULONG MessageLength,
+    _Out_ PVOID* CapturedData);
 
 VOID
 NTAPI
-CsrCaptureMessageBuffer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                        IN PVOID MessageBuffer OPTIONAL,
-                        IN ULONG MessageLength,
-                        OUT PVOID* CapturedData);
+CsrCaptureMessageBuffer(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_opt_ PVOID MessageBuffer,
+    _In_ ULONG MessageLength,
+    _Out_ PVOID* CapturedData);
 
 VOID
 NTAPI
-CsrFreeCaptureBuffer(IN PCSR_CAPTURE_BUFFER CaptureBuffer);
+CsrFreeCaptureBuffer(
+    _In_ _Frees_ptr_ PCSR_CAPTURE_BUFFER CaptureBuffer);
 
 VOID
 NTAPI
-CsrCaptureMessageString(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                        IN PCSTR String OPTIONAL,
-                        IN ULONG StringLength,
-                        IN ULONG MaximumLength,
-                        OUT PSTRING CapturedString);
+CsrCaptureMessageString(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_opt_ PCSTR String,
+    _In_ ULONG StringLength,
+    _In_ ULONG MaximumLength,
+    _Out_ PSTRING CapturedString);
+
+VOID
+NTAPI
+CsrCaptureMessageUnicodeStringInPlace(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _Inout_ PUNICODE_STRING String);
 
 NTSTATUS
 NTAPI
-CsrCaptureMessageMultiUnicodeStringsInPlace(OUT PCSR_CAPTURE_BUFFER* CaptureBuffer,
-                                            IN ULONG StringsCount,
-                                            IN PUNICODE_STRING* MessageStrings);
+CsrCaptureMessageMultiUnicodeStringsInPlace(
+    _Inout_ PCSR_CAPTURE_BUFFER* CaptureBuffer,
+    _In_ ULONG StringsCount,
+    _In_ PUNICODE_STRING* MessageStrings);
 
 PLARGE_INTEGER
 NTAPI
-CsrCaptureTimeout(IN ULONG Milliseconds,
-                  OUT PLARGE_INTEGER Timeout);
+CsrCaptureTimeout(
+    _In_ ULONG Milliseconds,
+    _Out_ PLARGE_INTEGER Timeout);
 
 VOID
 NTAPI
-CsrProbeForRead(IN PVOID Address,
-                IN ULONG Length,
-                IN ULONG Alignment);
+CsrProbeForRead(
+    _In_ PVOID Address,
+    _In_ ULONG Length,
+    _In_ ULONG Alignment);
 
 VOID
 NTAPI
-CsrProbeForWrite(IN PVOID Address,
-                 IN ULONG Length,
-                 IN ULONG Alignment);
+CsrProbeForWrite(
+    _In_ PVOID Address,
+    _In_ ULONG Length,
+    _In_ ULONG Alignment);
 
 HANDLE
 NTAPI
@@ -94,8 +110,9 @@ CsrIdentifyAlertableThread(VOID);
 
 NTSTATUS
 NTAPI
-CsrSetPriorityClass(IN HANDLE Process,
-                    IN OUT PULONG PriorityClass);
+CsrSetPriorityClass(
+    _In_ HANDLE Process,
+    _Inout_ PULONG PriorityClass);
 
 #endif // _CSR_H
 
diff --git a/subsystems/csr/csrlib/api.c b/subsystems/csr/csrlib/api.c
index b1611d1f34f..2241e9ef652 100644
--- a/subsystems/csr/csrlib/api.c
+++ b/subsystems/csr/csrlib/api.c
@@ -64,8 +64,9 @@ CsrIdentifyAlertableThread(VOID)
  */
 NTSTATUS
 NTAPI
-CsrSetPriorityClass(IN HANDLE Process,
-                    IN OUT PULONG PriorityClass)
+CsrSetPriorityClass(
+    _In_ HANDLE Process,
+    _Inout_ PULONG PriorityClass)
 {
 #if (NTDDI_VERSION < NTDDI_WS03)
     NTSTATUS Status;
diff --git a/subsystems/csr/csrlib/capture.c b/subsystems/csr/csrlib/capture.c
index c5b6b10cb59..2a7855f4c76 100644
--- a/subsystems/csr/csrlib/capture.c
+++ b/subsystems/csr/csrlib/capture.c
@@ -20,9 +20,10 @@
  */
 VOID
 NTAPI
-CsrProbeForRead(IN PVOID Address,
-                IN ULONG Length,
-                IN ULONG Alignment)
+CsrProbeForRead(
+    _In_ PVOID Address,
+    _In_ ULONG Length,
+    _In_ ULONG Alignment)
 {
     volatile UCHAR *Pointer;
     UCHAR Data;
@@ -52,9 +53,10 @@ CsrProbeForRead(IN PVOID Address,
  */
 VOID
 NTAPI
-CsrProbeForWrite(IN PVOID Address,
-                 IN ULONG Length,
-                 IN ULONG Alignment)
+CsrProbeForWrite(
+    _In_ PVOID Address,
+    _In_ ULONG Length,
+    _In_ ULONG Alignment)
 {
     volatile UCHAR *Pointer;
 
@@ -82,8 +84,9 @@ CsrProbeForWrite(IN PVOID Address,
  */
 PCSR_CAPTURE_BUFFER
 NTAPI
-CsrAllocateCaptureBuffer(IN ULONG ArgumentCount,
-                         IN ULONG BufferSize)
+CsrAllocateCaptureBuffer(
+    _In_ ULONG ArgumentCount,
+    _In_ ULONG BufferSize)
 {
     PCSR_CAPTURE_BUFFER CaptureBuffer;
     ULONG OffsetsArraySize;
@@ -146,9 +149,10 @@ CsrAllocateCaptureBuffer(IN ULONG ArgumentCount,
  */
 ULONG
 NTAPI
-CsrAllocateMessagePointer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                          IN ULONG MessageLength,
-                          OUT PVOID* CapturedData)
+CsrAllocateMessagePointer(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_ ULONG MessageLength,
+    _Out_ PVOID* CapturedData)
 {
     if (MessageLength == 0)
     {
@@ -182,10 +186,11 @@ CsrAllocateMessagePointer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
  */
 VOID
 NTAPI
-CsrCaptureMessageBuffer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                        IN PVOID MessageBuffer OPTIONAL,
-                        IN ULONG MessageLength,
-                        OUT PVOID* CapturedData)
+CsrCaptureMessageBuffer(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_opt_ PVOID MessageBuffer,
+    _In_ ULONG MessageLength,
+    _Out_ PVOID* CapturedData)
 {
     /* Simply allocate a message pointer in the buffer */
     CsrAllocateMessagePointer(CaptureBuffer, MessageLength, CapturedData);
@@ -202,7 +207,8 @@ CsrCaptureMessageBuffer(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
  */
 VOID
 NTAPI
-CsrFreeCaptureBuffer(IN PCSR_CAPTURE_BUFFER CaptureBuffer)
+CsrFreeCaptureBuffer(
+    _In_ _Frees_ptr_ PCSR_CAPTURE_BUFFER CaptureBuffer)
 {
     /* Free it from the heap */
     RtlFreeHeap(CsrPortHeap, 0, CaptureBuffer);
@@ -213,11 +219,12 @@ CsrFreeCaptureBuffer(IN PCSR_CAPTURE_BUFFER CaptureBuffer)
  */
 VOID
 NTAPI
-CsrCaptureMessageString(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                        IN PCSTR String OPTIONAL,
-                        IN ULONG StringLength,
-                        IN ULONG MaximumLength,
-                        OUT PSTRING CapturedString)
+CsrCaptureMessageString(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_opt_ PCSTR String,
+    _In_ ULONG StringLength,
+    _In_ ULONG MaximumLength,
+    _Out_ PSTRING CapturedString)
 {
     ASSERT(CapturedString != NULL);
 
@@ -259,9 +266,11 @@ CsrCaptureMessageString(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
         CapturedString->Buffer[CapturedString->Length] = ANSI_NULL;
 }
 
-static VOID
-CsrCaptureMessageUnicodeStringInPlace(IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer,
-                                      IN PUNICODE_STRING String)
+VOID
+NTAPI
+CsrCaptureMessageUnicodeStringInPlace(
+    _Inout_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _Inout_ PUNICODE_STRING String)
 {
     ASSERT(String != NULL);
 
@@ -282,9 +291,10 @@ CsrCaptureMessageUnicodeStringInPlace(IN OUT PCSR_CAPTURE_BUFFER
CaptureBuffer,
  */
 NTSTATUS
 NTAPI
-CsrCaptureMessageMultiUnicodeStringsInPlace(OUT PCSR_CAPTURE_BUFFER* CaptureBuffer,
-                                            IN ULONG StringsCount,
-                                            IN PUNICODE_STRING* MessageStrings)
+CsrCaptureMessageMultiUnicodeStringsInPlace(
+    _Inout_ PCSR_CAPTURE_BUFFER* CaptureBuffer,
+    _In_ ULONG StringsCount,
+    _In_ PUNICODE_STRING* MessageStrings)
 {
     ULONG Count;
 
@@ -328,8 +338,9 @@ CsrCaptureMessageMultiUnicodeStringsInPlace(OUT PCSR_CAPTURE_BUFFER*
CaptureBuff
  */
 PLARGE_INTEGER
 NTAPI
-CsrCaptureTimeout(IN ULONG Milliseconds,
-                  OUT PLARGE_INTEGER Timeout)
+CsrCaptureTimeout(
+    _In_ ULONG Milliseconds,
+    _Out_ PLARGE_INTEGER Timeout)
 {
     /* Validate the time */
     if (Milliseconds == -1) return NULL;
diff --git a/subsystems/csr/csrlib/connect.c b/subsystems/csr/csrlib/connect.c
index 51d7c006f75..c93f80075d7 100644
--- a/subsystems/csr/csrlib/connect.c
+++ b/subsystems/csr/csrlib/connect.c
@@ -31,16 +31,17 @@ ULONG_PTR CsrPortMemoryDelta;
 BOOLEAN InsideCsrProcess = FALSE;
 
 typedef NTSTATUS
-(NTAPI *PCSR_SERVER_API_ROUTINE)(IN PPORT_MESSAGE Request,
-                                 IN PPORT_MESSAGE Reply);
+(NTAPI *PCSR_SERVER_API_ROUTINE)(
+    _In_ PCSR_API_MESSAGE Request,
+    _Inout_ PCSR_API_MESSAGE Reply);
 
 PCSR_SERVER_API_ROUTINE CsrServerApiRoutine;
 
 /* FUNCTIONS ******************************************************************/
 
-NTSTATUS
-NTAPI
-CsrpConnectToServer(IN PWSTR ObjectDirectory)
+static NTSTATUS
+CsrpConnectToServer(
+    _In_ PCWSTR ObjectDirectory)
 {
     NTSTATUS Status;
     SIZE_T PortNameLength;
@@ -198,11 +199,12 @@ CsrpConnectToServer(IN PWSTR ObjectDirectory)
  */
 NTSTATUS
 NTAPI
-CsrClientConnectToServer(IN PWSTR ObjectDirectory,
-                         IN ULONG ServerId,
-                         IN PVOID ConnectionInfo,
-                         IN OUT PULONG ConnectionInfoSize,
-                         OUT PBOOLEAN ServerToServerCall)
+CsrClientConnectToServer(
+    _In_ PCWSTR ObjectDirectory,
+    _In_ ULONG ServerId,
+    _In_ PVOID ConnectionInfo,
+    _Inout_ PULONG ConnectionInfoSize,
+    _Out_ PBOOLEAN ServerToServerCall)
 {
     NTSTATUS Status;
     PIMAGE_NT_HEADERS NtHeader;
@@ -367,10 +369,11 @@ C_ASSERT((sizeof(TEST) - sizeof(TEST_EMBEDDED)) !=
FIELD_OFFSET(TEST, Three));
  */
 NTSTATUS
 NTAPI
-CsrClientCallServer(IN OUT PCSR_API_MESSAGE ApiMessage,
-                    IN OUT PCSR_CAPTURE_BUFFER CaptureBuffer OPTIONAL,
-                    IN CSR_API_NUMBER ApiNumber,
-                    IN ULONG DataLength)
+CsrClientCallServer(
+    _Inout_ PCSR_API_MESSAGE ApiMessage,
+    _Inout_opt_ PCSR_CAPTURE_BUFFER CaptureBuffer,
+    _In_ CSR_API_NUMBER ApiNumber,
+    _In_ ULONG DataLength)
 {
     NTSTATUS Status;
 
@@ -484,8 +487,7 @@ CsrClientCallServer(IN OUT PCSR_API_MESSAGE ApiMessage,
         ApiMessage->Header.ClientId = NtCurrentTeb()->ClientId;
 
         /* Do a direct call */
-        Status = CsrServerApiRoutine(&ApiMessage->Header,
-                                     &ApiMessage->Header);
+        Status = CsrServerApiRoutine(ApiMessage, ApiMessage);
 
         /* Check for success */
         if (!NT_SUCCESS(Status))