[CSRSRV]
authorHermès Bélusca-Maïto <hermes.belusca-maito@reactos.org>
Sat, 13 Oct 2012 20:32:44 +0000 (20:32 +0000)
committerHermès Bélusca-Maïto <hermes.belusca-maito@reactos.org>
Sat, 13 Oct 2012 20:32:44 +0000 (20:32 +0000)
- Remove $Id$ property.
- Correct misspellings : "othwerwise" --> "otherwise" and "(de)refence" --> "(de)reference".
- Add missing functions' documentation (from the old CSRSRV).
- Add some useful comments.

svn path=/trunk/; revision=57556

reactos/subsystems/win32/csrss/csrsrv/api/user.c
reactos/subsystems/win32/csrss/csrsrv/api/wapi.c
reactos/subsystems/win32/csrss/csrsrv/init.c
reactos/subsystems/win32/csrss/csrsrv/procsup.c
reactos/subsystems/win32/csrss/csrsrv/server.c
reactos/subsystems/win32/csrss/csrsrv/session.c
reactos/subsystems/win32/csrss/csrsrv/thredsup.c
reactos/subsystems/win32/csrss/csrsrv/wait.c
reactos/subsystems/win32/csrss/include/api.h
reactos/subsystems/win32/csrss/include/csrplugin.h

index 140250f..9ce9da0 100644 (file)
@@ -1,5 +1,4 @@
-/* $Id$
- *
+/*
  * subsystems/win32/csrss/csrsrv/api/user.c
  *
  * User functions
index e4b884b..af4f764 100644 (file)
@@ -1,5 +1,4 @@
-/* $Id$
- *
+/*
  * subsystems/win32/csrss/csrsrv/api/wapi.c
  *
  * CSRSS port message processing
@@ -206,7 +205,9 @@ CsrCallServerFromServer(PCSR_API_MESSAGE ReceiveMsg,
 
     /* Return success */
     return STATUS_SUCCESS;
+
 #else // Hacky reactos code
+
     PCSR_PROCESS ProcessData;
 
     /* Get the Process Data */
@@ -249,7 +250,7 @@ CsrCallServerFromServer(PCSR_API_MESSAGE ReceiveMsg,
  * @param None
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -298,8 +299,8 @@ CsrApiPortInitialize(VOID)
     /* Create the Port Object */
     Status = NtCreatePort(&CsrApiPort,
                           &ObjectAttributes,
-                          LPC_MAX_DATA_LENGTH, // hack
-                          LPC_MAX_MESSAGE_LENGTH, // hack
+                          LPC_MAX_DATA_LENGTH, // hack ; sizeof(CSR_CONNECTION_INFO),
+                          LPC_MAX_MESSAGE_LENGTH, // hack ; sizeof(CSR_API_MESSAGE),
                           16 * PAGE_SIZE);
     if (NT_SUCCESS(Status))
     {
@@ -745,7 +746,7 @@ BasepFakeStaticServerData(VOID)
 }
 
 NTSTATUS WINAPI
-CsrpHandleConnectionRequest (PPORT_MESSAGE Request)
+CsrpHandleConnectionRequest(PPORT_MESSAGE Request)
 {
     NTSTATUS Status;
     HANDLE ServerPort = NULL;//, ServerThread = NULL;
@@ -844,6 +845,19 @@ CsrpHandleConnectionRequest (PPORT_MESSAGE Request)
     return Status;
 }
 
+/*++
+ * @name CsrConnectToUser
+ * @implemented NT4
+ *
+ * The CsrConnectToUser connects to the User subsystem.
+ *
+ * @param None
+ *
+ * @return A pointer to the CSR Thread
+ *
+ * @remarks None.
+ *
+ *--*/
 PCSR_THREAD
 NTAPI
 CsrConnectToUser(VOID)
index 45433b6..45a4433 100644 (file)
@@ -3,7 +3,8 @@
  * PROJECT:         ReactOS CSR Sub System
  * FILE:            subsystems/win32/csrss/csrsrv/init.c
  * PURPOSE:         CSR Server DLL Initialization
- * PROGRAMMERS:     ReactOS Portable Systems Group
+ * PROGRAMMERS:     Alex Ionescu (alex@relsoft.net)
+ *                  ReactOS Portable Systems Group
  */
 
 /* INCLUDES *******************************************************************/
@@ -111,7 +112,7 @@ BasepFakeStaticServerData(VOID);
  * @param None.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -226,7 +227,7 @@ Quickie:
  *        Handle fo the Object Directory to protect.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -249,7 +250,7 @@ CsrSetDirectorySecurity(IN HANDLE ObjectDirectory)
  *        Pointer to the Security Descriptor to return.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks Depending on the DOS Devices Protection Mode (set in the registry),
  *          regular users may or may not have full access to the directory.
@@ -466,7 +467,7 @@ FreeDosDevicesProtection(IN PSECURITY_DESCRIPTOR DosDevicesSd)
  *        Session ID for which to create the directories.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -597,7 +598,7 @@ CsrCreateSessionObjectDirectory(IN ULONG Session)
  *        Array of arguments.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -754,6 +755,7 @@ CsrParseServerCommandLine(IN ULONG ArgumentCount,
 //            {
 //                Status = CsrLoadServerDll(ParameterValue, EntryPoint, 2);
 //            }
+            // Status = CsrLoadServerDll(ParameterValue, EntryPoint, DllIndex);
             if (!NT_SUCCESS(Status))
             {
                 DPRINT1("CSRSS: *** Failed loading ServerDll=%s (Status == 0x%x)\n",
@@ -786,7 +788,7 @@ CsrParseServerCommandLine(IN ULONG ArgumentCount,
  *        Pointer to a pointer to the security descriptor to create.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -826,7 +828,7 @@ CsrCreateLocalSystemSD(OUT PSECURITY_DESCRIPTOR *LocalSystemSd)
         return Status;
     }
 
-    /* Create the DACL for it*/
+    /* Create the DACL for it */
     RtlCreateAcl(Dacl, Length, ACL_REVISION2);
 
     /* Create the ACE */
@@ -863,7 +865,7 @@ CsrCreateLocalSystemSD(OUT PSECURITY_DESCRIPTOR *LocalSystemSd)
  * @param None
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -945,6 +947,25 @@ CsrSbApiPortInitialize(VOID)
 
 /* PUBLIC FUNCTIONS ***********************************************************/
 
+/*++
+ * @name CsrServerInitialization
+ * @implemented NT4
+ *
+ * The CsrServerInitialization routine is the native (not Server) entrypoint
+ * of this Server DLL. It serves as the entrypoint for csrss.
+ *
+ * @param ArgumentCount
+ *        Number of arguments on the command line.
+ *
+ * @param Arguments
+ *        Array of arguments from the command line.
+ *
+ * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
+ *         otherwise.
+ *
+ * @remarks None.
+ *
+ *--*/
 NTSTATUS
 NTAPI
 CsrServerInitialization(IN ULONG ArgumentCount,
@@ -1085,11 +1106,33 @@ CsrServerInitialization(IN ULONG ArgumentCount,
     return Status;
 }
 
+/*++
+ * @name CsrPopulateDosDevices
+ * @unimplemented NT5.1
+ *
+ * The CsrPopulateDosDevices routine uses the DOS Device Map from the Kernel
+ * to populate the Dos Devices Object Directory for the session.
+ *
+ * @param None.
+ *
+ * @return None.
+ *
+ * @remarks None.
+ *
+ *--*/
+VOID
+NTAPI
+CsrPopulateDosDevices(VOID)
+{
+    DPRINT1("Deprecated API\n");
+    return;
+}
+
 BOOL
 NTAPI
-DllMain(HANDLE hDll,
-        DWORD dwReason,
-        LPVOID lpReserved)
+DllMain(IN HANDLE hDll,
+        IN DWORD dwReason,
+        IN LPVOID lpReserved)
 {
     /* We don't do much */
     UNREFERENCED_PARAMETER(hDll);
index 0f2b955..2285970 100644 (file)
@@ -17,7 +17,7 @@
 /* GLOBALS ********************************************************************/
 
 RTL_CRITICAL_SECTION ProcessDataLock;
-PCSR_PROCESS CsrRootProcess;
+PCSR_PROCESS CsrRootProcess = NULL;
 SECURITY_QUALITY_OF_SERVICE CsrSecurityQos =
 {
     sizeof(SECURITY_QUALITY_OF_SERVICE),
@@ -25,7 +25,7 @@ SECURITY_QUALITY_OF_SERVICE CsrSecurityQos =
     SECURITY_STATIC_TRACKING,
     FALSE
 };
-LONG CsrProcessSequenceCount = 5;
+ULONG CsrProcessSequenceCount = 5;
 extern ULONG CsrTotalPerProcessDataLength;
 
 /* FUNCTIONS ******************************************************************/
@@ -64,6 +64,26 @@ CsrSetToShutdownPriority(VOID)
     }
 }
 
+/*++
+ * @name CsrGetProcessLuid
+ * @implemented NT4
+ *
+ * Do nothing for 500ms.
+ *
+ * @param hProcess
+ *        Optional handle to the process whose LUID should be returned.
+ *
+ * @param Luid
+ *        Pointer to a LUID Pointer which will receive the CSR Process' LUID
+ *
+ * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
+ *         otherwise.
+ *
+ * @remarks If hProcess is not supplied, then the current thread's token will
+ *          be used. If that too is missing, then the current process' token
+ *          will be used.
+ *
+ *--*/
 NTSTATUS
 NTAPI
 CsrGetProcessLuid(HANDLE hProcess OPTIONAL,
@@ -148,6 +168,20 @@ CsrGetProcessLuid(HANDLE hProcess OPTIONAL,
     return Status;
 }
 
+/*++
+ * @name CsrImpersonateClient
+ * @implemented NT4
+ *
+ * The CsrImpersonateClient will impersonate the given CSR Thread.
+ *
+ * @param CsrThread
+ *        Pointer to the CSR Thread to impersonate.
+ *
+ * @return TRUE if impersionation suceeded, false otherwise.
+ *
+ * @remarks Impersonation can be recursive.
+ *
+ *--*/
 BOOLEAN
 NTAPI
 CsrImpersonateClient(IN PCSR_THREAD CsrThread)
@@ -173,6 +207,10 @@ CsrImpersonateClient(IN PCSR_THREAD CsrThread)
     if (!NT_SUCCESS(Status))
     {
         /* Failure */
+/*
+        DPRINT1("CSRSS: Can't impersonate client thread - Status = %lx\n", Status);
+        if (Status != STATUS_BAD_IMPERSONATION_LEVEL) DbgBreakPoint();
+*/
         return FALSE;
     }
 
@@ -183,6 +221,21 @@ CsrImpersonateClient(IN PCSR_THREAD CsrThread)
     return TRUE;
 }
 
+/*++
+ * @name CsrRevertToSelf
+ * @implemented NT4
+ *
+ * The CsrRevertToSelf routine will attempt to remove an active impersonation.
+ *
+ * @param None.
+ *
+ * @return TRUE if the reversion was succesful, false otherwise.
+ *
+ * @remarks Impersonation can be recursive; as such, the impersonation token
+ *          will only be deleted once the CSR Thread's impersonaton count
+ *          has reached zero.
+ *
+ *--*/
 BOOLEAN
 NTAPI
 CsrRevertToSelf(VOID)
@@ -197,6 +250,7 @@ CsrRevertToSelf(VOID)
         /* Make sure impersonation is on */
         if (!CurrentThread->ImpersonationCount)
         {
+            // DPRINT1("CSRSS: CsrRevertToSelf called while not impersonating\n");
             return FALSE;
         }
         else if (--CurrentThread->ImpersonationCount > 0)
@@ -216,18 +270,33 @@ CsrRevertToSelf(VOID)
     return NT_SUCCESS(Status);
 }
 
+/*++
+ * @name FindProcessForShutdown
+ *
+ * The FindProcessForShutdown routine returns a CSR Process which is ready
+ * to be shutdown, and sets the appropriate shutdown flags for it.
+ *
+ * @param CallerLuid
+ *        Pointer to the LUID of the CSR Process calling this routine.
+ *
+ * @return Pointer to a CSR Process which is ready to be shutdown.
+ *
+ * @remarks None.
+ *
+ *--*/
 PCSR_PROCESS
 NTAPI
 FindProcessForShutdown(IN PLUID CallerLuid)
 {
     PCSR_PROCESS CsrProcess, ReturnCsrProcess = NULL;
+    // PCSR_THREAD CsrThread;
     NTSTATUS Status;
     ULONG Level = 0;
     LUID ProcessLuid;
     LUID SystemLuid = SYSTEM_LUID;
-    BOOLEAN IsSystemLuid = FALSE, IsOurLuid = FALSE;
+    // BOOLEAN IsSystemLuid = FALSE, IsOurLuid = FALSE;
     PLIST_ENTRY NextEntry;
-    
+
     /* Set the List Pointers */
     NextEntry = CsrRootProcess->ListLink.Flink;
     while (NextEntry != &CsrRootProcess->ListLink)
@@ -237,10 +306,10 @@ FindProcessForShutdown(IN PLUID CallerLuid)
 
         /* Move to the next entry */
         NextEntry = NextEntry->Flink;
-        
+
         /* Skip this process if it's already been processed */
         if (CsrProcess->Flags & CsrProcessSkipShutdown) continue;
-    
+
         /* Get the LUID of this Process */
         Status = CsrGetProcessLuid(CsrProcess->ProcessHandle, &ProcessLuid);
 
@@ -248,29 +317,41 @@ FindProcessForShutdown(IN PLUID CallerLuid)
         if (Status == STATUS_ACCESS_DENIED)
         {
             /* FIXME:Check if we have any threads */
+/*
+            if (CsrProcess->ThreadCount)
+            {
+                /\* Impersonate one of the threads and retry *\/
+                CsrThread = CONTAINING_RECORD(CsrProcess->ThreadList.Flink,
+                                              CSR_THREAD,
+                                              Link);
+                CsrImpersonateClient(CsrThread);
+                Status = CsrGetProcessLuid(NULL, &ProcessLuid);
+                CsrRevertToSelf();
+            }
+*/
         }
-        
+
         if (!NT_SUCCESS(Status))
         {
             /* We didn't have access, so skip it */
             CsrProcess->Flags |= CsrProcessSkipShutdown;
             continue;
         }
-        
+
         /* Check if this is the System LUID */
-        if ((IsSystemLuid = RtlEqualLuid(&ProcessLuid, &SystemLuid)))
+        if ((/*IsSystemLuid =*/ RtlEqualLuid(&ProcessLuid, &SystemLuid)))
         {
             /* Mark this process */
             CsrProcess->ShutdownFlags |= CsrShutdownSystem;
         }
-        else if (!(IsOurLuid = RtlEqualLuid(&ProcessLuid, CallerLuid)))
+        else if (!(/*IsOurLuid =*/ RtlEqualLuid(&ProcessLuid, CallerLuid)))
         {
             /* Our LUID doesn't match with the caller's */
             CsrProcess->ShutdownFlags |= CsrShutdownOther;
         }
-        
+
         /* Check if we're past the previous level */
-        if (CsrProcess->ShutdownLevel > Level)
+        if (CsrProcess->ShutdownLevel > Level /* || !ReturnCsrProcess */)
         {
             /* Update the level */
             Level = CsrProcess->ShutdownLevel;
@@ -279,14 +360,14 @@ FindProcessForShutdown(IN PLUID CallerLuid)
             ReturnCsrProcess = CsrProcess;
         }
     }
-    
+
     /* Check if we found a process */
     if (ReturnCsrProcess)
     {
         /* Skip this one next time */
         ReturnCsrProcess->Flags |= CsrProcessSkipShutdown;
     }
-    
+
     return ReturnCsrProcess;
 }
 
@@ -604,7 +685,7 @@ CsrDestroyProcess(IN PCLIENT_ID Cid,
  *        column.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -903,7 +984,7 @@ CsrAllocateProcess(VOID)
 /*++
  * @name CsrLockedReferenceProcess
  *
- * The CsrLockedReferenceProcess refences a CSR Process while the
+ * The CsrLockedReferenceProcess references a CSR Process while the
  * Process Lock is already being held.
  *
  * @param CsrProcess
@@ -923,7 +1004,7 @@ CsrLockedReferenceProcess(IN PCSR_PROCESS CsrProcess)
 }
 
 /*++
- * @name CsrServerInitialization
+ * @name CsrInitializeProcessStructure
  * @implemented NT4
  *
  * The CsrInitializeProcessStructure routine sets up support for CSR Processes
@@ -932,7 +1013,7 @@ CsrLockedReferenceProcess(IN PCSR_PROCESS CsrProcess)
  * @param None.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -1099,7 +1180,7 @@ CsrInsertProcess(IN PCSR_PROCESS Parent OPTIONAL,
  *        CSR Process corresponding to the given Process ID.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks Locking a CSR Process is defined as acquiring an extra
  *          reference to it and returning with the Process Lock held.
index cecfa9a..1221edc 100644 (file)
@@ -98,7 +98,7 @@ CsrServerDllInitialization(IN PCSR_SERVER_DLL LoadedServerDll)
  *        assumed.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -340,7 +340,7 @@ CsrSrvClientConnect(IN OUT PCSR_API_MESSAGE ApiMessage,
  *        specifies various arguments for the shared section.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -463,7 +463,7 @@ CsrSrvCreateSharedSection(IN PCHAR ParameterValue)
  *        connection.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
index 9f068e0..361b3c3 100644 (file)
@@ -192,7 +192,7 @@ CsrDereferenceNtSession(IN PCSR_NT_SESSION Session,
  * @param ApiMessage
  *        Pointer to the Session Manager API Message.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks The CsrSbCreateSession routine will initialize a new CSR NT
  *          Session and allocate a new CSR Process for the subsystem process.
@@ -339,7 +339,7 @@ CsrSbCreateSession(IN PSB_API_MSG ApiMessage)
  * @param ApiMessage
  *        Pointer to the Session Manager API Message.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks The CsrSbForeignSessionComplete API is not yet implemented.
  *
@@ -362,7 +362,7 @@ CsrSbForeignSessionComplete(IN PSB_API_MSG ApiMessage)
  * @param ApiMessage
  *        Pointer to the Session Manager API Message.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks The CsrSbTerminateSession API is not yet implemented.
  *
@@ -384,7 +384,7 @@ CsrSbTerminateSession(IN PSB_API_MSG ApiMessage)
  * @param ApiMessage
  *        Pointer to the Session Manager API Message.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks The CsrSbCreateProcess API is not yet implemented.
  *
index 6124af4..18cfca1 100644 (file)
@@ -2,7 +2,7 @@
  * COPYRIGHT:       See COPYING in the top level directory
  * PROJECT:         ReactOS CSR Sub System
  * FILE:            subsystems/win32/csrss/csrsrv/thredsup.c
- * PURPOSE:         CSR Process Management
+ * PURPOSE:         CSR Server DLL Thread Implementation
  * PROGRAMMERS:     ReactOS Portable Systems Group
  *                  Alex Ionescu
  */
@@ -101,6 +101,19 @@ UnProtectHandle(IN HANDLE ObjectHandle)
     return FALSE;
 }
 
+/*++
+ * @name CsrAllocateThread
+ *
+ * The CsrAllocateThread routine allocates a new CSR Thread object.
+ *
+ * @param CsrProcess
+ *        Pointer to the CSR Process which will contain this CSR Thread.
+ *
+ * @return Pointer to the newly allocated CSR Thread.
+ *
+ * @remarks None.
+ *
+ *--*/
 PCSR_THREAD
 NTAPI
 CsrAllocateThread(IN PCSR_PROCESS CsrProcess)
@@ -125,7 +138,7 @@ CsrAllocateThread(IN PCSR_PROCESS CsrProcess)
 /*++
  * @name CsrLockedReferenceThread
  *
- * The CsrLockedReferenceThread refences a CSR Thread while the
+ * The CsrLockedReferenceThread references a CSR Thread while the
  * Process Lock is already being held.
  *
  * @param CsrThread
@@ -144,6 +157,26 @@ CsrLockedReferenceThread(IN PCSR_THREAD CsrThread)
     ++CsrThread->ReferenceCount;
 }
 
+/*++
+ * @name CsrLocateThreadByClientId
+ *
+ * The CsrLocateThreadByClientId routine locates the CSR Thread and,
+ * optionally, its parent CSR Process, corresponding to a Client ID.
+ *
+ * @param Process
+ *        Optional pointer to a CSR Process pointer which will contain
+ *        the CSR Thread's parent.
+ *
+ * @param ClientId
+ *        Pointer to a Client ID structure containing the Unique Thread ID
+ *        to look up.
+ *
+ * @return Pointer to the CSR Thread corresponding to this CID, or NULL if
+ *         none was found.
+ *
+ * @remarks None.
+ *
+ *--*/
 PCSR_THREAD
 NTAPI
 CsrLocateThreadByClientId(OUT PCSR_PROCESS *Process OPTIONAL,
@@ -152,6 +185,7 @@ CsrLocateThreadByClientId(OUT PCSR_PROCESS *Process OPTIONAL,
     ULONG i;
     PLIST_ENTRY ListHead, NextEntry;
     PCSR_THREAD FoundThread;
+    // ASSERT(ProcessStructureListLocked());
 
     /* Hash the Thread */
     i = CsrHashThread(ClientId->UniqueThread);
@@ -185,6 +219,27 @@ CsrLocateThreadByClientId(OUT PCSR_PROCESS *Process OPTIONAL,
     return NULL;
 }
 
+/*++
+ * @name CsrLocateThreadInProcess
+ *
+ * The CsrLocateThreadInProcess routine locates the CSR Thread
+ * corresponding to a Client ID inside a specific CSR Process.
+ *
+ * @param Process
+ *        Optional pointer to the CSR Process which contains the CSR Thread
+ *        that will be looked up.
+ *
+ * @param ClientId
+ *        Pointer to a Client ID structure containing the Unique Thread ID
+ *        to look up.
+ *
+ * @return Pointer to the CSR Thread corresponding to this CID, or NULL if
+ *         none was found.
+ *
+ * @remarks If the CsrProcess argument is NULL, the lookup will be done inside
+ *          CsrRootProcess.
+ *
+ *--*/
 PCSR_THREAD
 NTAPI
 CsrLocateThreadInProcess(IN PCSR_PROCESS CsrProcess OPTIONAL,
@@ -219,12 +274,30 @@ CsrLocateThreadInProcess(IN PCSR_PROCESS CsrProcess OPTIONAL,
     return FoundThread;
 }
 
+/*++
+ * @name CsrInsertThread
+ *
+ * The CsrInsertThread routine inserts a CSR Thread into its parent's
+ * Thread List and into the Thread Hash Table.
+ *
+ * @param Process
+ *        Pointer to the CSR Process containing this CSR Thread.
+ *
+ * @param Thread
+ *        Pointer to the CSR Thread to be inserted.
+ *
+ * @return None.
+ *
+ * @remarks None.
+ *
+ *--*/
 VOID
 NTAPI
 CsrInsertThread(IN PCSR_PROCESS Process,
                 IN PCSR_THREAD Thread)
 {
     ULONG i;
+    // ASSERT(ProcessStructureListLocked());
 
     /* Insert it into the Regular List */
     InsertTailList(&Process->ThreadList, &Thread->Link);
@@ -240,14 +313,49 @@ CsrInsertThread(IN PCSR_PROCESS Process,
     InsertHeadList(&CsrThreadHashTable[i], &Thread->HashLinks);
 }
 
+/*++
+ * @name CsrDeallocateThread
+ *
+ * The CsrDeallocateThread frees the memory associated with a CSR Thread.
+ *
+ * @param CsrThread
+ *        Pointer to the CSR Thread to be freed.
+ *
+ * @return None.
+ *
+ * @remarks Do not call this routine. It is reserved for the internal
+ *          thread management routines when a CSR Thread has been cleanly
+ *          dereferenced and killed.
+ *
+ *--*/
 VOID
 NTAPI
 CsrDeallocateThread(IN PCSR_THREAD CsrThread)
 {
     /* Free the process object from the heap */
+    // ASSERT(CsrThread->WaitBlock == NULL);
     RtlFreeHeap(CsrHeap, 0, CsrThread);
 }
 
+/*++
+ * @name CsrRemoveThread
+ *
+ * The CsrRemoveThread function undoes a CsrInsertThread operation and
+ * removes the CSR Thread from the the Hash Table and Thread List.
+ *
+ * @param CsrThread
+ *        Pointer to the CSR Thread to remove.
+ *
+ * @return None.
+ *
+ * @remarks If this CSR Thread is the last one inside a CSR Process, the
+ *          parent will be dereferenced and the CsrProcessLastThreadTerminated
+ *          flag will be set.
+ *
+ *          After executing this routine, the CSR Thread will have the
+ *          CsrThreadInTermination flag set.
+ *
+ *--*/
 VOID
 NTAPI
 CsrRemoveThread(IN PCSR_THREAD CsrThread)
@@ -297,7 +405,7 @@ CsrRemoveThread(IN PCSR_THREAD CsrThread)
  *        with this CSR Thread.
  *
  * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
- *         othwerwise.
+ *         otherwise.
  *
  * @remarks None.
  *
@@ -382,6 +490,24 @@ CsrCreateRemoteThread(IN HANDLE hThread,
     return STATUS_SUCCESS;
 }
 
+/*++
+ * @name CsrThreadRefcountZero
+ *
+ * The CsrThreadRefcountZero routine is executed when a CSR Thread has lost
+ * all its active references. It removes and de-allocates the CSR Thread.
+ *
+ * @param CsrThread
+ *        Pointer to the CSR Thread that is to be deleted.
+ *
+ * @return None.
+ *
+ * @remarks Do not call this routine. It is reserved for the internal
+ *          thread management routines when a CSR Thread has lost all
+ *          its references.
+ *
+ *          This routine is called with the Process Lock held.
+ *
+ *--*/
 VOID
 NTAPI
 CsrThreadRefcountZero(IN PCSR_THREAD CsrThread)
@@ -483,7 +609,7 @@ CsrDestroyThread(IN PCLIENT_ID Cid)
 /*++
  * @name CsrLockedDereferenceThread
  *
- * The CsrLockedDereferenceThread derefences a CSR Thread while the
+ * The CsrLockedDereferenceThread dereferences a CSR Thread while the
  * Process Lock is already being held.
  *
  * @param CsrThread
@@ -511,6 +637,29 @@ CsrLockedDereferenceThread(IN PCSR_THREAD CsrThread)
     }
 }
 
+/*++
+ * @name CsrCreateThread
+ * @implemented NT4
+ *
+ * The CsrCreateThread routine creates a CSR Thread object for an NT Thread.
+ *
+ * @param CsrProcess
+ *        Pointer to the CSR Process which will contain the CSR Thread.
+ *
+ * @param hThread
+ *        Handle to an existing NT Thread to which to associate this
+ *        CSR Thread.
+ *
+ * @param ClientId
+ *        Pointer to the Client ID structure of the NT Thread to associate
+ *        with this CSR Thread.
+ *
+ * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
+ *         otherwise.
+ *
+ * @remarks None.
+ *
+ *--*/
 NTSTATUS
 NTAPI
 CsrCreateThread(IN PCSR_PROCESS CsrProcess,
index 6fba748..1852c9d 100644 (file)
@@ -40,7 +40,7 @@ RTL_CRITICAL_SECTION CsrWaitListsLock;
  * @param NewWaitBlock
  *        Pointed to the initialized CSR Wait Block for this wait.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks None.
  *
@@ -262,7 +262,7 @@ CsrCreateWait(IN PLIST_ENTRY WaitList,
  * @name CsrDereferenceWait
  * @implemented NT4
  *
- * The CsrDereferenceWait routine derefences a CSR Wait Block.
+ * The CsrDereferenceWait routine dereferences a CSR Wait Block.
  *
  * @param WaitList
  *        Pointer to the Wait List associated to the wait.
@@ -394,7 +394,7 @@ CsrMoveSatisfiedWait(IN PLIST_ENTRY NewEntry,
  * @param WaitArgument[1-2]
  *        User-defined argument to pass on to the wait function.
  *
- * @return TRUE in case of success, FALSE othwerwise.
+ * @return TRUE in case of success, FALSE otherwise.
  *
  * @remarks None.
  *
index bdd7e56..776e96f 100644 (file)
@@ -1,5 +1,4 @@
-/* $Id$
- *
+/*
  * COPYRIGHT:       See COPYING in the top level directory
  * PROJECT:         ReactOS system libraries
  * FILE:            subsys/csrss/include/api.h
index d544651..be56642 100644 (file)
@@ -1,5 +1,4 @@
-/* $Id$
- *
+/*
  * COPYRIGHT:       See COPYING in the top level directory
  * PROJECT:         ReactOS system libraries
  * FILE:            subsys/csrss/include/csrplugin.h