From 4c1fa161a3b1bbf1691abaa8dd0637e4ad40f1f2 Mon Sep 17 00:00:00 2001 From: Jon Griffiths Date: Wed, 1 Oct 2003 03:20:21 +0000 Subject: [PATCH] Documentation updates. --- dlls/advapi32/security.c | 2 +- dlls/gdi/wing.c | 88 ++++++++++++++++++++ dlls/kernel/atom.c | 84 ++++++++++++------- dlls/ntdll/large_int.c | 176 ++++++++++++++++++++++++++++++++++++++- dlls/shlwapi/string.c | 4 +- loader/module.c | 154 +++++++++++++++++++++++++++------- 6 files changed, 442 insertions(+), 66 deletions(-) diff --git a/dlls/advapi32/security.c b/dlls/advapi32/security.c index a4614401d8..dd02b79ddd 100644 --- a/dlls/advapi32/security.c +++ b/dlls/advapi32/security.c @@ -817,7 +817,7 @@ LookupPrivilegeValueW( LPCWSTR lpSystemName, LPCWSTR lpName, PLUID lpLuid ) * 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. diff --git a/dlls/gdi/wing.c b/dlls/gdi/wing.c index 7a5a88e83c..1026d7ca4b 100644 --- a/dlls/gdi/wing.c +++ b/dlls/gdi/wing.c @@ -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 @@ typedef enum WING_DITHER_TYPE /*********************************************************************** * 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 @@ HDC16 WINAPI WinGCreateDC16(void) /*********************************************************************** * 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 @@ BOOL16 WINAPI WinGRecommendDIBFormat16(BITMAPINFO *bmpi) /*********************************************************************** * 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 @@ SEGPTR WINAPI WinGGetDIBPointer16(HBITMAP16 hWinGBitmap, BITMAPINFO* bmpi) /*********************************************************************** * 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 @@ UINT16 WINAPI WinGSetDIBColorTable16(HDC16 hdc, UINT16 start, UINT16 num, /*********************************************************************** * 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 @@ UINT16 WINAPI WinGGetDIBColorTable16(HDC16 hdc, UINT16 start, UINT16 num, /*********************************************************************** * 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 @@ HPALETTE16 WINAPI WinGCreateHalfTonePalette16(void) /*********************************************************************** * 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 @@ HBRUSH16 WINAPI WinGCreateHalfToneBrush16(HDC16 winDC, COLORREF col, /*********************************************************************** * WinGStretchBlt (WING.1009) + * + * See StretchBlt16. */ BOOL16 WINAPI WinGStretchBlt16(HDC16 destDC, INT16 xDest, INT16 yDest, INT16 widDest, INT16 heiDest, @@ -175,6 +261,8 @@ BOOL16 WINAPI WinGStretchBlt16(HDC16 destDC, INT16 xDest, INT16 yDest, /*********************************************************************** * WinGBitBlt (WING.1010) + * + * See BitBlt16. */ BOOL16 WINAPI WinGBitBlt16(HDC16 destDC, INT16 xDest, INT16 yDest, INT16 widDest, INT16 heiDest, HDC16 srcDC, diff --git a/dlls/kernel/atom.c b/dlls/kernel/atom.c index 618c0591bc..2915b3f5aa 100644 --- a/dlls/kernel/atom.c +++ b/dlls/kernel/atom.c @@ -387,6 +387,15 @@ UINT16 WINAPI GetAtomName16( ATOM atom, LPSTR buffer, INT16 count ) /*********************************************************************** * 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 @@ static ATOM ATOM_AddAtomA( LPCSTR str, BOOL local ) /*********************************************************************** * 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 @@ ATOM WINAPI GlobalAddAtomA( LPCSTR str /* [in] Pointer to string to add */ ) /*********************************************************************** * 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 @@ static ATOM ATOM_AddAtomW( LPCWSTR str, BOOL local ) /*********************************************************************** * GlobalAddAtomW (KERNEL32.@) + * + * Unicode version of GlobalAddAtomA. */ ATOM WINAPI GlobalAddAtomW( LPCWSTR str ) { @@ -493,6 +505,8 @@ ATOM WINAPI GlobalAddAtomW( LPCWSTR str ) /*********************************************************************** * AddAtomW (KERNEL32.@) + * + * Unicode version of AddAtomA. */ ATOM WINAPI AddAtomW( LPCWSTR str ) { @@ -519,12 +533,13 @@ static ATOM ATOM_DeleteAtom( ATOM atom, BOOL local) /*********************************************************************** * 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 @@ ATOM WINAPI GlobalDeleteAtom( ATOM atom /* [in] Atom to delete */ ) /*********************************************************************** * 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 @@ static ATOM ATOM_FindAtomA( LPCSTR str, BOOL local ) /*********************************************************************** * 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 @@ ATOM WINAPI GlobalFindAtomA( LPCSTR str /* [in] Pointer to string to search for /*********************************************************************** * 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 @@ static ATOM ATOM_FindAtomW( LPCWSTR str, BOOL local ) /*********************************************************************** * GlobalFindAtomW (KERNEL32.@) + * + * Unicode version of GlobalFindAtomA. */ ATOM WINAPI GlobalFindAtomW( LPCWSTR str ) { @@ -638,6 +655,8 @@ ATOM WINAPI GlobalFindAtomW( LPCWSTR str ) /*********************************************************************** * FindAtomW (KERNEL32.@) + * + * Unicode version of FindAtomA. */ ATOM WINAPI FindAtomW( LPCWSTR str ) { @@ -701,11 +720,11 @@ static UINT ATOM_GetAtomNameA( ATOM atom, LPSTR buffer, INT count, BOOL local ) /*********************************************************************** * 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 @@ UINT WINAPI GlobalGetAtomNameA( /*********************************************************************** * 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 @@ static UINT ATOM_GetAtomNameW( ATOM atom, LPWSTR buffer, INT count, BOOL local ) /*********************************************************************** * GlobalGetAtomNameW (KERNEL32.@) + * + * Unicode version of GlobalGetAtomNameA. */ UINT WINAPI GlobalGetAtomNameW( ATOM atom, LPWSTR buffer, INT count ) { @@ -791,6 +813,8 @@ UINT WINAPI GlobalGetAtomNameW( ATOM atom, LPWSTR buffer, INT count ) /*********************************************************************** * GetAtomNameW (KERNEL32.@) + * + * Unicode version of GetAtomNameA. */ UINT WINAPI GetAtomNameW( ATOM atom, LPWSTR buffer, INT count ) { diff --git a/dlls/ntdll/large_int.c b/dlls/ntdll/large_int.c index 1f52211d13..02bc584ec3 100644 --- a/dlls/ntdll/large_int.c +++ b/dlls/ntdll/large_int.c @@ -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 @@ LONGLONG WINAPI RtlLargeIntegerAdd( LONGLONG a, LONGLONG b ) /****************************************************************************** * RtlLargeIntegerSubtract (NTDLL.@) + * + * Subtract two 64 bit integers. + * + * PARAMS + * a [I] Initial number. + * b [I] Number to subtract from a. + * + * RETURNS + * The difference of a and b. */ LONGLONG WINAPI RtlLargeIntegerSubtract( LONGLONG a, LONGLONG b ) { @@ -57,6 +75,14 @@ LONGLONG WINAPI RtlLargeIntegerSubtract( LONGLONG a, LONGLONG b ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlLargeIntegerNegate( LONGLONG a ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlLargeIntegerShiftLeft( LONGLONG a, INT count ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlLargeIntegerShiftRight( LONGLONG a, INT count ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlLargeIntegerArithmeticShift( LONGLONG a, INT count ) /****************************************************************************** * 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 @@ ULONGLONG WINAPI RtlLargeIntegerDivide( ULONGLONG a, ULONGLONG b, ULONGLONG *rem /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlConvertLongToLargeInteger( LONG a ) /****************************************************************************** * 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 @@ ULONGLONG WINAPI RtlConvertUlongToLargeInteger( ULONG a ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlEnlargedIntegerMultiply( INT a, INT b ) /****************************************************************************** * 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 @@ ULONGLONG WINAPI RtlEnlargedUnsignedMultiply( UINT a, UINT b ) /****************************************************************************** * 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 @@ UINT WINAPI RtlEnlargedUnsignedDivide( ULONGLONG a, UINT b, UINT *remptr ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlExtendedLargeIntegerDivide( LONGLONG a, INT b, INT *rem ) /****************************************************************************** * 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 @@ LONGLONG WINAPI RtlExtendedMagicDivide( * 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 @@ NTSTATUS WINAPI RtlInt64ToUnicodeString( /****************************************************************************** * _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 @@ LONGLONG WINAPI _alldiv( LONGLONG a, LONGLONG b ) /****************************************************************************** * _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 @@ LONGLONG WINAPI _allmul( LONGLONG a, LONGLONG b ) /****************************************************************************** * _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 @@ LONGLONG WINAPI _allrem( LONGLONG a, LONGLONG b ) /****************************************************************************** * _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 @@ ULONGLONG WINAPI _aulldiv( ULONGLONG a, ULONGLONG b ) /****************************************************************************** * _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 ) { diff --git a/dlls/shlwapi/string.c b/dlls/shlwapi/string.c index 7c7b7f3750..b92d8de25c 100644 --- a/dlls/shlwapi/string.c +++ b/dlls/shlwapi/string.c @@ -1745,7 +1745,7 @@ static HRESULT WINAPI _SHStrDupAA(LPCSTR src, LPSTR * dest) } /************************************************************************* - * SHStrDupA + * SHStrDupA [SHLWAPI.@] * * Return a Unicode copy of a string, in memory allocated by CoTaskMemAlloc(). * @@ -1812,7 +1812,7 @@ static HRESULT WINAPI _SHStrDupAW(LPCWSTR src, LPSTR * dest) } /************************************************************************* - * SHStrDupW + * SHStrDupW [SHLWAPI.@] * * See SHStrDupA. */ diff --git a/loader/module.c b/loader/module.c index 07204fe59f..f32e13bcbc 100644 --- a/loader/module.c +++ b/loader/module.c @@ -55,7 +55,19 @@ WINE_DECLARE_DEBUG_CHANNEL(loaddll); /**************************************************************************** * 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 @@ enum binary_type MODULE_GetBinaryType( HANDLE hfile ) * 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. + * Determine whether a file is executable, and if so, what kind. * - * 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 + * 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 - * the value pointed by lpBinaryType is set. - * Returns FALSE if the file is not an executable or if the function fails. + * 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. * - * 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. + * 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 * - * Note that .COM and .PIF files are only recognized by their - * file name extension; but Windows does it the same way ... + * 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 @@ BOOL WINAPI GetBinaryTypeA( LPCSTR lpApplicationName, LPDWORD lpBinaryType ) /*********************************************************************** * GetBinaryTypeW [KERNEL32.@] + * + * Unicode version of GetBinaryTypeA. */ BOOL WINAPI GetBinaryTypeW( LPCWSTR lpApplicationName, LPDWORD lpBinaryType ) { @@ -371,6 +388,15 @@ BOOL WINAPI GetBinaryTypeW( LPCWSTR lpApplicationName, LPDWORD lpBinaryType ) /*********************************************************************** * 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 @@ HMODULE WINAPI GetModuleHandleA(LPCSTR module) /*********************************************************************** * GetModuleHandleW (KERNEL32.@) + * + * Unicode version of GetModuleHandleA. */ HMODULE WINAPI GetModuleHandleW(LPCWSTR module) { @@ -417,15 +445,21 @@ HMODULE WINAPI GetModuleHandleW(LPCWSTR module) * 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 @@ DWORD WINAPI GetModuleFileNameA( /*********************************************************************** * GetModuleFileNameW (KERNEL32.@) + * + * Unicode version of GetModuleFileNameA. */ DWORD WINAPI GetModuleFileNameW( HMODULE hModule, LPWSTR lpFileName, DWORD size ) { @@ -522,11 +558,22 @@ static BOOL load_library_as_datafile( LPCWSTR name, HMODULE* hmod) /****************************************************************** * 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 @@ HMODULE WINAPI LoadLibraryExA(LPCSTR libname, HANDLE hfile, DWORD flags) /*********************************************************************** * LoadLibraryExW (KERNEL32.@) + * + * Unicode version of LoadLibraryExA. */ HMODULE WINAPI LoadLibraryExW(LPCWSTR libnameW, HANDLE hfile, DWORD flags) { @@ -603,6 +652,18 @@ HMODULE WINAPI LoadLibraryExW(LPCWSTR libnameW, HANDLE hfile, DWORD flags) /*********************************************************************** * 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 @@ HMODULE WINAPI LoadLibraryA(LPCSTR libname) /*********************************************************************** * LoadLibraryW (KERNEL32.@) + * + * Unicode version of LoadLibraryA. */ HMODULE WINAPI LoadLibraryW(LPCWSTR libnameW) { @@ -620,6 +683,15 @@ HMODULE WINAPI LoadLibraryW(LPCWSTR libnameW) /*********************************************************************** * 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 @@ BOOL WINAPI FreeLibrary(HINSTANCE hLibModule) /*********************************************************************** * 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 @@ FARPROC WINAPI GetProcAddress( HMODULE hModule, LPCSTR function ) /*********************************************************************** * 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 ) {