[PATCH] Added documentation.
max at mtew.isa-geek.net
max at mtew.isa-geek.net
Tue Mar 8 17:37:41 CST 2011
From: Max TenEyck Woodbury <max at mtew.isa-geek.net>
---
dlls/ntdll/atom.c | 415 ++++++++++++++++++++++++++++++++++++++++++++++++++---
1 files changed, 393 insertions(+), 22 deletions(-)
diff --git a/dlls/ntdll/atom.c b/dlls/ntdll/atom.c
index 8ac4b97..7211820 100644
--- a/dlls/ntdll/atom.c
+++ b/dlls/ntdll/atom.c
@@ -43,12 +43,30 @@ 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.
+ *
+ * PARAMS
+ * atomstr [I] A pointer to the wchar_t atom name or the atom value.
+ * len [I] The length of atomstr.
+ * pAtom [O] A pointer to where the atom handle is stored.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if atomstr is an integral atom and pAtom is filled.
+ * Failure: STATUS_INVALID_PARAMETER if len is too big, or atom is zero or too
+ * big, STATUS_MORE_ENTRIES otherwise.
+ *
+ * PROCEDURE
+ * If atomstr is a binary number in the correct range, use it as the atom
+ * value. Check the range of len. If atomstr starts with "#", the rest of
+ * atomstr is the decimal representation of the integral atom. Check the value
+ * of atom for range. Store the atom value at pAtom.
+ *
+ * DEFECTS
+ * Validity of pAtom not checked. Accessability of atomstr not checked.
*/
-static NTSTATUS is_integral_atom( LPCWSTR atomstr, size_t len, RTL_ATOM* pAtom )
+static NTSTATUS is_integral_atom( LPCWSTR atomstr, size_t len, RTL_ATOM* pAtom)
{
RTL_ATOM atom;
@@ -78,8 +96,30 @@ done:
/******************************************************************
* RtlDeleteAtomFromAtomTable (NTDLL.@)
+ * RtlDeleteAtomFromAtomTable (NTOSKRNL.@)
+ *
+ * Delete the atom from the atom table.
+ *
+ * PARAMS
+ * table [I] Handle of the atom table.
+ * atom [I] Handle of the atom to be deleted.
+ *
+ * RETURNS
+ * Failure: STATUS_INVALID_PARAMETER if 'table' is null.
+ * Success: Status from the Wine server request.
+ *
+ * PROCEDURE
+ * Check and convert 'table' handle. Send a 'delete_atom' request to the
+ * server.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlDeleteAtomFromAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
+NTSTATUS WINAPI RtlDeleteAtomFromAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom)
{
NTSTATUS status;
@@ -99,11 +139,26 @@ 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
+ * The size of the result in bytes.
+ *
+ * PARAMS
+ * buffer [O] Where to store the result.
+ * len [I] The effective size of buffer.
+ * atom [I] The integral atom handle.
+ *
+ * PROCEDURE
+ * Use sprintfW to convert 'atom' to a string, copy it to 'buffer' and
+ * truncated/terminate the result.
+ *
+ * DEFECTS
+ * Validity of buffer not checked.
*/
-static ULONG integral_atom_name(WCHAR* buffer, ULONG len, RTL_ATOM atom)
+static ULONG integral_atom_name( WCHAR* buffer, ULONG len, RTL_ATOM atom)
{
static const WCHAR fmt[] = {'#','%','u',0};
WCHAR tmp[16];
@@ -119,9 +174,43 @@ static ULONG integral_atom_name(WCHAR* buffer, ULONG len, RTL_ATOM atom)
/******************************************************************
* RtlQueryAtomInAtomTable (NTDLL.@)
+ * RtlQueryAtomInAtomTable (NTOSKRNL.@)
+ *
+ * Get the string and statistics associated with an atom handle from an atom
+ * table.
+ *
+ * PARAMS
+ * table [I] The atom table handle.
+ * atom [I] The atom handle.
+ * ref [O] Where to store the reference count.
+ * pin [O] Where to store the 'pinned' flag.
+ * name [O] Where to store the associated string.
+ * len [IO] The effective length of name and the length of the result.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if the atom was found or Other status values from
+ * the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if table or atom is null or
+ * STATUS_BUFFER_TOO_SMALL if 'len' is not big enough to hold the result.
+ *
+ * PROCEDURE
+ * Check the table and atom handles. Convert the table handle. If it is an
+ * integral atom, generate the result using integral_atom_name(), otherwise send
+ * a 'get_atom_information' request to the server. Set ref and pin.
+ * Truncate/terminate the returned name.
+ *
+ * DEFECTS
+ * Accessability of ref, pin, name and len not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-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, RTL_ATOM atom,
+ ULONG* ref, ULONG* pin, WCHAR* name, ULONG* len)
{
NTSTATUS status = STATUS_SUCCESS;
DWORD wlen = 0;
@@ -170,8 +259,36 @@ NTSTATUS WINAPI RtlQueryAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom, UL
/******************************************************************
* RtlCreateAtomTable (NTDLL.@)
+ * RtlCreateAtomTable (NTSKRNL.@)
+ *
+ * Create an atom table.
+ *
+ * PARAMS
+ * size [I] The desired atom table size.
+ * table [O] Where to store the atom table handle.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if the atom table handle is already set or other
+ * status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if 'size' is non-zero and the atom table
+ * handle is set.
+ *
+ * PROCEDURE
+ * Check table and size. If table is not already set, Send an
+ * 'init_atom_table' request to the server. Convert the table address returned
+ * by the server to a handle and save the atom table handle in table.
+ *
+ * DEFECTS
+ * Accessability of table not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlCreateAtomTable( ULONG size, RTL_ATOM_TABLE* table )
+NTSTATUS WINAPI RtlCreateAtomTable( ULONG size, RTL_ATOM_TABLE* table)
{
NTSTATUS status;
@@ -195,8 +312,27 @@ NTSTATUS WINAPI RtlCreateAtomTable( ULONG size, RTL_ATOM_TABLE* table )
/******************************************************************
* RtlDestroyAtomTable (NTDLL.@)
+ * RtlDestroyAtomTable (NTOSKRNL.@)
+ *
+ * Discontinue using an atom table.
+ *
+ * PARAMS
+ * table [I] The atom table handle.
+ *
+ * RETURNS
+ * Status from NtClose.
+ *
+ * PROCEDURE
+ * Close table.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlDestroyAtomTable( RTL_ATOM_TABLE table )
+NTSTATUS WINAPI RtlDestroyAtomTable( RTL_ATOM_TABLE table)
{
if (!table) return STATUS_INVALID_PARAMETER;
return NtClose( table );
@@ -204,8 +340,38 @@ NTSTATUS WINAPI RtlDestroyAtomTable( RTL_ATOM_TABLE table )
/******************************************************************
* RtlAddAtomToAtomTable (NTDLL.@)
+ * RtlAddAtomToAtomTable (NTOSKRNL.@)
+ *
+ * Add a name to an atom table.
+ *
+ * PARAMS
+ * table [I] Atom table handle.
+ * name [I] The name of the atom.
+ * atom [O] Where to store the new atom handle.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if atom was added to the atom table or other status
+ * values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER is 'table' is not set or 'name' has a bad
+ * value.
+ *
+ * PROCEDURE
+ * Check 'table'. Try for an integral atom using is_integral_atom(). If that
+ * fails, convert the table handle and send an 'add_atom' to the server and store
+ * the result in 'atom'.
+ *
+ * DEFECTS
+ * Validity of 'atom' not checked. Accessability of 'name' not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlAddAtomToAtomTable( RTL_ATOM_TABLE table, const WCHAR* name, RTL_ATOM* atom )
+NTSTATUS WINAPI RtlAddAtomToAtomTable( RTL_ATOM_TABLE table, const WCHAR* name,
+ RTL_ATOM* atom)
{
NTSTATUS status;
@@ -234,8 +400,37 @@ NTSTATUS WINAPI RtlAddAtomToAtomTable( RTL_ATOM_TABLE table, const WCHAR* name,
/******************************************************************
* RtlLookupAtomInAtomTable (NTDLL.@)
+ * RtlLookupAtomInAtomTable (NTOSKRNL.@)
+ *
+ * Find the atom handle associated with name in an atom table.
+ *
+ * PARAMS
+ * table [I] The atom table handle.
+ * name [I] The name to lookup.
+ * atom [O] Where to store the atom handle.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if the name is a valid integral atom name or other
+ * status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if table is null.
+ *
+ * PROCEDURE
+ * Check 'table'. Try for an integral atom using is_integral_atom(). If that
+ * fails, convert the table handle and send a 'find_atom' request to the server
+ * and store the result in atom.
+ *
+ * DEFECTS
+ * Validity of name and atom not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlLookupAtomInAtomTable( RTL_ATOM_TABLE table, const WCHAR* name, RTL_ATOM* atom )
+NTSTATUS WINAPI RtlLookupAtomInAtomTable( RTL_ATOM_TABLE table,
+ const WCHAR* name, RTL_ATOM* atom)
{
NTSTATUS status;
@@ -263,8 +458,30 @@ NTSTATUS WINAPI RtlLookupAtomInAtomTable( RTL_ATOM_TABLE table, const WCHAR* nam
/******************************************************************
* RtlEmptyAtomTable (NTDLL.@)
+ * RtlEmptyAtomTable (NTOSKRNL.@)
+ *
+ * Delete all the entries in an atom table.
+ *
+ * PARAMS
+ * table [I] The table handle.
+ * delete_pinned [I] Are 'pinned' values to be deleted?
+ *
+ * RETURNS
+ * Success: Status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if table is null.
+ *
+ * PROCEDURE
+ * Check and convert the table handle. Send a 'delete_pinned' request to the
+ * server.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlEmptyAtomTable( RTL_ATOM_TABLE table, BOOLEAN delete_pinned )
+NTSTATUS WINAPI RtlEmptyAtomTable( RTL_ATOM_TABLE table, BOOLEAN delete_pinned)
{
NTSTATUS status;
@@ -284,8 +501,31 @@ NTSTATUS WINAPI RtlEmptyAtomTable( RTL_ATOM_TABLE table, BOOLEAN delete_pinned )
/******************************************************************
* RtlPinAtomInAtomTable (NTDLL.@)
+ * RtlPinAtomInAtomTable (NTOSKRNL.@)
+ *
+ * Designate an atom in an atom table as 'pinned'.
+ *
+ * PARAMS
+ * table [I] The atom table handle.
+ * atom [I] The atom handle of the atom to be 'pinned'.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if 'atom' is an integral atom or other status
+ * values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER is 'table' is null.
+ *
+ * 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.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-04.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI RtlPinAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
+NTSTATUS WINAPI RtlPinAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom)
{
NTSTATUS status;
@@ -310,8 +550,37 @@ NTSTATUS WINAPI RtlPinAtomInAtomTable( RTL_ATOM_TABLE table, RTL_ATOM atom )
/******************************************************************
* NtAddAtom (NTDLL.@)
+ * ZwAddAtom (NTDLL.@)
+ * NtAddAtom (NTOSKRNL.@)
+ *
+ * Insert a name into the global atom table.
+ *
+ * PARAMS
+ * name [I] The name to be added to the atom table.
+ * length [I] The length of the name.
+ * atom [O] Where to store the returned atom handle.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if name is an integral atom and atom is filled
+ * or status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if name is too long, atom is null or
+ * the number is too big.
+ *
+ * PROCEDURE
+ * Check for an integral atom. If that fails, send an 'add_atom' request to
+ * the server. Store the returned atom handle.
+ *
+ * DEFECTS
+ * Validity of 'name' and 'atom' are not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI NtAddAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
+NTSTATUS WINAPI NtAddAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom)
{
NTSTATUS status;
@@ -334,8 +603,29 @@ NTSTATUS WINAPI NtAddAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
/******************************************************************
* NtDeleteAtom (NTDLL.@)
+ * ZwDeleteAtom (NTDLL.@)
+ * NtDeleteAtom (NTOSKRNL.@)
+ *
+ * Delete the atom from the global atom table.
+ *
+ * PARAMS
+ * atom [I] The handle of the atom to be deleted.
+ *
+ * RETURNS
+ * Status values from the Wine server.
+ *
+ * PROCEDURE
+ * Send a 'delete_atom' request to the server.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI NtDeleteAtom(RTL_ATOM atom)
+NTSTATUS WINAPI NtDeleteAtom(
+ RTL_ATOM atom) /* The handle of the atom to be deleted. */
{
NTSTATUS status;
@@ -351,8 +641,37 @@ NTSTATUS WINAPI NtDeleteAtom(RTL_ATOM atom)
/******************************************************************
* NtFindAtom (NTDLL.@)
+ * ZwFindAtom (NTDLL.@)
+ * NtFindAtom (NTOSKRNL.@)
+ *
+ * Find the atom handle associated with a name in the global atom table.
+ *
+ * PARAMS
+ * name [I] The address of the name to find.
+ * length [I] The length of name.
+ * atom [O] Where to store the returned atom handle.
+ *
+ * RETURNS
+ * Success: STATUS_SUCCESS if 'name' is an integral atom and 'atom' is filled,
+ * or other status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if 'name' is too long, 'atom' is null or
+ * the number is too big.
+ *
+ * PROCEDURE
+ * Try for an integral atom using is_integral_atom(). If that fails, send a
+ * 'find_atom' request to the server. Store the returned atom handle.
+ *
+ * DEFECTS
+ * Validity of name and atom are not checked.
+ *
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI NtFindAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
+NTSTATUS WINAPI NtFindAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom)
{
NTSTATUS status;
@@ -375,9 +694,61 @@ NTSTATUS WINAPI NtFindAtom( const WCHAR* name, ULONG length, RTL_ATOM* atom )
/******************************************************************
* NtQueryInformationAtom (NTDLL.@)
+ * ZwQueryInformationAtom (NTDLL.@)
+ * NtQueryInformationAtom (NTOSKRNL.@)
+ *
+ * Get information about atoms in the global information table or global
+ * atom table information.
+ *
+ * PARAMS
+ * atom [I] The atom handle.
+ * class [I] The kind of information wanted. (See ENUMERATIONS below.)
+ * ptr [O] The address of the area to receive the information.
+ * size [I] The effective size of the area.
+ * psize [O] The size of the information put into the area.
+ *
+ * RETURNS
+ * Success: Status values from the Wine server.
+ * Failure: STATUS_INVALID_PARAMETER if 'size' is too small for Basic
+ * Information or STATUS_BUFFER_TOO_SMALL if size is too small for the result.
+ *
+ * PROCEDURE
+ * Dispatch on class.
+ * For class AtomBasicInformation, try for an integral atom using
+ * is_integral_atom(). If that failes, send a 'get_atom_information' to the
+ * server.
+ *
+ * DEFECTS
+ * class AtomTableInformation not implemented. Accessability of name and psize
+ * not checked.
+ *
+ * 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;
+ *|
+ * TESTS
+ * tests/atom.c
+ *
+ * HISTORY
+ * Apparently no public documented by Microsoft as of 20011-03-05.
+ * Added at NTDLL 4.0 and still available.
*/
-NTSTATUS WINAPI NtQueryInformationAtom( RTL_ATOM atom, ATOM_INFORMATION_CLASS class,
- PVOID ptr, ULONG size, PULONG psize )
+NTSTATUS WINAPI NtQueryInformationAtom( RTL_ATOM atom,
+ ATOM_INFORMATION_CLASS class, PVOID ptr, ULONG size, PULONG psize)
{
NTSTATUS status;
--
1.7.4
More information about the wine-patches
mailing list