Author: fireball
Date: Wed Jun 28 16:52:08 2006
New Revision: 22671
URL:
http://svn.reactos.org/svn/reactos?rev=22671&view=rev
Log:
[AUDIT]
- Add proper function headers, including links to documentation
- All exported functions have publically-available information sources
- The only internal function is actually quite self-explanatory by its name
- Implementation is partly wrong as pointed by Gunnar
Modified:
trunk/reactos/ntoskrnl/ex/atom.c (contents, props changed)
Modified: trunk/reactos/ntoskrnl/ex/atom.c
URL:
http://svn.reactos.org/svn/reactos/trunk/reactos/ntoskrnl/ex/atom.c?rev=226…
==============================================================================
--- trunk/reactos/ntoskrnl/ex/atom.c (original)
+++ trunk/reactos/ntoskrnl/ex/atom.c Wed Jun 28 16:52:08 2006
@@ -1,6 +1,6 @@
/*
- * COPYRIGHT: See COPYING in the top level directory
- * PROJECT: ReactOS kernel
+ * PROJECT: ReactOS Kernel
+ * COPYRIGHT: GPL - See COPYING in the top level directory
* FILE: ntoskrnl/ex/atom.c
* PURPOSE: Executive Atom Functions
* PROGRAMMERS: Alex Ionescu (alex(a)relsoft.net)
@@ -28,6 +28,17 @@
/* PRIVATE FUNCTIONS *********************************************************/
+/*++
+ * @name ExpGetGlobalAtomTable
+ *
+ * Gets pointer to a global atom table, creates it if not already created
+ *
+ * @return Pointer to the RTL_ATOM_TABLE, or NULL if it's impossible
+ * to create atom table
+ *
+ * @remarks Internal function
+ *
+ *--*/
PRTL_ATOM_TABLE
NTAPI
ExpGetGlobalAtomTable(VOID)
@@ -49,9 +60,29 @@
/* FUNCTIONS ****************************************************************/
-/*
+/*++
+ * @name NtAddAtom
* @implemented
- */
+ *
+ * Function NtAddAtom creates new Atom in Global Atom Table. If Atom
+ * with the same name already exist, internal Atom counter is incremented.
+ * See:
http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms…
+ *
+ * @param AtomName
+ * Atom name in Unicode
+ *
+ * @param AtomNameLength
+ * Length of the atom name
+ *
+ * @param Atom
+ * Pointer to RTL_ATOM
+ *
+ * @return STATUS_SUCCESS in case of success, proper error code
+ * othwerwise.
+ *
+ * @remarks None
+ *
+ *--*/
NTSTATUS
NTAPI
NtAddAtom(IN PWSTR AtomName,
@@ -151,9 +182,24 @@
return Status;
}
-/*
+/*++
+ * @name NtDeleteAtom
* @implemented
- */
+ *
+ * Removes Atom from Global Atom Table. If Atom's reference counter
+ * is greater then 1, function decrements this counter, but Atom
+ * stayed in Global Atom Table.
+ * See:
http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms…
+ *
+ * @param Atom
+ * Atom identifier
+ *
+ * @return STATUS_SUCCESS in case of success, proper error code
+ * othwerwise.
+ *
+ * @remarks None
+ *
+ *--*/
NTSTATUS
NTAPI
NtDeleteAtom(IN RTL_ATOM Atom)
@@ -168,9 +214,29 @@
return RtlDeleteAtomFromAtomTable(AtomTable, Atom);
}
-/*
+/*++
+ * @name NtFindAtom
* @implemented
- */
+ *
+ * Retrieves existing Atom's identifier without incrementing Atom's
+ * internal counter
+ * See:
http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms…
+ *
+ * @param AtomName
+ * Atom name in Unicode
+ *
+ * @param AtomNameLength
+ * Length of the atom name
+ *
+ * @param Atom
+ * Pointer to RTL_ATOM
+ *
+ * @return STATUS_SUCCESS in case of success, proper error code
+ * othwerwise.
+ *
+ * @remarks None
+ *
+ *--*/
NTSTATUS
NTAPI
NtFindAtom(IN PWSTR AtomName,
@@ -270,9 +336,36 @@
return Status;
}
-/*
+/*++
+ * @name NtQueryInformationAtom
* @implemented
- */
+ *
+ * Gets single Atom properties or reads Global Atom Table
+ * See:
http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms…
+ *
+ * @param Atom
+ * Atom to query. If AtomInformationClass parameter is
+ * AtomTableInformation, Atom parameter is not used.
+ *
+ * @param AtomInformationClass
+ * See ATOM_INFORMATION_CLASS enumeration type for details
+ *
+ * @param AtomInformation
+ * Result of call - pointer to user's allocated buffer for data
+ *
+ * @param AtomInformationLength
+ * Size of AtomInformation buffer, in bytes
+ *
+ * @param ReturnLength
+ * Pointer to ULONG value containing required AtomInformation
+ * buffer size
+ *
+ * @return STATUS_SUCCESS in case of success, proper error code
+ * othwerwise.
+ *
+ * @remarks None
+ *
+ *--*/
NTSTATUS
NTAPI
NtQueryInformationAtom(RTL_ATOM Atom,
Propchange: trunk/reactos/ntoskrnl/ex/atom.c
------------------------------------------------------------------------------
--- svn:needs-lock (original)
+++ svn:needs-lock (removed)
@@ -1,1 +1,0 @@
-*