[PATCH] NTDLL atom.c documentation.
max at mtew.isa-geek.net
max at mtew.isa-geek.net
Sun Mar 6 01:26:01 CST 2011
From: Max TenEyck Woodbury <max at mtew.isa-geek.net>
---
dlls/ntdll/atom.c | 348 +++++++++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 326 insertions(+), 22 deletions(-)
diff --git a/dlls/ntdll/atom.c b/dlls/ntdll/atom.c
index 8ac4b97..5b71b76 100644
--- a/dlls/ntdll/atom.c
+++ b/dlls/ntdll/atom.c
@@ -43,12 +43,26 @@ WINE_DEFAULT_DEBUG_CHANNEL(atom);
#define IS_INTATOM(x) (((ULONG_PTR)(x) >> 16) == 0)
/******************************************************************
- * is_integral_atom
- * Returns STATUS_SUCCESS if integral atom and 'pAtom' is filled
- * STATUS_INVALID_PARAMETER if 'atomstr' is too long
- * STATUS_MORE_ENTRIES otherwise
+ * is_integral_atom {NTDLL}
+ *
+ * Internal use. Check an 'integer atom' name for validity.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_SUCCESS if 'atomstr' is an integral atom and 'pAtom' is filled.
+ *| STATUS_INVALID_PARAMETER if 'atomstr' is too long, 'pAtom' is null or
+ *| the number is too big.
+ *| STATUS_MORE_ENTRIES otherwise
+ * DEFECTS
+ * Validity of pAtom not checked. Accessability of 'atomstr' not checked.
+ * PROCEDURE
+ * Convert the digits following the "#" in 'name' as a decimal number and
+ * check the result against the valid range, otherwise treat it as a binary
+ * number.
*/
-static NTSTATUS is_integral_atom( LPCWSTR atomstr, size_t len, RTL_ATOM* pAtom )
+static NTSTATUS is_integral_atom(
+ LPCWSTR atomstr, /* a pointer to the wchar_t atom name. */
+ size_t len, /* the length of 'atomstr'. */
+ RTL_ATOM* pAtom) /* a pointer to where the 'atom' is stored. */
{
RTL_ATOM atom;
@@ -78,8 +92,26 @@ done:
/******************************************************************
* RtlDeleteAtomFromAtomTable (NTDLL.@)
+ * Delete the atom 'atom' from the atom table 'table'.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER if 'table' is null.
+ *| status from the Wine server request.
+ * FORWARDS
+ *| From ntoskrnl.exe:RtlDeleteAtomFromAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export added at NTDLL 4.0.
+ * PROCEDURE
+ * Check and convert 'table' handle. Send a 'delete_atom' request to the
+ * server.
*/
-NTSTATUS WINAPI RtlDeleteAtomFromAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
+NTSTATUS WINAPI RtlDeleteAtomFromAtomTable(
+ RTL_ATOM_TABLE table, /* Handle for the atom table. */
+ RTL_ATOM atom) /* Handle for the atom. */
{
NTSTATUS status;
@@ -99,11 +131,22 @@ NTSTATUS WINAPI RtlDeleteAtomFromAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom
}
/******************************************************************
- * integral_atom_name (internal)
+ * integral_atom_name {NTDLL}
*
- * Helper for fetching integral (local/global) atoms names.
+ * Internal use. Convert an 'integeal atom' handle to a displayable/usable form.
+ * RETURNS
+ *| Type ULONG.
+ *| The size of the result in bytes.
+ * DEFECTS
+ * Validity of 'buffer' not checked.
+ * PROCEDURE
+ * Use sprintfW to convert 'atom' to a string, copy it to 'buffer' and
+ * truncated/terminate the result.
*/
-static ULONG integral_atom_name(WCHAR* buffer, ULONG len, RTL_ATOM atom)
+static ULONG integral_atom_name(
+ WCHAR* buffer, /* Where to store the result. */
+ ULONG len, /* The effective size of 'buffer'. */
+ RTL_ATOM atom) /* The atom handle. */
{
static const WCHAR fmt[] = {'#','%','u',0};
WCHAR tmp[16];
@@ -119,9 +162,38 @@ static ULONG integral_atom_name(WCHAR* buffer, ULONG len, RTL_ATOM atom)
/******************************************************************
* RtlQueryAtomInAtomTable (NTDLL.@)
+ * DESCRIPTION
+ * Get the string and statistics associated with an atom handle from an atom
+ * table.
+ * RETURNS
+ * Type NTSTATUS.
+ * STATUS_INVALID_PARAMETER if 'table' or 'atom' is null.
+ * STATUS_BUFFER_TOO_SMALL if 'len' is not big enough to hold the result.
+ * STATUS_SUCCESS if the atom was found.
+ * Other status values from the Wine server.
+ * PROCEDURE
+ * Check the 'table' and 'atom' handles. Convert the 'table' handle. If it
+ * is an integral atom, generate the result, otherwise send a
+ * 'get_atom_information' request to the server. Set 'ref' and 'pin'.
+ * Truncate/terminate returned 'name'.
+ * DEFECTS
+ * Accessability of 'ref', 'pin', 'name' and 'len' not checked.
+ * FORWARDS FROM
+ *| ntoskrnl.exe
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
*/
-NTSTATUS WINAPI RtlQueryAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom, ULONG* ref,
- ULONG* pin, WCHAR* name, ULONG* len )
+NTSTATUS WINAPI RtlQueryAtomInAtomTable(
+ RTL_ATOM_TABLE table, /* The atom table handle. */
+ RTL_ATOM atom, /* The atom handle. */
+ ULONG* ref, /* Reference count of 'atom'. */
+ ULONG* pin, /* Pinned attribute of 'atom'. */
+ WCHAR* name, /* Where to store the associated string. */
+ ULONG* len ) /* The effective size of 'name'. */
{
NTSTATUS status = STATUS_SUCCESS;
DWORD wlen = 0;
@@ -170,8 +242,31 @@ NTSTATUS WINAPI RtlQueryAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom, UL
/******************************************************************
* RtlCreateAtomTable (NTDLL.@)
+ * Create an atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER if 'size' is non-zero and the atom table handle
+ *| is set.
+ *| STATUS_SUCCESS if the atom table handle is already set.
+ *| Other status values from the Wine server.
+ * DEFECTS
+ * Accessability of 'table' not checked.
+ * FORWARDS
+ *| From ntoskrnl.exe:RtlCreateAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Check 'table' and 'size'. If 'table' is not already set, Send an
+ * 'init_atom_table' request to the server. Convert the table returned by the
+ * server to a handle and save the atom table handle in 'table'.
*/
-NTSTATUS WINAPI RtlCreateAtomTable( ULONG size, RTL_ATOM_TABLE* table )
+NTSTATUS WINAPI RtlCreateAtomTable(
+ ULONG size, /* The desired atom table size. */
+ RTL_ATOM_TABLE* table) /* Where to store the atom table handle. */
{
NTSTATUS status;
@@ -195,8 +290,24 @@ NTSTATUS WINAPI RtlCreateAtomTable( ULONG size, RTL_ATOM_TABLE* table )
/******************************************************************
* RtlDestroyAtomTable (NTDLL.@)
+ *
+ * Discontinue using an atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| Status from NtClose.
+ * FORWARDS
+ * From ntoskrnl.exe:RtlDestroyAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Close 'table'.
*/
-NTSTATUS WINAPI RtlDestroyAtomTable( RTL_ATOM_TABLE table )
+NTSTATUS WINAPI RtlDestroyAtomTable(
+ RTL_ATOM_TABLE table) /* The atom table handle. */
{
if (!table) return STATUS_INVALID_PARAMETER;
return NtClose( table );
@@ -204,8 +315,30 @@ NTSTATUS WINAPI RtlDestroyAtomTable( RTL_ATOM_TABLE table )
/******************************************************************
* RtlAddAtomToAtomTable (NTDLL.@)
+ * Add a name to an atom table.
+ * RETURNS
+ *| Type NTSTATUS
+ *| STATUS_SUCCESS if 'atom' was added to atom table 'table'.
+ *| STATUS_INVALID_PARAMETER is 'table' is not set or 'name' has a bad value.
+ *| Other status values from the Wine server.
+ * DEFECTS
+ * Validity of 'atom' not checked. Accessability of 'name' not checked.
+ * FORWARDS
+ *| from ntoskrnl.exe:RtlAddAtomToAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Check 'table'. Try for an integral atom. If that fails, convert 'table'
+ * handle and send an 'add_atom' to the server and store the result in 'atom'.
*/
-NTSTATUS WINAPI RtlAddAtomToAtomTable( RTL_ATOM_TABLE table, const WCHAR* name, RTL_ATOM* atom )
+NTSTATUS WINAPI RtlAddAtomToAtomTable(
+ RTL_ATOM_TABLE table, /* The atom table handle. */
+ const WCHAR* name, /* The name of the atom. */
+ RTL_ATOM* atom) /* Where to store the atom handle. */
{
NTSTATUS status;
@@ -234,8 +367,33 @@ NTSTATUS WINAPI RtlAddAtomToAtomTable( RTL_ATOM_TABLE table, const WCHAR* name,
/******************************************************************
* RtlLookupAtomInAtomTable (NTDLL.@)
+ *
+ * Find the atom handle associated with name in an atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER if 'table' is null.
+ *| STATUS_SUCCESS if the name is a valid integral atom name.
+ *| Other status values from the Wine server.
+ * DEFECTS
+ * Validity of 'name' and 'atom' not checked. Accessability of 'table' not
+ * checked.
+ * FORWARDS
+ *| From ntoskrnl.exe:RtlLookupAtomInAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Check 'table'. Try for an integral atom. If that fails, convert 'table'
+ * handle and send a 'find_atom' request to the server and store the result in
+ * 'atom'.
*/
-NTSTATUS WINAPI RtlLookupAtomInAtomTable( RTL_ATOM_TABLE table, const WCHAR* name, RTL_ATOM* atom )
+NTSTATUS WINAPI RtlLookupAtomInAtomTable(
+ RTL_ATOM_TABLE table, /* The atom table handle. */
+ const WCHAR* name, /* The address of the name to lookup. */
+ RTL_ATOM* atom) /* Where the atom handle is to be stored. */
{
NTSTATUS status;
@@ -263,8 +421,26 @@ NTSTATUS WINAPI RtlLookupAtomInAtomTable( RTL_ATOM_TABLE table, const WCHAR* nam
/******************************************************************
* RtlEmptyAtomTable (NTDLL.@)
+ *
+ * Release all the entries in an atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER if 'table' is null.
+ *| Other status values from the Wine server.
+ * FORWARDS
+ * From ntoskrnl.exe:RtlEmptyAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Check and convert 'table'. Send a 'delete_pinned' request to the server.
*/
-NTSTATUS WINAPI RtlEmptyAtomTable( RTL_ATOM_TABLE table, BOOLEAN delete_pinned )
+NTSTATUS WINAPI RtlEmptyAtomTable(
+ RTL_ATOM_TABLE table, /* The table handle. */
+ BOOLEAN delete_pinned) /* Are 'pinned' values to be deleted? */
{
NTSTATUS status;
@@ -284,8 +460,28 @@ NTSTATUS WINAPI RtlEmptyAtomTable( RTL_ATOM_TABLE table, BOOLEAN delete_pinned )
/******************************************************************
* RtlPinAtomInAtomTable (NTDLL.@)
+ *
+ * Designate an atom in an atom table as 'pinned'.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER is 'table' is null.
+ *| STATUS_SUCCESS if 'atom' is an integral atom.
+ *| Other status values from the Wine server.
+ * FORWARDS
+ * From ntoskrnl.exe:RtlPinAtomInAtomTable.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE.
+ * Check 'table'. Check for an integral atom. If not an integral atom,
+ * convert 'handle' and send a 'set_atom_information' request to the server.
*/
-NTSTATUS WINAPI RtlPinAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
+NTSTATUS WINAPI RtlPinAtomInAtomTable(
+ RTL_ATOM_TABLE table, /* The table handle. */
+ RTL_ATOM atom) /* The atom handle. */
{
NTSTATUS status;
@@ -310,8 +506,32 @@ NTSTATUS WINAPI RtlPinAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
/******************************************************************
* NtAddAtom (NTDLL.@)
+ * Insert a name into the global atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_SUCCESS if 'name' is an integral atom and 'atom' is filled.
+ *| STATUS_INVALID_PARAMETER if 'name' is too long, 'atom' is null or
+ *| the number is too big.
+ *| Status values from the Wine server.
+ * DEFECTS
+ * Validity of 'name' and 'atom' are not checked.
+ * FORWARDS
+ *| From ntoskrnl.exe:NtAddAtom.
+ *| From ntdll:ZwAddAtom.
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Check for an integral atom. If that fails, send an 'add_atom' request to
+ * the server. Store the returned atom handle.
*/
-NTSTATUS WINAPI NtAddAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
+NTSTATUS WINAPI NtAddAtom(
+ const WCHAR* name, /* The address of the name to be added. */
+ ULONG length, /* The length of the name to be added. */
+ RTL_ATOM* atom) /* Where to store the returned atom handle. */
{
NTSTATUS status;
@@ -334,8 +554,24 @@ NTSTATUS WINAPI NtAddAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
/******************************************************************
* NtDeleteAtom (NTDLL.@)
+ * Delete the atom from the global atom table.
+ * RETURNS
+ *| Type NTSTATUS
+ *| Status values from the Wine server.
+ * FORWARDS
+ *| From ntoskrnl.exe:NtDeleteAtom
+ *| From ntdll:ZwDeleteAtom
+ * TESTS
+ * tests/atom.c
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Send a 'delete_atom' request to the server.
*/
-NTSTATUS WINAPI NtDeleteAtom(RTL_ATOM atom)
+NTSTATUS WINAPI NtDeleteAtom(
+ RTL_ATOM atom) /* The handle of the atom to be deleted. */
{
NTSTATUS status;
@@ -351,8 +587,32 @@ NTSTATUS WINAPI NtDeleteAtom(RTL_ATOM atom)
/******************************************************************
* NtFindAtom (NTDLL.@)
+ * Find the atom handle associated with a name in the global atom table.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_SUCCESS if 'name' is an integral atom and 'atom' is filled.
+ *| STATUS_INVALID_PARAMETER if 'name' is too long, 'atom' is null or
+ *| the number is too big.
+ *| Other status values from the Wine server.
+ * FORWARDS
+ *| From ntoskrnl.exe:NtFindAtom
+ *| From ntdll:ZwFindAtom
+ * TESTS
+ * tests/atom.c
+ * DEFECTS
+ * Validity of 'name' and 'atom' are not checked.
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Try for an integral atom. If that fails, send a 'find_atom' request to
+ * the server. Store the returned atom handle.
*/
-NTSTATUS WINAPI NtFindAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
+NTSTATUS WINAPI NtFindAtom(
+ const WCHAR* name, /* The address of the name to find. */
+ ULONG length, /* The length of the name to find. */
+ RTL_ATOM* atom) /* Where to store the returned atom handle. */
{
NTSTATUS status;
@@ -375,9 +635,53 @@ NTSTATUS WINAPI NtFindAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
/******************************************************************
* NtQueryInformationAtom (NTDLL.@)
+ * Get information about atoms in the global information table or global
+ * atom table information.
+ * RETURNS
+ *| Type NTSTATUS.
+ *| STATUS_INVALID_PARAMETER if 'size' is too small for Basic Information.
+ *| STATUS_BUFFER_TOO_SMALL if 'size' is too small for the result.
+ *| Other status values from the Wine server.
+ * ENUMERATIONS
+ *| 'class'
+ *| AtomBasicInformation - Get information about a particular atom.
+ *| AtomTableInformation - Get information about the global atom table.
+ * STRUCTURES
+ *| typedef struct _ATOM_BASIC_INFORMATION {
+ *| USHORT UsageCount; USHORT Flags;
+ *| USHORT NameLength; WCHAR Name[1];
+ *| } ATOM_BASIC_INFORMATION, *PATOM_BASIC_INFORMATION;
+ *| Flags bits:
+ *| 0 Probably 'pinned'.
+ *| NameLength is in bytes.
+ *|
+ *| typedef struct _ATOM_TABLE_INFORMATION {
+ *| ULONG NumberOfAtoms; RTL_ATOM Atoms[1];
+ *| } ATOM_TABLE_INFORMATION, *PATOM_TABLE_INFORMATION;
+ *|
+ * FORWARDS
+ *| From ntoskrnl.exe:NtQueryInformationAtom
+ *| From ntdll:ZwQueryInformationAtom
+ * TESTS
+ * tests/atom.c
+ * DEFECTS
+ * 'class' AtomTableInformation not implemented.
+ * Accessability of 'name' and 'psize' not checked.
+ * SEARCH
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
+ * lists it as an undocumented named export for NTDLL 4.0.
+ * PROCEDURE
+ * Dispatch on 'class'.
+ * For AtomBasicInformation, try for an integral atom. If that failes, send
+ * a 'get_atom_information' to the server.
*/
-NTSTATUS WINAPI NtQueryInformationAtom( RTL_ATOM atom, ATOM_INFORMATION_CLASS class,
- PVOID ptr, ULONG size, PULONG psize )
+NTSTATUS WINAPI NtQueryInformationAtom(
+ RTL_ATOM atom, /* The atom handle being checked. */
+ ATOM_INFORMATION_CLASS class, /* The kind of information wanted. */
+ PVOID ptr, /* Where the results are to be stored. */
+ ULONG size, /* The usable size of the result store. */
+ PULONG psize) /* Where to store the actual result size. */
{
NTSTATUS status;
--
1.7.4
More information about the wine-patches
mailing list