Hi,
More documentation updates.
Cheers,
Jon
Changelog:
Jon Griffiths <jon_p_griffiths@yahoo.com>
+dlls/advapi32/security.c dlls/shlwapi/ordinal.c
dlls/shlwapi/string.c dlls/ntdll/large_int.c
dlls/kernel/atom.c loader/module.c
dlls/gdi/wing.c
Documentation updates
__________________________________
Do you Yahoo!?
The New Yahoo! Shopping - with improved product search
http://shopping.yahoo.com--- wine/dlls/advapi32/security.c 2003-09-23 19:44:29.000000000 +0100
+++ wine-develop/dlls/advapi32/security.c 2003-09-27 09:40:56.000000000 +0100
@@ -817,7 +817,7 @@
* PARAMS
* lpSystemName [I] Name of the system
* lpName [I] Name of the privilege
- * pLuid [O] Destination for the resulting LUD
+ * pLuid [O] Destination for the resulting LUID
*
* RETURNS
* Success: TRUE. pLuid contains the requested LUID.
--- wine/dlls/shlwapi/ordinal.c 2003-09-11 17:11:13.000000000 +0100
+++ wine-develop/dlls/shlwapi/ordinal.c 2003-09-27 09:51:41.000000000 +0100
@@ -3970,6 +3961,16 @@
/*************************************************************************
* GetMenuPosFromID [SHLWAPI.@]
+ *
+ * Return the position of a menu item from its Id.
+ *
+ * PARAMS
+ * hMenu [I] Menu containing the item
+ * wID [I] Id of the menu item
+ *
+ * RETURNS
+ * Success: The index of the menu item in hMenu.
+ * Failure: -1, If the item is not found.
*/
INT WINAPI GetMenuPosFromID(HMENU hMenu, UINT wID)
{
--- wine/dlls/shlwapi/string.c 2003-09-11 17:11:13.000000000 +0100
+++ wine-develop/dlls/shlwapi/string.c 2003-09-27 09:55:46.000000000 +0100
@@ -1745,7 +1745,7 @@
}
/*************************************************************************
- * SHStrDupA
+ * SHStrDupA [SHLWAPI.@]
*
* Return a Unicode copy of a string, in memory allocated by CoTaskMemAlloc().
*
@@ -1812,7 +1812,7 @@
}
/*************************************************************************
- * SHStrDupW
+ * SHStrDupW [SHLWAPI.@]
*
* See SHStrDupA.
*/
--- wine/dlls/ntdll/large_int.c 2003-09-11 17:11:06.000000000 +0100
+++ wine-develop/dlls/ntdll/large_int.c 2003-09-27 10:31:31.000000000 +0100
@@ -39,6 +39,15 @@
/******************************************************************************
* RtlLargeIntegerAdd (NTDLL.@)
+ *
+ * Add two 64 bit integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to add to a.
+ *
+ * RETURNS
+ * The sum of a and b.
*/
LONGLONG WINAPI RtlLargeIntegerAdd( LONGLONG a, LONGLONG b )
{
@@ -48,6 +57,15 @@
/******************************************************************************
* RtlLargeIntegerSubtract (NTDLL.@)
+ *
+ * Multiply two 64 bit integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The product of a and b.
*/
LONGLONG WINAPI RtlLargeIntegerSubtract( LONGLONG a, LONGLONG b )
{
@@ -57,6 +75,14 @@
/******************************************************************************
* RtlLargeIntegerNegate (NTDLL.@)
+ *
+ * Negate a 64 bit integer.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ *
+ * RETURNS
+ * The value of a negated.
*/
LONGLONG WINAPI RtlLargeIntegerNegate( LONGLONG a )
{
@@ -66,6 +92,15 @@
/******************************************************************************
* RtlLargeIntegerShiftLeft (NTDLL.@)
+ *
+ * Perform a shift left on a 64 bit integer.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * count [I] Number of bits to shift by
+ *
+ * RETURNS
+ * The value of a following the shift.
*/
LONGLONG WINAPI RtlLargeIntegerShiftLeft( LONGLONG a, INT count )
{
@@ -75,6 +110,15 @@
/******************************************************************************
* RtlLargeIntegerShiftRight (NTDLL.@)
+ *
+ * Perform a shift right on a 64 bit integer.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * count [I] Number of bits to shift by
+ *
+ * RETURNS
+ * The value of a following the shift.
*/
LONGLONG WINAPI RtlLargeIntegerShiftRight( LONGLONG a, INT count )
{
@@ -84,6 +128,15 @@
/******************************************************************************
* RtlLargeIntegerArithmeticShift (NTDLL.@)
+ *
+ * Perform an arithmetic shift right on a 64 bit integer.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * count [I] Number of bits to shift by
+ *
+ * RETURNS
+ * The value of a following the shift.
*/
LONGLONG WINAPI RtlLargeIntegerArithmeticShift( LONGLONG a, INT count )
{
@@ -95,7 +148,18 @@
/******************************************************************************
* RtlLargeIntegerDivide (NTDLL.@)
*
- * FIXME: should it be signed division instead?
+ * Divide one 64 bit unsigned integer by another, with remainder.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to divide a by
+ * rem [O] Destination for remainder
+ *
+ * RETURNS
+ * The dividend of a and b. If rem is non-NULL it is set to the remainder.
+ *
+ * FIXME
+ * Should it be signed division instead?
*/
ULONGLONG WINAPI RtlLargeIntegerDivide( ULONGLONG a, ULONGLONG b, ULONGLONG *rem )
{
@@ -107,6 +171,14 @@
/******************************************************************************
* RtlConvertLongToLargeInteger (NTDLL.@)
+ *
+ * Convert a 32 bit integer into 64 bits.
+ *
+ * PARAMS
+ * a [I] Number to convert
+ *
+ * RETURNS
+ * a.
*/
LONGLONG WINAPI RtlConvertLongToLargeInteger( LONG a )
{
@@ -116,6 +188,14 @@
/******************************************************************************
* RtlConvertUlongToLargeInteger (NTDLL.@)
+ *
+ * Convert a 32 bit unsigned integer into 64 bits.
+ *
+ * PARAMS
+ * a [I] Number to convert
+ *
+ * RETURNS
+ * a.
*/
ULONGLONG WINAPI RtlConvertUlongToLargeInteger( ULONG a )
{
@@ -125,6 +205,15 @@
/******************************************************************************
* RtlEnlargedIntegerMultiply (NTDLL.@)
+ *
+ * Multiply two integers giving a 64 bit integer result.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The product of a and b.
*/
LONGLONG WINAPI RtlEnlargedIntegerMultiply( INT a, INT b )
{
@@ -134,6 +223,15 @@
/******************************************************************************
* RtlEnlargedUnsignedMultiply (NTDLL.@)
+ *
+ * Multiply two unsigned integers giving a 64 bit unsigned integer result.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The product of a and b.
*/
ULONGLONG WINAPI RtlEnlargedUnsignedMultiply( UINT a, UINT b )
{
@@ -143,6 +241,16 @@
/******************************************************************************
* RtlEnlargedUnsignedDivide (NTDLL.@)
+ *
+ * Divide one 64 bit unsigned integer by a 32 bit unsigned integer, with remainder.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to divide a by
+ * remptr [O] Destination for remainder
+ *
+ * RETURNS
+ * The dividend of a and b. If remptr is non-NULL it is set to the remainder.
*/
UINT WINAPI RtlEnlargedUnsignedDivide( ULONGLONG a, UINT b, UINT *remptr )
{
@@ -167,6 +275,16 @@
/******************************************************************************
* RtlExtendedLargeIntegerDivide (NTDLL.@)
+ *
+ * Divide one 64 bit integer by a 32 bit integer, with remainder.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to divide a by
+ * rem [O] Destination for remainder
+ *
+ * RETURNS
+ * The dividend of a and b. If rem is non-NULL it is set to the remainder.
*/
LONGLONG WINAPI RtlExtendedLargeIntegerDivide( LONGLONG a, INT b, INT *rem )
{
@@ -178,6 +296,15 @@
/******************************************************************************
* RtlExtendedIntegerMultiply (NTDLL.@)
+ *
+ * Multiply one 64 bit integer by another 32 bit integer.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The product of a and b.
*/
LONGLONG WINAPI RtlExtendedIntegerMultiply( LONGLONG a, INT b )
{
@@ -269,7 +396,7 @@
* DIFFERENCES
* - Accept base 0 as 10 instead of crashing as native function does.
* - The native function does produce garbage or STATUS_BUFFER_OVERFLOW for
- * base 2, 8 and 16 when the value is larger than 0xFFFFFFFF.
+ * base 2, 8 and 16 when the value is larger than 0xFFFFFFFF.
*/
NTSTATUS WINAPI RtlLargeIntegerToChar(
const ULONGLONG *value_ptr, /* [I] Pointer to the value to be converted */
@@ -383,6 +510,15 @@
/******************************************************************************
* _alldiv (NTDLL.@)
+ *
+ * Divide two 64 bit unsigned integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The dividend of a and b.
*/
LONGLONG WINAPI _alldiv( LONGLONG a, LONGLONG b )
{
@@ -392,6 +528,15 @@
/******************************************************************************
* _allmul (NTDLL.@)
+ *
+ * Multiply two 64 bit integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The product of a and b.
*/
LONGLONG WINAPI _allmul( LONGLONG a, LONGLONG b )
{
@@ -401,6 +546,15 @@
/******************************************************************************
* _allrem (NTDLL.@)
+ *
+ * Calculate the remainder after dividing two 64 bit integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to divide a by.
+ *
+ * RETURNS
+ * The remainder of a divided by b.
*/
LONGLONG WINAPI _allrem( LONGLONG a, LONGLONG b )
{
@@ -410,6 +564,15 @@
/******************************************************************************
* _aulldiv (NTDLL.@)
+ *
+ * Divide two 64 bit unsigned integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to multiply a by.
+ *
+ * RETURNS
+ * The dividend of a and b.
*/
ULONGLONG WINAPI _aulldiv( ULONGLONG a, ULONGLONG b )
{
@@ -419,6 +582,15 @@
/******************************************************************************
* _aullrem (NTDLL.@)
+ *
+ * Calculate the remainder after dividing two 64 bit unsigned integers.
+ *
+ * PARAMS
+ * a [I] Initial number.
+ * b [I] Number to divide a by.
+ *
+ * RETURNS
+ * The remainder of a divided by b.
*/
ULONGLONG WINAPI _aullrem( ULONGLONG a, ULONGLONG b )
{
--- wine/dlls/kernel/atom.c 2003-09-11 17:10:58.000000000 +0100
+++ wine-develop/dlls/kernel/atom.c 2003-09-27 10:53:19.000000000 +0100
@@ -387,6 +387,15 @@
/***********************************************************************
* InitAtomTable (KERNEL32.@)
+ *
+ * Initialise the global atom table.
+ *
+ * PARAMS
+ * entries [I] The number of entries to reserve in the table.
+ *
+ * RETURNS
+ * Success: TRUE.
+ * Failure: FALSE.
*/
BOOL WINAPI InitAtomTable( DWORD entries )
{
@@ -430,14 +439,14 @@
/***********************************************************************
* GlobalAddAtomA (KERNEL32.@)
*
- * Adds a character string to the global atom table and returns a unique
- * value identifying the string.
+ * Add a character string to the global atom table and return a unique
+ * value identifying it.
*
* RETURNS
- * Atom: Success
- * 0: Failure
+ * Success: The atom allocated to str.
+ * Failure: 0.
*/
-ATOM WINAPI GlobalAddAtomA( LPCSTR str /* [in] Pointer to string to add */ )
+ATOM WINAPI GlobalAddAtomA( LPCSTR str /* [in] String to add */ )
{
return ATOM_AddAtomA( str, FALSE );
}
@@ -445,14 +454,15 @@
/***********************************************************************
* AddAtomA (KERNEL32.@)
- * Adds a string to the atom table and returns the atom identifying the
- * string.
+ *
+ * Add a character string to the global atom table and return a unique
+ * value identifying it.
*
* RETURNS
- * Atom: Success
- * 0: Failure
+ * Success: The atom allocated to str.
+ * Failure: 0.
*/
-ATOM WINAPI AddAtomA( LPCSTR str /* [in] Pointer to string to add */ )
+ATOM WINAPI AddAtomA( LPCSTR str /* [in] String to add */ )
{
return ATOM_AddAtomA( str, TRUE );
}
@@ -484,6 +494,8 @@
/***********************************************************************
* GlobalAddAtomW (KERNEL32.@)
+ *
+ * Unicode version of GlobalAddAtomA.
*/
ATOM WINAPI GlobalAddAtomW( LPCWSTR str )
{
@@ -493,6 +505,8 @@
/***********************************************************************
* AddAtomW (KERNEL32.@)
+ *
+ * Unicode version of AddAtomA.
*/
ATOM WINAPI AddAtomW( LPCWSTR str )
{
@@ -519,12 +533,13 @@
/***********************************************************************
* GlobalDeleteAtom (KERNEL32.@)
- * Decrements the reference count of a string atom. If the count is
+ *
+ * Decrement the reference count of a string atom. If the count is
* zero, the string associated with the atom is removed from the table.
*
* RETURNS
- * 0: Success
- * Atom: Failure
+ * Success: 0.
+ * Failure: atom.
*/
ATOM WINAPI GlobalDeleteAtom( ATOM atom /* [in] Atom to delete */ )
{
@@ -534,12 +549,13 @@
/***********************************************************************
* DeleteAtom (KERNEL32.@)
- * Decrements the reference count of a string atom. If count becomes
+ *
+ * Decrement the reference count of a string atom. If the count becomes
* zero, the string associated with the atom is removed from the table.
*
* RETURNS
- * 0: Success
- * Atom: Failure
+ * Success: 0.
+ * Failure: atom
*/
ATOM WINAPI DeleteAtom( ATOM atom /* [in] Atom to delete */ )
{
@@ -576,12 +592,11 @@
/***********************************************************************
* GlobalFindAtomA (KERNEL32.@)
*
- * Searches the atom table for the string and returns the atom
- * associated with it.
+ * Get the atom associated with a string.
*
* RETURNS
- * Atom: Success
- * 0: Failure
+ * Success: The associated atom.
+ * Failure: 0.
*/
ATOM WINAPI GlobalFindAtomA( LPCSTR str /* [in] Pointer to string to search for */ )
{
@@ -590,12 +605,12 @@
/***********************************************************************
* FindAtomA (KERNEL32.@)
- * Searches the local atom table for the string and returns the atom
- * associated with that string.
+ *
+ * Get the atom associated with a string.
*
* RETURNS
- * Atom: Success
- * 0: Failure
+ * Success: The associated atom.
+ * Failure: 0.
*/
ATOM WINAPI FindAtomA( LPCSTR str /* [in] Pointer to string to find */ )
{
@@ -629,6 +644,8 @@
/***********************************************************************
* GlobalFindAtomW (KERNEL32.@)
+ *
+ * Unicode version of GlobalFindAtomA.
*/
ATOM WINAPI GlobalFindAtomW( LPCWSTR str )
{
@@ -638,6 +655,8 @@
/***********************************************************************
* FindAtomW (KERNEL32.@)
+ *
+ * Unicode version of FindAtomA.
*/
ATOM WINAPI FindAtomW( LPCWSTR str )
{
@@ -701,11 +720,11 @@
/***********************************************************************
* GlobalGetAtomNameA (KERNEL32.@)
*
- * Retrieves a copy of the string associated with an atom.
+ * Get a copy of the string associated with an atom.
*
* RETURNS
- * Length of string in characters: Success
- * 0: Failure
+ * Success: The length of the returned string in characters.
+ * Failure: 0.
*/
UINT WINAPI GlobalGetAtomNameA(
ATOM atom, /* [in] Atom identifier */
@@ -718,11 +737,12 @@
/***********************************************************************
* GetAtomNameA (KERNEL32.@)
- * Retrieves a copy of the string associated with the atom.
+ *
+ * Get a copy of the string associated with an atom.
*
* RETURNS
- * Length of string: Success
- * 0: Failure
+ * Success: The length of the returned string in characters.
+ * Failure: 0.
*/
UINT WINAPI GetAtomNameA(
ATOM atom, /* [in] Atom */
@@ -782,6 +802,8 @@
/***********************************************************************
* GlobalGetAtomNameW (KERNEL32.@)
+ *
+ * Unicode version of GlobalGetAtomNameA.
*/
UINT WINAPI GlobalGetAtomNameW( ATOM atom, LPWSTR buffer, INT count )
{
@@ -791,6 +813,8 @@
/***********************************************************************
* GetAtomNameW (KERNEL32.@)
+ *
+ * Unicode version of GetAtomNameA.
*/
UINT WINAPI GetAtomNameW( ATOM atom, LPWSTR buffer, INT count )
{
--- wine/dlls/gdi/wing.c 2002-11-21 21:50:05.000000000 +0000
+++ wine-develop/dlls/gdi/wing.c 2003-09-27 19:52:15.000000000 +0100
@@ -29,6 +29,19 @@
WINE_DEFAULT_DEBUG_CHANNEL(wing);
+/*************************************************************************
+ * WING {WING}
+ *
+ * The Windows Game dll provides a number of functions designed to allow
+ * programmers to bypass Gdi and write directly to video memory. The intention
+ * was to bolster the use of Windows as a gaming platform and remove the
+ * need for Dos based games using 32 bit Dos extenders.
+ *
+ * This initial approach could not compete with the performance of Dos games
+ * (such as Doom and Warcraft) at the time, and so this dll was eventually
+ * superceeded by DirectX. It should not be used by new applications, and is
+ * provided only for compatability with older Windows programs.
+ */
typedef enum WING_DITHER_TYPE
{
@@ -50,6 +63,15 @@
/***********************************************************************
* WinGCreateDC (WING.1001)
+ *
+ * Create a new WinG device context.
+ *
+ * PARAMS
+ * None.
+ *
+ * RETURNS
+ * Success: A handle to the created device context.
+ * Failure: A NULL handle.
*/
HDC16 WINAPI WinGCreateDC16(void)
{
@@ -59,6 +81,15 @@
/***********************************************************************
* WinGRecommendDIBFormat (WING.1002)
+ *
+ * Get the recommended format of bitmaps for the current display.
+ *
+ * PARAMS
+ * bmpi [O] Destination for format information
+ *
+ * RETURNS
+ * Success: TRUE. bmpi is filled with the best (fastest) bitmap format
+ * Failure: FALSE, if bmpi is NULL.
*/
BOOL16 WINAPI WinGRecommendDIBFormat16(BITMAPINFO *bmpi)
{
@@ -85,6 +116,17 @@
/***********************************************************************
* WinGCreateBitmap (WING.1003)
+ *
+ * Create a new WinG bitmap.
+ *
+ * PARAMS
+ * hdc [I] WinG device context
+ * bmpi [I] Information about the bitmap
+ * bits [I] Location of the bitmap image data
+ *
+ * RETURNS
+ * Success: A handle to the created bitmap.
+ * Failure: A NULL handle.
*/
HBITMAP16 WINAPI WinGCreateBitmap16(HDC16 hdc, BITMAPINFO *bmpi,
SEGPTR *bits)
@@ -116,6 +158,17 @@
/***********************************************************************
* WinGSetDIBColorTable (WING.1006)
+ *
+ * Set all or part of the color table for a WinG device context.
+ *
+ * PARAMS
+ * hdc [I] WinG device context
+ * start [I] Start color
+ * num [I] Number of entries to set
+ * colors [I] Array of color data
+ *
+ * RETURNS
+ * The number of entries set.
*/
UINT16 WINAPI WinGSetDIBColorTable16(HDC16 hdc, UINT16 start, UINT16 num,
RGBQUAD *colors)
@@ -126,6 +179,17 @@
/***********************************************************************
* WinGGetDIBColorTable (WING.1005)
+ *
+ * Get all or part of the color table for a WinG device context.
+ *
+ * PARAMS
+ * hdc [I] WinG device context
+ * start [I] Start color
+ * num [I] Number of entries to set
+ * colors [O] Destination for the array of color data
+ *
+ * RETURNS
+ * The number of entries retrieved.
*/
UINT16 WINAPI WinGGetDIBColorTable16(HDC16 hdc, UINT16 start, UINT16 num,
RGBQUAD *colors)
@@ -136,6 +200,15 @@
/***********************************************************************
* WinGCreateHalfTonePalette (WING.1007)
+ *
+ * Create a half tone palette.
+ *
+ * PARAMS
+ * None.
+ *
+ * RETURNS
+ * Success: A handle to the created palette.
+ * Failure: A NULL handle.
*/
HPALETTE16 WINAPI WinGCreateHalfTonePalette16(void)
{
@@ -148,6 +221,17 @@
/***********************************************************************
* WinGCreateHalfToneBrush (WING.1008)
+ *
+ * Create a half tone brush for a WinG device context.
+ *
+ * PARAMS
+ * winDC [I] WinG device context
+ * col [I] Color
+ * type [I] Desired dithering type.
+ *
+ * RETURNS
+ * Success: A handle to the created brush.
+ * Failure: A NULL handle.
*/
HBRUSH16 WINAPI WinGCreateHalfToneBrush16(HDC16 winDC, COLORREF col,
WING_DITHER_TYPE type)
@@ -158,6 +242,8 @@
/***********************************************************************
* WinGStretchBlt (WING.1009)
+ *
+ * See StretchBlt16.
*/
BOOL16 WINAPI WinGStretchBlt16(HDC16 destDC, INT16 xDest, INT16 yDest,
INT16 widDest, INT16 heiDest,
@@ -175,6 +261,8 @@
/***********************************************************************
* WinGBitBlt (WING.1010)
+ *
+ * See BitBlt16.
*/
BOOL16 WINAPI WinGBitBlt16(HDC16 destDC, INT16 xDest, INT16 yDest,
INT16 widDest, INT16 heiDest, HDC16 srcDC,
--- wine/loader/module.c 2003-09-29 22:32:11.000000000 +0100
+++ wine-t/loader/module.c 2003-09-30 08:19:49.000000000 +0100
@@ -55,7 +55,19 @@
/****************************************************************************
* DisableThreadLibraryCalls (KERNEL32.@)
*
- * Don't call DllEntryPoint for DLL_THREAD_{ATTACH,DETACH} if set.
+ * Inform the module loader that thread notifications are not required for a dll.
+ *
+ * PARAMS
+ * hModule [I] Module handle to skip calls for
+ *
+ * RETURNS
+ * Success: TRUE. Thread attach and detach notifications will not be sent
+ * to hModule.
+ * Failure: FALSE. Use GetLastError() to determine the cause.
+ *
+ * NOTES
+ * This is typically called from the dll entry point of a dll during process
+ * attachment, for dlls that do not need to process thread notifications.
*/
BOOL WINAPI DisableThreadLibraryCalls( HMODULE hModule )
{
@@ -243,32 +255,35 @@
* GetBinaryTypeA [KERNEL32.@]
* GetBinaryType [KERNEL32.@]
*
- * The GetBinaryType function determines whether a file is executable
- * or not and if it is it returns what type of executable it is.
- * The type of executable is a property that determines in which
- * subsystem an executable file runs under.
- *
- * Binary types returned:
- * SCS_32BIT_BINARY: A Win32 based application
- * SCS_DOS_BINARY: An MS-Dos based application
- * SCS_WOW_BINARY: A Win16 based application
- * SCS_PIF_BINARY: A PIF file that executes an MS-Dos based app
- * SCS_POSIX_BINARY: A POSIX based application ( Not implemented )
- * SCS_OS216_BINARY: A 16bit OS/2 based application
- *
- * Returns TRUE if the file is an executable in which case
- * the value pointed by lpBinaryType is set.
- * Returns FALSE if the file is not an executable or if the function fails.
- *
- * To do so it opens the file and reads in the header information
- * if the extended header information is not present it will
- * assume that the file is a DOS executable.
- * If the extended header information is present it will
- * determine if the file is a 16 or 32 bit Windows executable
- * by check the flags in the header.
+ * Determine whether a file is executable, and if so, what kind.
+ *
+ * PARAMS
+ * lpApplicationName [I] Path of the file to check
+ * lpBinaryType [O] Destination for the binary type
+ *
+ * RETURNS
+ * TRUE, if the file is an executable, in which case lpBinaryType is set.
+ * FALSE, if the file is not an executable or if the function fails.
*
- * Note that .COM and .PIF files are only recognized by their
- * file name extension; but Windows does it the same way ...
+ * NOTES
+ * The type of executable is a property that determines which subsytem an
+ * executable file runs under. lpBinaryType can be set to one of the following
+ * values:
+ * SCS_32BIT_BINARY: A Win32 based application
+ * SCS_DOS_BINARY: An MS-Dos based application
+ * SCS_WOW_BINARY: A Win16 based application
+ * SCS_PIF_BINARY: A PIF file that executes an MS-Dos based app
+ * SCS_POSIX_BINARY: A POSIX based application ( Not implemented )
+ * SCS_OS216_BINARY: A 16bit OS/2 based application
+ *
+ * To find the binary type, this function reads in the files header information.
+ * If extended header information is not present it will assume that the file
+ * is a DOS executable. If extended header information is present it will
+ * determine if the file is a 16 or 32 bit Windows executable by checking the
+ * flags in the header.
+ *
+ * ".com" and ".pif" files are only recognized by their file name extension,
+ * as per native Windows.
*/
BOOL WINAPI GetBinaryTypeA( LPCSTR lpApplicationName, LPDWORD lpBinaryType )
{
@@ -338,6 +353,8 @@
/***********************************************************************
* GetBinaryTypeW [KERNEL32.@]
+ *
+ * Unicode version of GetBinaryTypeA.
*/
BOOL WINAPI GetBinaryTypeW( LPCWSTR lpApplicationName, LPDWORD lpBinaryType )
{
@@ -371,6 +388,15 @@
/***********************************************************************
* GetModuleHandleA (KERNEL32.@)
* GetModuleHandle32 (KERNEL.488)
+ *
+ * Get the handle of a dll loaded into the process address space.
+ *
+ * PARAMS
+ * module [I] Name of the dll
+ *
+ * RETURNS
+ * Success: A handle to the loaded dll.
+ * Failure: A NULL handle. Use GetLastError() to determine the cause.
*/
HMODULE WINAPI GetModuleHandleA(LPCSTR module)
{
@@ -393,6 +419,8 @@
/***********************************************************************
* GetModuleHandleW (KERNEL32.@)
+ *
+ * Unicode version of GetModuleHandleA.
*/
HMODULE WINAPI GetModuleHandleW(LPCWSTR module)
{
@@ -417,15 +445,21 @@
* GetModuleFileNameA (KERNEL32.@)
* GetModuleFileName32 (KERNEL.487)
*
- * GetModuleFileNameA seems to *always* return the long path;
- * it's only GetModuleFileName16 that decides between short/long path
- * by checking if exe version >= 4.0.
- * (SDK docu doesn't mention this)
+ * Get the file name of a loaded module from its handle.
+ *
+ * RETURNS
+ * Success: The length of the file name, excluding the terminating NUL.
+ * Failure: 0. Use GetLastError() to determine the cause.
+ *
+ * NOTES
+ * This function always returns the long path of hModule (as opposed to
+ * GetModuleFileName16() which returns short paths when the modules version
+ * field is < 4.0).
*/
DWORD WINAPI GetModuleFileNameA(
- HMODULE hModule, /* [in] module handle (32bit) */
- LPSTR lpFileName, /* [out] filenamebuffer */
- DWORD size ) /* [in] size of filenamebuffer */
+ HMODULE hModule, /* [in] Module handle (32 bit) */
+ LPSTR lpFileName, /* [out] Destination for file name */
+ DWORD size ) /* [in] Size of lpFileName in characters */
{
LPWSTR filenameW = HeapAlloc( GetProcessHeap(), 0, size * sizeof(WCHAR) );
@@ -442,6 +476,8 @@
/***********************************************************************
* GetModuleFileNameW (KERNEL32.@)
+ *
+ * Unicode version of GetModuleFileNameA.
*/
DWORD WINAPI GetModuleFileNameW( HMODULE hModule, LPWSTR lpFileName, DWORD size )
{
@@ -522,11 +558,22 @@
/******************************************************************
* LoadLibraryExA (KERNEL32.@)
*
+ * Load a dll file into the process address space.
+ *
+ * PARAMS
+ * libname [I] Name of the file to load
+ * hfile [I] Reserved, must be 0.
+ * flags [I] Flags for loading the dll
+ *
+ * RETURNS
+ * Success: A handle to the loaded dll.
+ * Failure: A NULL handle. Use GetLastError() to determine the cause.
+ *
+ * NOTES
* The HFILE parameter is not used and marked reserved in the SDK. I can
* only guess that it should force a file to be mapped, but I rather
* ignore the parameter because it would be extremely difficult to
* integrate this with different types of module representations.
- *
*/
HMODULE WINAPI LoadLibraryExA(LPCSTR libname, HANDLE hfile, DWORD flags)
{
@@ -568,6 +615,8 @@
/***********************************************************************
* LoadLibraryExW (KERNEL32.@)
+ *
+ * Unicode version of LoadLibraryExA.
*/
HMODULE WINAPI LoadLibraryExW(LPCWSTR libnameW, HANDLE hfile, DWORD flags)
{
@@ -603,6 +652,18 @@
/***********************************************************************
* LoadLibraryA (KERNEL32.@)
+ *
+ * Load a dll file into the process address space.
+ *
+ * PARAMS
+ * libname [I] Name of the file to load
+ *
+ * RETURNS
+ * Success: A handle to the loaded dll.
+ * Failure: A NULL handle. Use GetLastError() to determine the cause.
+ *
+ * NOTES
+ * See LoadLibraryExA().
*/
HMODULE WINAPI LoadLibraryA(LPCSTR libname)
{
@@ -611,6 +672,8 @@
/***********************************************************************
* LoadLibraryW (KERNEL32.@)
+ *
+ * Unicode version of LoadLibraryA.
*/
HMODULE WINAPI LoadLibraryW(LPCWSTR libnameW)
{
@@ -620,6 +683,15 @@
/***********************************************************************
* FreeLibrary (KERNEL32.@)
* FreeLibrary32 (KERNEL.486)
+ *
+ * Free a dll loaded into the process address space.
+ *
+ * PARAMS
+ * hLibModule [I] Handle to the dll returned by LoadLibraryA().
+ *
+ * RETURNS
+ * Success: TRUE. The dll is removed if it is not still in use.
+ * Failure: FALSE. Use GetLastError() to determine the cause.
*/
BOOL WINAPI FreeLibrary(HINSTANCE hLibModule)
{
@@ -648,6 +720,16 @@
/***********************************************************************
* GetProcAddress (KERNEL32.@)
+ *
+ * Find the address of an exported symbol in a loaded dll.
+ *
+ * PARAMS
+ * hModule [I] Handle to the dll returned by LoadLibraryA().
+ * function [I] Name of the symbol, or an integer ordinal number < 16384
+ *
+ * RETURNS
+ * Success: A pointer to the symbol in the process address space.
+ * Failure: NULL. Use GetLastError() to determine the cause.
*/
FARPROC WINAPI GetProcAddress( HMODULE hModule, LPCSTR function )
{
@@ -673,6 +755,16 @@
/***********************************************************************
* GetProcAddress32 (KERNEL.453)
+ *
+ * Find the address of an exported symbol in a loaded dll.
+ *
+ * PARAMS
+ * hModule [I] Handle to the dll returned by LoadLibraryA().
+ * function [I] Name of the symbol, or an integer ordinal number < 16384
+ *
+ * RETURNS
+ * Success: A pointer to the symbol in the process address space.
+ * Failure: NULL. Use GetLastError() to determine the cause.
*/
FARPROC WINAPI GetProcAddress32_16( HMODULE hModule, LPCSTR function )
{
