diff --git a/dlls/advapi32/advapi.c b/dlls/advapi32/advapi.c index d3bac201585..da544f9b623 100644 --- a/dlls/advapi32/advapi.c +++ b/dlls/advapi32/advapi.c @@ -38,8 +38,15 @@ WINE_DEFAULT_DEBUG_CHANNEL(advapi); /****************************************************************************** * GetUserNameA [ADVAPI32.@] * - * NOTE: lpSize returns the total length of the username, including the - * terminating null character. + * Get the current user name. + * + * PARAMS + * lpszName [O] Destination for the user name. + * lpSize [I/O] Size of lpszName. + * + * RETURNS + * Success: The length of the user name, including terminating NUL. + * Failure: ERROR_MORE_DATA if *lpSize is too small. */ BOOL WINAPI GetUserNameA( LPSTR lpszName, LPDWORD lpSize ) @@ -64,9 +71,7 @@ GetUserNameA( LPSTR lpszName, LPDWORD lpSize ) /****************************************************************************** * GetUserNameW [ADVAPI32.@] * - * PARAMS - * lpszName [] - * lpSize [] + * See GetUserNameA. */ BOOL WINAPI GetUserNameW( LPWSTR lpszName, LPDWORD lpSize ) @@ -88,21 +93,39 @@ GetUserNameW( LPWSTR lpszName, LPDWORD lpSize ) /****************************************************************************** * GetCurrentHwProfileA [ADVAPI32.@] + * + * Get the current hardware profile. + * + * PARAMS + * pInfo [O] Destination for hardware profile information. + * + * RETURNS + * Success: TRUE. pInfo is updated with the hardware profile details. + * Failure: FALSE. */ -BOOL WINAPI GetCurrentHwProfileA(LPHW_PROFILE_INFOA info) +BOOL WINAPI GetCurrentHwProfileA(LPHW_PROFILE_INFOA pInfo) { - FIXME("Mostly Stub\n"); - info->dwDockInfo = DOCKINFO_DOCKED; - strcpy(info->szHwProfileGuid,"{12340001-1234-1234-1234-1233456789012}"); - strcpy(info->szHwProfileName,"Wine Profile"); + FIXME("(%p) semi-stub\n", pInfo); + pInfo->dwDockInfo = DOCKINFO_DOCKED; + strcpy(pInfo->szHwProfileGuid,"{12340001-1234-1234-1234-1233456789012}"); + strcpy(pInfo->szHwProfileName,"Wine Profile"); return 1; } /****************************************************************************** * AbortSystemShutdownA [ADVAPI32.@] * + * Stop a system shutdown if one is in progress. + * * PARAMS - * lpMachineName + * lpMachineName [I] Name of machine to not shutdown. + * + * RETURNS + * Success: TRUE. + * Failure: FALSE. + * + * NOTES + * The Wine implementation of this function is a harmless stub. */ BOOL WINAPI AbortSystemShutdownA( LPSTR lpMachineName ) { @@ -113,8 +136,7 @@ BOOL WINAPI AbortSystemShutdownA( LPSTR lpMachineName ) /****************************************************************************** * AbortSystemShutdownW [ADVAPI32.@] * - * PARAMS - * lpMachineName + * See AbortSystemShutdownA. */ BOOL WINAPI AbortSystemShutdownW( LPCWSTR lpMachineName ) { diff --git a/dlls/advapi32/registry.c b/dlls/advapi32/registry.c index 58e5f5230e5..ff890a3a219 100644 --- a/dlls/advapi32/registry.c +++ b/dlls/advapi32/registry.c @@ -1405,12 +1405,7 @@ DWORD WINAPI RegEnumValueA( HKEY hkey, DWORD index, LPSTR value, LPDWORD val_cou /****************************************************************************** * RegDeleteValueW [ADVAPI32.@] * - * PARAMS - * hkey [I] handle to key - * name [I] name of value to delete - * - * RETURNS - * error status + * See RegDeleteValueA. */ DWORD WINAPI RegDeleteValueW( HKEY hkey, LPCWSTR name ) { @@ -1425,6 +1420,16 @@ DWORD WINAPI RegDeleteValueW( HKEY hkey, LPCWSTR name ) /****************************************************************************** * RegDeleteValueA [ADVAPI32.@] + * + * Delete a value from the registry. + * + * PARAMS + * hkey [I] Registry handle of the key holding the value + * name [I] Name of the value under hkey to delete + * + * RETURNS + * Success: 0 + * Failure: A standard Windows error code. */ DWORD WINAPI RegDeleteValueA( HKEY hkey, LPCSTR name ) { diff --git a/dlls/advapi32/security.c b/dlls/advapi32/security.c index d39232feb1c..be32689fd9f 100644 --- a/dlls/advapi32/security.c +++ b/dlls/advapi32/security.c @@ -94,14 +94,19 @@ BOOL ADVAPI_IsLocalComputer(LPCWSTR ServerName) /****************************************************************************** * OpenProcessToken [ADVAPI32.@] - * Opens the access token associated with a process + * Opens the access token associated with a process handle. * * PARAMS * ProcessHandle [I] Handle to process * DesiredAccess [I] Desired access to process * TokenHandle [O] Pointer to handle of open access token * - * RETURNS STD + * RETURNS + * Success: TRUE. TokenHandle contains the access token. + * Failure: FALSE. + * + * NOTES + * See NtOpenProcessToken. */ BOOL WINAPI OpenProcessToken( HANDLE ProcessHandle, DWORD DesiredAccess, @@ -113,11 +118,20 @@ OpenProcessToken( HANDLE ProcessHandle, DWORD DesiredAccess, /****************************************************************************** * OpenThreadToken [ADVAPI32.@] * + * Opens the access token associated with a thread handle. + * * PARAMS - * thread [] - * desiredaccess [] - * openasself [] - * thandle [] + * ThreadHandle [I] Handle to process + * DesiredAccess [I] Desired access to the thread + * OpenAsSelf [I] ??? + * TokenHandle [O] Destination for the token handle + * + * RETURNS + * Success: TRUE. TokenHandle contains the access token. + * Failure: FALSE. + * + * NOTES + * See NtOpenThreadToken. */ BOOL WINAPI OpenThreadToken( HANDLE ThreadHandle, DWORD DesiredAccess, @@ -129,13 +143,23 @@ OpenThreadToken( HANDLE ThreadHandle, DWORD DesiredAccess, /****************************************************************************** * AdjustTokenPrivileges [ADVAPI32.@] * + * Adjust the privileges of an open token handle. + * * PARAMS - * TokenHandle [] - * DisableAllPrivileges [] - * NewState [] - * BufferLength [] - * PreviousState [] - * ReturnLength [] + * TokenHandle [I] Handle from OpenProcessToken() or OpenThreadToken() + * DisableAllPrivileges [I] TRUE=Remove all privileges, FALSE=Use NewState + * NewState [I] Desired new privileges of the token + * BufferLength [I] Length of NewState + * PreviousState [O] Destination for the previous state + * ReturnLength [I/O] Size of PreviousState + * + * + * RETURNS + * Success: TRUE. Privileges are set to NewState and PreviousState is updated. + * Failure: FALSE. + * + * NOTES + * See NtAdjustPrivilegesToken. */ BOOL WINAPI AdjustTokenPrivileges( HANDLE TokenHandle, BOOL DisableAllPrivileges, @@ -148,10 +172,16 @@ AdjustTokenPrivileges( HANDLE TokenHandle, BOOL DisableAllPrivileges, /****************************************************************************** * CheckTokenMembership [ADVAPI32.@] * + * Determine if an access token is a member of a SID. + * * PARAMS - * TokenHandle [I] - * SidToCheck [I] - * IsMember [O] + * TokenHandle [I] Handle from OpenProcessToken() or OpenThreadToken() + * SidToCheck [I] SID that possibly contains the token + * IsMember [O] Destination for result. + * + * RETURNS + * Success: TRUE. IsMember is TRUE if TokenHandle is a member, FALSE otherwise. + * Failure: FALSE. */ BOOL WINAPI CheckTokenMembership( HANDLE TokenHandle, PSID SidToCheck, @@ -167,12 +197,18 @@ CheckTokenMembership( HANDLE TokenHandle, PSID SidToCheck, * GetTokenInformation [ADVAPI32.@] * * PARAMS - * token [I] - * tokeninfoclass [I] - * tokeninfo [O] - * tokeninfolength [I] - * retlen [O] + * token [I] Handle from OpenProcessToken() or OpenThreadToken() + * tokeninfoclass [I] A TOKEN_INFORMATION_CLASS from "winnt.h" + * tokeninfo [O] Destination for token information + * tokeninfolength [I] Length of tokeninfo + * retlen [O] Destination for returned token information length * + * RETURNS + * Success: TRUE. tokeninfo contains retlen bytes of token information + * Failure: FALSE. + * + * NOTES + * See NtQueryInformationToken. */ BOOL WINAPI GetTokenInformation( HANDLE token, TOKEN_INFORMATION_CLASS tokeninfoclass, @@ -203,12 +239,17 @@ GetTokenInformation( HANDLE token, TOKEN_INFORMATION_CLASS tokeninfoclass, /****************************************************************************** * SetTokenInformation [ADVAPI32.@] * - * PARAMS - * token [I] - * tokeninfoclass [I] - * tokeninfo [I] - * tokeninfolength [I] + * Set information for an access token. * + * PARAMS + * token [I] Handle from OpenProcessToken() or OpenThreadToken() + * tokeninfoclass [I] A TOKEN_INFORMATION_CLASS from "winnt.h" + * tokeninfo [I] Token information to set + * tokeninfolength [I] Length of tokeninfo + * + * RETURNS + * Success: TRUE. The information for the token is set to tokeninfo. + * Failure: FALSE. */ BOOL WINAPI SetTokenInformation( HANDLE token, TOKEN_INFORMATION_CLASS tokeninfoclass, @@ -242,13 +283,22 @@ SetTokenInformation( HANDLE token, TOKEN_INFORMATION_CLASS tokeninfoclass, /************************************************************************* * SetThreadToken [ADVAPI32.@] * - * Assigns an "impersonation token" to a thread so it can assume the + * Assigns an 'impersonation token' to a thread so it can assume the * security privledges of another thread or process. Can also remove - * a previously assigned token. Only supported on NT - it's a stub - * exactly like this one on Win9X. + * a previously assigned token. * + * PARAMS + * thread [O] Handle to thread to set the token for + * token [I] Token to set + * + * RETURNS + * Success: TRUE. The threads access token is set to token + * Failure: FALSE. + * + * NOTES + * Only supported on NT or higher. On Win9X this function does nothing. + * See SetTokenInformation. */ - BOOL WINAPI SetThreadToken(PHANDLE thread, HANDLE token) { FIXME("(%p, %p): stub (NT impl. only)\n", thread, token); @@ -608,14 +658,8 @@ DWORD WINAPI InitializeAcl(PACL acl, DWORD size, DWORD rev) /****************************************************************************** * LookupPrivilegeValueW [ADVAPI32.@] - * Retrieves LUID used on a system to represent the privilege name. * - * PARAMS - * lpSystemName [I] Address of string specifying the system - * lpName [I] Address of string specifying the privilege - * lpLuid [I] Address of locally unique identifier - * - * RETURNS STD + * See LookupPrivilegeValueA. */ BOOL WINAPI LookupPrivilegeValueW( LPCWSTR lpSystemName, LPCWSTR lpName, PLUID lpLuid ) @@ -629,6 +673,17 @@ LookupPrivilegeValueW( LPCWSTR lpSystemName, LPCWSTR lpName, PLUID lpLuid ) /****************************************************************************** * LookupPrivilegeValueA [ADVAPI32.@] + * + * Retrieves LUID used on a system to represent the privilege name. + * + * PARAMS + * lpSystemName [I] Name of the system + * lpName [I] Name of the privilege + * pLuid [O] Destination for the resulting LUD + * + * RETURNS + * Success: TRUE. pLuid contains the requested LUID. + * Failure: FALSE. */ BOOL WINAPI LookupPrivilegeValueA( LPCSTR lpSystemName, LPCSTR lpName, PLUID lpLuid ) @@ -648,9 +703,22 @@ LookupPrivilegeValueA( LPCSTR lpSystemName, LPCSTR lpName, PLUID lpLuid ) /****************************************************************************** * GetFileSecurityA [ADVAPI32.@] * - * Obtains Specified information about the security of a file or directory - * The information obtained is constrained by the callers access rights and - * privileges + * Obtains Specified information about the security of a file or directory. + * + * PARAMS + * lpFileName [I] Name of the file to get info for + * RequestedInformation [I] SE_ flags from "winnt.h" + * pSecurityDescriptor [O] Destination for security information + * nLength [I] Length of pSecurityDescriptor + * lpnLengthNeeded [O] Destination for length of returned security information + * + * RETURNS + * Success: TRUE. pSecurityDescriptor contains the requested information. + * Failure: FALSE. lpnLengthNeeded contains the required space to return the info. + * + * NOTES + * The information returned is constrained by the callers access rights and + * privileges. */ BOOL WINAPI GetFileSecurityA( LPCSTR lpFileName, @@ -665,16 +733,7 @@ GetFileSecurityA( LPCSTR lpFileName, /****************************************************************************** * GetFileSecurityW [ADVAPI32.@] * - * Obtains Specified information about the security of a file or directory - * The information obtained is constrained by the callers access rights and - * privileges - * - * PARAMS - * lpFileName [] - * RequestedInformation [] - * pSecurityDescriptor [] - * nLength [] - * lpnLengthNeeded [] + * See GetFileSecurityA. */ BOOL WINAPI GetFileSecurityW( LPCWSTR lpFileName, @@ -881,6 +940,7 @@ LsaQueryInformationPolicy( struct di * xdi = HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(xdi)); RtlCreateUnicodeStringFromAsciiz(&(xdi->ppdi.Name), "DOMAIN"); + xdi->ppdi.Sid = &(xdi->sid); xdi->sid.Revision = SID_REVISION; xdi->sid.SubAuthorityCount = 1; diff --git a/dlls/comctl32/comctl32undoc.c b/dlls/comctl32/comctl32undoc.c index 71308ac92ab..7769ca3e0be 100644 --- a/dlls/comctl32/comctl32undoc.c +++ b/dlls/comctl32/comctl32undoc.c @@ -1809,9 +1809,9 @@ DPA_Clone (const HDPA hdpa, const HDPA hdpaNew) */ LPVOID WINAPI -DPA_GetPtr (const HDPA hdpa, INT i) +DPA_GetPtr (const HDPA hdpa, INT nIndex) { - TRACE("(%p %d)\n", hdpa, i); + TRACE("(%p %d)\n", hdpa, nIndex); if (!hdpa) return NULL; @@ -1819,14 +1819,14 @@ DPA_GetPtr (const HDPA hdpa, INT i) WARN("no pointer array.\n"); return NULL; } - if ((i < 0) || (i >= hdpa->nItemCount)) { - WARN("not enough pointers in array (%d vs %d).\n",i,hdpa->nItemCount); + if ((nIndex < 0) || (nIndex >= hdpa->nItemCount)) { + WARN("not enough pointers in array (%d vs %d).\n",nIndex,hdpa->nItemCount); return NULL; } - TRACE("-- %p\n", hdpa->ptrs[i]); + TRACE("-- %p\n", hdpa->ptrs[nIndex]); - return hdpa->ptrs[i]; + return hdpa->ptrs[nIndex]; } diff --git a/dlls/comctl32/commctrl.c b/dlls/comctl32/commctrl.c index fd0aae66283..db1cd0ee35b 100644 --- a/dlls/comctl32/commctrl.c +++ b/dlls/comctl32/commctrl.c @@ -1145,12 +1145,12 @@ BOOL WINAPI SetWindowSubclass (HWND hWnd, SUBCLASSPROC pfnSubclass, * PARAMS * hWnd [in] Handle to window which were subclassing * pfnSubclass [in] Pointer to the subclass procedure - * iID [in] Unique indentifier of the subclassing procedure + * uID [in] Unique indentifier of the subclassing procedure * pdwRef [out] Pointer to the reference data * * RETURNS - * Success: non-sero - * Failure: zero + * Success: Non-zero + * Failure: 0 */ BOOL WINAPI GetWindowSubclass (HWND hWnd, SUBCLASSPROC pfnSubclass, diff --git a/dlls/kernel/thunk.c b/dlls/kernel/thunk.c index d68ce7e7650..7dcb8f81871 100644 --- a/dlls/kernel/thunk.c +++ b/dlls/kernel/thunk.c @@ -759,34 +759,34 @@ void WINAPI OT_32ThkLSF( CONTEXT86 *context ) * A thunk setup routine. * Expects a pointer to a preinitialized thunkbuffer in the first argument * looking like: - * 00..03: unknown (pointer, check _41, _43, _46) - * 04: EB1E jmp +0x20 - * - * 06..23: unknown (space for replacement code, check .90) - * - * 24:>E800000000 call offset 29 - * 29:>58 pop eax ( target of call ) - * 2A: 2D25000000 sub eax,0x00000025 ( now points to offset 4 ) - * 2F: BAxxxxxxxx mov edx,xxxxxxxx - * 34: 68yyyyyyyy push KERNEL32.90 - * 39: C3 ret - * - * 3A: EB1E jmp +0x20 - * 3E ... 59: unknown (space for replacement code?) - * 5A: E8xxxxxxxx call <32bitoffset xxxxxxxx> - * 5F: 5A pop edx - * 60: 81EA25xxxxxx sub edx, 0x25xxxxxx - * 66: 52 push edx - * 67: 68xxxxxxxx push xxxxxxxx - * 6C: 68yyyyyyyy push KERNEL32.89 - * 71: C3 ret - * 72: end? + *| 00..03: unknown (pointer, check _41, _43, _46) + *| 04: EB1E jmp +0x20 + *| + *| 06..23: unknown (space for replacement code, check .90) + *| + *| 24:>E800000000 call offset 29 + *| 29:>58 pop eax ( target of call ) + *| 2A: 2D25000000 sub eax,0x00000025 ( now points to offset 4 ) + *| 2F: BAxxxxxxxx mov edx,xxxxxxxx + *| 34: 68yyyyyyyy push KERNEL32.90 + *| 39: C3 ret + *| + *| 3A: EB1E jmp +0x20 + *| 3E ... 59: unknown (space for replacement code?) + *| 5A: E8xxxxxxxx call <32bitoffset xxxxxxxx> + *| 5F: 5A pop edx + *| 60: 81EA25xxxxxx sub edx, 0x25xxxxxx + *| 66: 52 push edx + *| 67: 68xxxxxxxx push xxxxxxxx + *| 6C: 68yyyyyyyy push KERNEL32.89 + *| 71: C3 ret + *| 72: end? * This function checks if the code is there, and replaces the yyyyyyyy entries * by the functionpointers. * The thunkbuf looks like: * - * 00: DWORD length ? don't know exactly - * 04: SEGPTR ptr ? where does it point to? + *| 00: DWORD length ? don't know exactly + *| 04: SEGPTR ptr ? where does it point to? * The segpointer ptr is written into the first DWORD of 'thunk'. * [ok probably] * RETURNS @@ -1020,17 +1020,18 @@ void WINAPI W32S_BackTo32( CONTEXT86 *context ) /********************************************************************** * AllocSLCallback (KERNEL32.@) * + * NOTES * Win95 uses some structchains for callbacks. It allocates them * in blocks of 100 entries, size 32 bytes each, layout: * blockstart: - * 0: PTR nextblockstart - * 4: entry *first; - * 8: WORD sel ( start points to blockstart) - * A: WORD unknown + *| 0: PTR nextblockstart + *| 4: entry *first; + *| 8: WORD sel ( start points to blockstart) + *| A: WORD unknown * 100xentry: - * 00..17: Code - * 18: PDB *owning_process; - * 1C: PTR blockstart + *| 00..17: Code + *| 18: PDB *owning_process; + *| 1C: PTR blockstart * * We ignore this for now. (Just a note for further developers) * FIXME: use this method, so we don't waste selectors... @@ -1038,21 +1039,21 @@ void WINAPI W32S_BackTo32( CONTEXT86 *context ) * Following code is then generated by AllocSLCallback. The code is 16 bit, so * the 0x66 prefix switches from word->long registers. * - * 665A pop edx - * 6668x arg2 x pushl - * 6652 push edx - * EAx arg1 x jmpf + *| 665A pop edx + *| 6668x arg2 x pushl + *| 6652 push edx + *| EAx arg1 x jmpf * * returns the startaddress of this thunk. * - * Note, that they look very similair to the ones allocates by THUNK_Alloc. + * Note, that they look very similar to the ones allocates by THUNK_Alloc. * RETURNS - * segmented pointer to the start of the thunk + * A segmented pointer to the start of the thunk */ DWORD WINAPI AllocSLCallback( - DWORD finalizer, /* [in] finalizer function */ - DWORD callback /* [in] callback function */ + DWORD finalizer, /* [in] Finalizer function */ + DWORD callback /* [in] Callback function */ ) { LPBYTE x,thunk = HeapAlloc( GetProcessHeap(), 0, 32 ); WORD sel; @@ -1092,15 +1093,20 @@ void WINAPI GetTEBSelectorFS16(void) /********************************************************************** * IsPeFormat (KERNEL.431) - * Checks the passed filename if it is a PE format executeable + * + * Determine if a file is a PE format executable. + * * RETURNS * TRUE, if it is. - * FALSE if not. + * FALSE if the file could not be opened or is not a PE file. + * + * NOTES + * If fn is given as NULL then the function expects hf16 to be valid. */ BOOL16 WINAPI IsPeFormat16( - LPSTR fn, /* [in] filename to executeable */ - HFILE16 hf16 /* [in] open file, if filename is NULL */ -) { + LPSTR fn, /* [in] Filename to the executeable */ + HFILE16 hf16) /* [in] An open file handle */ +{ BOOL ret = FALSE; IMAGE_DOS_HEADER mzh; OFSTRUCT ofs; diff --git a/dlls/kernel/time.c b/dlls/kernel/time.c index 7b1e5640e70..caa10c2eeb6 100644 --- a/dlls/kernel/time.c +++ b/dlls/kernel/time.c @@ -51,13 +51,13 @@ WINE_DEFAULT_DEBUG_CHANNEL(win32); /*********************************************************************** * SetLocalTime (KERNEL32.@) * - * Sets the local time using current time zone and daylight + * Set the local time using current time zone and daylight * savings settings. * * RETURNS - * - * True if the time was set, false if the time was invalid or the - * necessary permissions were not held. + * Success: TRUE. The time was set + * Failure: FALSE, if the time was invalid or caller does not have + * permission to change the time. */ BOOL WINAPI SetLocalTime( const SYSTEMTIME *systime) /* [in] The desired local time. */ @@ -80,15 +80,13 @@ BOOL WINAPI SetLocalTime( /*********************************************************************** * GetSystemTimeAdjustment (KERNEL32.@) * - * Indicates the period between clock interrupt and the amount the clock - * is adjusted each interrupt so as to keep it insync with an external source. + * Get the period between clock interrupts and the amount the clock + * is adjusted each interrupt so as to keep it in sync with an external source. * * RETURNS - * - * Always returns true. + * TRUE. * * BUGS - * * Only the special case of disabled time adjustments is supported. */ BOOL WINAPI GetSystemTimeAdjustment( @@ -106,12 +104,12 @@ BOOL WINAPI GetSystemTimeAdjustment( /*********************************************************************** * SetSystemTime (KERNEL32.@) * - * Sets the system time (utc). + * Set the system time in utc. * * RETURNS - * - * True if the time was set, false if the time was invalid or the - * necessary permissions were not held. + * Success: TRUE. The time was set + * Failure: FALSE, if the time was invalid or caller does not have + * permission to change the time. */ BOOL WINAPI SetSystemTime( const SYSTEMTIME *systime) /* [in] The desired system time. */ @@ -132,15 +130,14 @@ BOOL WINAPI SetSystemTime( /*********************************************************************** * GetTimeZoneInformation (KERNEL32.@) * - * Fills in the a time zone information structure with values based on - * the current local time. + * Get information about the current local time zone. * * RETURNS - * - * The daylight savings time standard or TIME_ZONE_ID_INVALID if the call failed. + * Success: TIME_ZONE_ID_STANDARD. tzinfo contains the time zone info. + * Failure: TIME_ZONE_ID_INVALID. */ DWORD WINAPI GetTimeZoneInformation( - LPTIME_ZONE_INFORMATION tzinfo) /* [out] The time zone structure to be filled in. */ + LPTIME_ZONE_INFORMATION tzinfo) /* [out] Destination for time zone information */ { NTSTATUS status; if ((status = RtlQueryTimeZoneInformation(tzinfo))) @@ -152,11 +149,11 @@ DWORD WINAPI GetTimeZoneInformation( /*********************************************************************** * SetTimeZoneInformation (KERNEL32.@) * - * Set the local time zone with values based on the time zone structure. + * Change the settings of the current local time zone. * * RETURNS - * - * True on successful setting of the time zone. + * Success: TRUE. The time zone was updated with the settings from tzinfo + * Failure: FALSE. */ BOOL WINAPI SetTimeZoneInformation( const LPTIME_ZONE_INFORMATION tzinfo) /* [in] The new time zone. */ @@ -346,12 +343,11 @@ static BOOL _GetTimezoneBias( /*********************************************************************** * SystemTimeToTzSpecificLocalTime (KERNEL32.@) * - * Converts the system time (utc) to the local time in the specified time zone. + * Convert a utc system time to a local time in a given time zone. * * RETURNS - * - * Returns TRUE when the local time was calculated. - * + * Success: TRUE. lpLocalTime contains the converted time + * Failure: FALSE. */ BOOL WINAPI SystemTimeToTzSpecificLocalTime( @@ -397,13 +393,12 @@ BOOL WINAPI SystemTimeToTzSpecificLocalTime( /*********************************************************************** * TzSpecificLocalTimeToSystemTime (KERNEL32.@) * - * Converts a local time to a time in Coordinated Universal Time (UTC). + * Converts a local time to a time in utc. * * RETURNS - * - * Returns TRUE when the utc time was calculated. + * Success: TRUE. lpUniversalTime contains the converted time + * Failure: FALSE. */ - BOOL WINAPI TzSpecificLocalTimeToSystemTime( LPTIME_ZONE_INFORMATION lpTimeZoneInformation, /* [in] The desired time zone. */ LPSYSTEMTIME lpLocalTime, /* [in] The local time. */ @@ -444,15 +439,16 @@ BOOL WINAPI TzSpecificLocalTimeToSystemTime( } - - /*********************************************************************** * GetSystemTimeAsFileTime (KERNEL32.@) * - * Fills in a file time structure with the current time in UTC format. + * Get the current time in utc format. + * + * RETURNS + * Nothing. */ VOID WINAPI GetSystemTimeAsFileTime( - LPFILETIME time) /* [out] The file time struct to be filled with the system time. */ + LPFILETIME time) /* [out] Destination for the current utc time */ { LARGE_INTEGER t; NtQuerySystemTime( &t ); @@ -482,20 +478,19 @@ static void TIME_ClockTimeToFileTime(clock_t unix_time, LPFILETIME filetime) /********************************************************************* * GetProcessTimes (KERNEL32.@) * - * Returns the user and kernel execution times of a process, + * Get the user and kernel execution times of a process, * along with the creation and exit times if known. * + * RETURNS + * TRUE. + * + * NOTES * olorin@fandra.org: - * Would be nice to subtract the cpu time, used by Wine at startup. + * Would be nice to subtract the cpu time used by Wine at startup. * Also, there is a need to separate times used by different applications. * - * RETURNS - * - * Always returns true. - * * BUGS - * - * lpCreationTime, lpExitTime are NOT INITIALIZED. + * lpCreationTime and lpExitTime are not initialised in the Wine implementation. */ BOOL WINAPI GetProcessTimes( HANDLE hprocess, /* [in] The process to be queried (obtained from PROCESS_QUERY_INFORMATION). */ @@ -541,6 +536,7 @@ int WINAPI GetCalendarInfoA(LCID Locale, CALID Calendar, CALTYPE CalType, /********************************************************************* * GetCalendarInfoW (KERNEL32.@) * + * See GetCalendarInfoA. */ int WINAPI GetCalendarInfoW(LCID Locale, CALID Calendar, CALTYPE CalType, LPWSTR lpCalData, int cchData, LPDWORD lpValue) @@ -687,6 +683,7 @@ int WINAPI SetCalendarInfoA(LCID Locale, CALID Calendar, CALTYPE CalType, LPCSTR /********************************************************************* * SetCalendarInfoW (KERNEL32.@) * + * See SetCalendarInfoA. */ int WINAPI SetCalendarInfoW(LCID Locale, CALID Calendar, CALTYPE CalType, LPCWSTR lpCalData) { @@ -782,6 +779,16 @@ BOOL WINAPI SystemTimeToFileTime( const SYSTEMTIME *syst, LPFILETIME ft ) /********************************************************************* * CompareFileTime (KERNEL32.@) + * + * Compare two FILETIME's to each other. + * + * PARAMS + * x [I] First time + * y [I] time to compare to x + * + * RETURNS + * -1, 0, or 1 indicating that x is less than, equal to, or greater + * than y respectively. */ INT WINAPI CompareFileTime( const FILETIME *x, const FILETIME *y ) { @@ -800,8 +807,13 @@ INT WINAPI CompareFileTime( const FILETIME *x, const FILETIME *y ) /********************************************************************* * GetLocalTime (KERNEL32.@) + * + * Get the current local time. + * + * RETURNS + * Nothing. */ -VOID WINAPI GetLocalTime(LPSYSTEMTIME systime) +VOID WINAPI GetLocalTime(LPSYSTEMTIME systime) /* [O] Destination for current time */ { FILETIME lft; LARGE_INTEGER ft, ft2; @@ -815,8 +827,13 @@ VOID WINAPI GetLocalTime(LPSYSTEMTIME systime) /********************************************************************* * GetSystemTime (KERNEL32.@) + * + * Get the current system time. + * + * RETURNS + * Nothing. */ -VOID WINAPI GetSystemTime(LPSYSTEMTIME systime) +VOID WINAPI GetSystemTime(LPSYSTEMTIME systime) /* [O] Destination for current time */ { FILETIME ft; LARGE_INTEGER t; diff --git a/dlls/ntdll/critsection.c b/dlls/ntdll/critsection.c index 3b29f5bbbe3..023323a0171 100644 --- a/dlls/ntdll/critsection.c +++ b/dlls/ntdll/critsection.c @@ -62,6 +62,14 @@ static inline HANDLE get_semaphore( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlInitializeCriticalSection (NTDLL.@) + * + * Initialise a new RTL_CRITICAL_SECTION. + * + * PARAMS + * crit [O] Critical section to initialise + * + * RETURN + * STATUS_SUCCESS. */ NTSTATUS WINAPI RtlInitializeCriticalSection( RTL_CRITICAL_SECTION *crit ) { @@ -75,7 +83,18 @@ NTSTATUS WINAPI RtlInitializeCriticalSection( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlInitializeCriticalSectionAndSpinCount (NTDLL.@) - * The InitializeCriticalSectionAndSpinCount (KERNEL32) function is + * + * Initialise a new RTL_CRITICAL_SECTION with a given spin count. + * + * PARAMS + * crit [O] Critical section to initialise + * spincount [I] Spin count for crit + * + * RETURNS + * STATUS_SUCCESS. + * + * NOTES + * The InitializeCriticalSectionAndSpinCount() (KERNEL32) function is * available on NT4SP3 or later, and Win98 or later. * I am assuming that this is the correct definition given the MSDN * docs for the kernel32 functions. @@ -90,6 +109,14 @@ NTSTATUS WINAPI RtlInitializeCriticalSectionAndSpinCount( RTL_CRITICAL_SECTION * /*********************************************************************** * RtlDeleteCriticalSection (NTDLL.@) + * + * Free the resources used by an RTL_CRITICAL_SECTION. + * + * PARAMS + * crit [I/O] Critical section to free + * + * RETURNS + * STATUS_SUCCESS. */ NTSTATUS WINAPI RtlDeleteCriticalSection( RTL_CRITICAL_SECTION *crit ) { @@ -104,6 +131,14 @@ NTSTATUS WINAPI RtlDeleteCriticalSection( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlpWaitForCriticalSection (NTDLL.@) + * + * Wait for an RTL_CRITICAL_SECTION to become free. + * + * PARAMS + * crit [I/O] Critical section to wait for + * + * RETURNS + * STATUS_SUCCESS. */ NTSTATUS WINAPI RtlpWaitForCriticalSection( RTL_CRITICAL_SECTION *crit ) { @@ -157,6 +192,17 @@ NTSTATUS WINAPI RtlpUnWaitCriticalSection( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlEnterCriticalSection (NTDLL.@) + * + * Enter an RTL_CRITICAL_SECTION. + * + * PARAMS + * crit [I/O] Critical section to enter + * + * RETURNS + * STATUS_SUCCESS. The critical section is held by the caller. + * + * NOTES + * The caller will wait until the critical section is availale. */ NTSTATUS WINAPI RtlEnterCriticalSection( RTL_CRITICAL_SECTION *crit ) { @@ -179,6 +225,15 @@ NTSTATUS WINAPI RtlEnterCriticalSection( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlTryEnterCriticalSection (NTDLL.@) + * + * Enter an RTL_CRITICAL_SECTION without waiting. + * + * PARAMS + * crit [I/O] Critical section to enter + * + * RETURNS + * Success: TRUE. The critical section is held by the caller. + * Failure: FALSE. The critical section is currently held by another thread. */ BOOL WINAPI RtlTryEnterCriticalSection( RTL_CRITICAL_SECTION *crit ) { @@ -201,6 +256,14 @@ BOOL WINAPI RtlTryEnterCriticalSection( RTL_CRITICAL_SECTION *crit ) /*********************************************************************** * RtlLeaveCriticalSection (NTDLL.@) + * + * Leave an RTL_CRITICAL_SECTION. + * + * PARAMS + * crit [I/O] Critical section to enter + * + * RETURNS + * STATUS_SUCCESS. */ NTSTATUS WINAPI RtlLeaveCriticalSection( RTL_CRITICAL_SECTION *crit ) { diff --git a/dlls/ntdll/heap.c b/dlls/ntdll/heap.c index bd7babe924b..792a46b18bb 100644 --- a/dlls/ntdll/heap.c +++ b/dlls/ntdll/heap.c @@ -934,6 +934,20 @@ static BOOL HEAP_IsRealArena( HEAP *heapPtr, /* [in] ptr to the heap */ /*********************************************************************** * RtlCreateHeap (NTDLL.@) + * + * Create a new Heap. + * + * PARAMS + * flags [I] HEAP_ flags from "winnt.h" + * addr [I] Desired base address + * totalSize [I] Total size of the heap, or 0 for a growable heap + * commitSize [I] Amount of heap space to commit + * unknown [I] Not yet understood + * definition [I] Heap definition + * + * RETURNS + * Success: A HANDLE to the newly created heap. + * Failure: a NULL HANDLE. */ HANDLE WINAPI RtlCreateHeap( ULONG flags, PVOID addr, ULONG totalSize, ULONG commitSize, PVOID unknown, PRTL_HEAP_DEFINITION definition ) @@ -969,6 +983,15 @@ HANDLE WINAPI RtlCreateHeap( ULONG flags, PVOID addr, ULONG totalSize, ULONG com /*********************************************************************** * RtlDestroyHeap (NTDLL.@) + * + * Destroy a Heap created with RtlCreateHeap(). + * + * PARAMS + * heap [I] Heap to destroy. + * + * RETURNS + * Success: A NULL HANDLE, if heap is NULL or it was destroyed + * Failure: The Heap handle, if heap is the process heap. */ HANDLE WINAPI RtlDestroyHeap( HANDLE heap ) { @@ -1006,7 +1029,19 @@ HANDLE WINAPI RtlDestroyHeap( HANDLE heap ) /*********************************************************************** * RtlAllocateHeap (NTDLL.@) * - * NOTE: does not set last error. + * Allocate a memory block from a Heap. + * + * PARAMS + * heap [I] Heap to allocate block from + * flags [I] HEAP_ flags from "winnt.h" + * size [I] Size of the memory block to allocate + * + * RETURNS + * Success: A pointer to the newly allocated block + * Failure: NULL. + * + * NOTES + * This call does not SetLastError(). */ PVOID WINAPI RtlAllocateHeap( HANDLE heap, ULONG flags, ULONG size ) { @@ -1068,6 +1103,17 @@ PVOID WINAPI RtlAllocateHeap( HANDLE heap, ULONG flags, ULONG size ) /*********************************************************************** * RtlFreeHeap (NTDLL.@) + * + * Free a memory block allocated with RtlAllocateHeap(). + * + * PARAMS + * heap [I] Heap that block was allocated from + * flags [I] HEAP_ flags from "winnt.h" + * ptr [I] Block to free + * + * RETURNS + * Success: TRUE, if ptr is NULL or was freed successfully. + * Failure: FALSE. */ BOOLEAN WINAPI RtlFreeHeap( HANDLE heap, ULONG flags, PVOID ptr ) { @@ -1112,6 +1158,18 @@ BOOLEAN WINAPI RtlFreeHeap( HANDLE heap, ULONG flags, PVOID ptr ) /*********************************************************************** * RtlReAllocateHeap (NTDLL.@) + * + * Change the size of a memory block allocated with RtlAllocateHeap(). + * + * PARAMS + * heap [I] Heap that block was allocated from + * flags [I] HEAP_ flags from "winnt.h" + * ptr [I] Block to resize + * size [I] Size of the memory block to allocate + * + * RETURNS + * Success: A pointer to the resized block (which may be different). + * Failure: NULL. */ PVOID WINAPI RtlReAllocateHeap( HANDLE heap, ULONG flags, PVOID ptr, ULONG size ) { @@ -1231,6 +1289,18 @@ PVOID WINAPI RtlReAllocateHeap( HANDLE heap, ULONG flags, PVOID ptr, ULONG size /*********************************************************************** * RtlCompactHeap (NTDLL.@) + * + * Compact the free space in a Heap. + * + * PARAMS + * heap [I] Heap that block was allocated from + * flags [I] HEAP_ flags from "winnt.h" + * + * RETURNS + * The number of bytes compacted. + * + * NOTES + * This function is a harmless stub. */ ULONG WINAPI RtlCompactHeap( HANDLE heap, ULONG flags ) { @@ -1241,6 +1311,15 @@ ULONG WINAPI RtlCompactHeap( HANDLE heap, ULONG flags ) /*********************************************************************** * RtlLockHeap (NTDLL.@) + * + * Lock a Heap. + * + * PARAMS + * heap [I] Heap to lock + * + * RETURNS + * Success: TRUE. The Heap is locked. + * Failure: FALSE, if heap is invalid. */ BOOLEAN WINAPI RtlLockHeap( HANDLE heap ) { @@ -1253,6 +1332,15 @@ BOOLEAN WINAPI RtlLockHeap( HANDLE heap ) /*********************************************************************** * RtlUnlockHeap (NTDLL.@) + * + * Unlock a Heap. + * + * PARAMS + * heap [I] Heap to unlock + * + * RETURNS + * Success: TRUE. The Heap is unlocked. + * Failure: FALSE, if heap is invalid. */ BOOLEAN WINAPI RtlUnlockHeap( HANDLE heap ) { @@ -1265,6 +1353,20 @@ BOOLEAN WINAPI RtlUnlockHeap( HANDLE heap ) /*********************************************************************** * RtlSizeHeap (NTDLL.@) + * + * Get the actual size of a memory block allocated from a Heap. + * + * PARAMS + * heap [I] Heap that block was allocated from + * flags [I] HEAP_ flags from "winnt.h" + * ptr [I] Block to get the size of + * + * RETURNS + * Success: The size of the block. + * Failure: -1, heap or ptr are invalid. + * + * NOTES + * The size may be bigger than what was passed to RtlAllocateHeap(). */ ULONG WINAPI RtlSizeHeap( HANDLE heap, ULONG flags, PVOID ptr ) { @@ -1299,20 +1401,32 @@ ULONG WINAPI RtlSizeHeap( HANDLE heap, ULONG flags, PVOID ptr ) /*********************************************************************** * RtlValidateHeap (NTDLL.@) + * + * Determine if a block is a valid alloction from a heap. + * + * PARAMS + * heap [I] Heap that block was allocated from + * flags [I] HEAP_ flags from "winnt.h" + * ptr [I] Block to check + * + * RETURNS + * Success: TRUE. The block was allocated from heap. + * Failure: FALSE, if heap is invalid or ptr was not allocated from it. */ -BOOLEAN WINAPI RtlValidateHeap( HANDLE heap, ULONG flags, LPCVOID block ) +BOOLEAN WINAPI RtlValidateHeap( HANDLE heap, ULONG flags, LPCVOID ptr ) { HEAP *heapPtr = HEAP_GetPtr( heap ); if (!heapPtr) return FALSE; - return HEAP_IsRealArena( heapPtr, flags, block, QUIET ); + return HEAP_IsRealArena( heapPtr, flags, ptr, QUIET ); } /*********************************************************************** * RtlWalkHeap (NTDLL.@) * - * FIXME: the PROCESS_HEAP_ENTRY flag values seem different between this - * function and HeapWalk. To be checked. + * FIXME + * The PROCESS_HEAP_ENTRY flag values seem different between this + * function and HeapWalk(). To be checked. */ NTSTATUS WINAPI RtlWalkHeap( HANDLE heap, PVOID entry_ptr ) { @@ -1422,6 +1536,16 @@ HW_end: /*********************************************************************** * RtlGetProcessHeaps (NTDLL.@) + * + * Get the Heaps belonging to the current process. + * + * PARAMS + * count [I] size of heaps + * heaps [O] Destination array for heap HANDLE's + * + * RETURNS + * Success: The number of Heaps allocated by the process. + * Failure: 0. */ ULONG WINAPI RtlGetProcessHeaps( ULONG count, HANDLE *heaps ) { diff --git a/dlls/ntdll/om.c b/dlls/ntdll/om.c index 4a990ca70ab..bbd371d2aab 100644 --- a/dlls/ntdll/om.c +++ b/dlls/ntdll/om.c @@ -62,14 +62,14 @@ NTSTATUS WINAPI NtQueryObject( /****************************************************************************** * NtQuerySecurityObject [NTDLL.@] * - * analogue to GetKernelObjectSecurity + * An ntdll analogue to GetKernelObjectSecurity(). * * NOTES * only the lowest 4 bit of SecurityObjectInformationClass are used * 0x7-0xf returns STATUS_ACCESS_DENIED (even running with system privileges) * - * FIXME: we are constructing a fake sid - * (Administrators:Full, System:Full, Everyone:Read) + * FIXME + * We are constructing a fake sid (Administrators:Full, System:Full, Everyone:Read) */ NTSTATUS WINAPI NtQuerySecurityObject( @@ -245,9 +245,15 @@ NTSTATUS WINAPI NtDuplicateObject( HANDLE source_process, HANDLE source, /************************************************************************** * NtClose [NTDLL.@] - * FUNCTION: Closes a handle reference to an object - * ARGUMENTS: - * Handle handle to close + * + * Close a handle reference to an object. + * + * PARAMS + * Handle [I] handle to close + * + * RETURNS + * Success: ERROR_SUCCESS. + * Failure: An NTSTATUS error code. */ NTSTATUS WINAPI NtClose( HANDLE Handle ) { @@ -282,12 +288,17 @@ NTSTATUS WINAPI NtWaitForSingleObject( /************************************************************************** * NtOpenDirectoryObject [NTDLL.@] * ZwOpenDirectoryObject [NTDLL.@] - * FUNCTION: Opens a namespace directory object - * ARGUMENTS: - * DirectoryHandle Variable which receives the directory handle - * DesiredAccess Desired access to the directory - * ObjectAttributes Structure describing the directory - * RETURNS: Status + * + * Open a namespace directory object. + * + * PARAMS + * DirectoryHandle [O] Destination for the new directory handle + * DesiredAccess [I] Desired access to the directory + * ObjectAttributes [I] Structure describing the directory + * + * RETURNS + * Success: ERROR_SUCCESS. + * Failure: An NTSTATUS error code. */ NTSTATUS WINAPI NtOpenDirectoryObject( PHANDLE DirectoryHandle, @@ -318,16 +329,21 @@ NTSTATUS WINAPI NtCreateDirectoryObject( /****************************************************************************** * NtQueryDirectoryObject [NTDLL.@] * ZwQueryDirectoryObject [NTDLL.@] - * FUNCTION: Reads information from a namespace directory - * ARGUMENTS: - * DirObjInformation Buffer to hold the data read - * BufferLength Size of the buffer in bytes - * GetNextIndex If TRUE then set ObjectIndex to the index of the next object - * If FALSE then set ObjectIndex to the number of objects in the directory - * IgnoreInputIndex If TRUE start reading at index 0 - * If FALSE start reading at the index specified by object index - * ObjectIndex Zero based index into the directory, interpretation depends on IgnoreInputIndex and GetNextIndex - * DataWritten Caller supplied storage for the number of bytes written (or NULL) + * + * Read information from a namespace directory. + * + * PARAMS + * DirObjHandle [I] Object handle + * DirObjInformation [O] Buffer to hold the data read + * BufferLength [I] Size of the buffer in bytes + * GetNextIndex [I] Set ObjectIndex to TRUE=next object, FALSE=last object + * IgnoreInputIndex [I] Start reading at index TRUE=0, FALSE=ObjectIndex + * ObjectIndex [I/O] 0 based index into the directory, see IgnoreInputIndex and GetNextIndex + * DataWritten [O] Caller supplied storage for the number of bytes written (or NULL) + * + * RETURNS + * Success: ERROR_SUCCESS. + * Failure: An NTSTATUS error code. */ NTSTATUS WINAPI NtQueryDirectoryObject( IN HANDLE DirObjHandle, @@ -394,7 +410,8 @@ NTSTATUS WINAPI NtQuerySymbolicLinkObject( /****************************************************************************** * NtAllocateUuids [NTDLL.@] * - * I have seen lpdwCount pointing to a pointer once... + * NOTES + * I have seen lpdwCount pointing to a pointer once... */ NTSTATUS WINAPI NtAllocateUuids(LPDWORD lpdwCount, LPDWORD *p2, LPDWORD *p3) { diff --git a/dlls/ntdll/time.c b/dlls/ntdll/time.c index 261ad775a01..d6efb0a0923 100644 --- a/dlls/ntdll/time.c +++ b/dlls/ntdll/time.c @@ -297,11 +297,11 @@ static inline void NormalizeTimeFields(CSHORT *FieldToNormalize, CSHORT *CarryFi * * Parses Time into a TimeFields structure. * - * PARAMS: - * liTime [I]: Time to convert to timefields. - * TimeFields [O]: Pointer to TIME_FIELDS structure to hold parsed info. + * PARAMS + * liTime [I] Time to convert to timefields. + * TimeFields [O] Pointer to TIME_FIELDS structure to hold parsed info. * - * RETURNS: + * RETURNS * Nothing. */ VOID WINAPI RtlTimeToTimeFields( @@ -360,11 +360,11 @@ VOID WINAPI RtlTimeToTimeFields( * * Converts a TIME_FIELDS structure to time. * - * PARAMS: - * ftTimeFields [I]: Time fields structure to convert. - * Time [O]: Converted time. + * PARAMS + * ftTimeFields [I] Time fields structure to convert. + * Time [O] Converted time. * - * RETURNS: + * RETURNS * TRUE: Successfull * FALSE: Failure. */ @@ -418,11 +418,11 @@ BOOLEAN WINAPI RtlTimeFieldsToTime( * * Converts local time to system time. * - * PARAMS: - * LocalTime [I]: Localtime to convert. - * SystemTime [O]: SystemTime of the supplied localtime. + * PARAMS + * LocalTime [I] Localtime to convert. + * SystemTime [O] SystemTime of the supplied localtime. * - * RETURNS: + * RETURNS * Status. */ NTSTATUS WINAPI RtlLocalTimeToSystemTime( const LARGE_INTEGER *LocalTime, @@ -442,11 +442,11 @@ NTSTATUS WINAPI RtlLocalTimeToSystemTime( const LARGE_INTEGER *LocalTime, * * Converts system Time to local time. * - * PARAMS: - * SystemTime [I]: System time to convert. - * LocalTime [O]: Local time of the supplied system time. + * PARAMS + * SystemTime [I] System time to convert. + * LocalTime [O] Local time of the supplied system time. * - * RETURNS: + * RETURNS * Nothing. */ NTSTATUS WINAPI RtlSystemTimeToLocalTime( const LARGE_INTEGER *SystemTime, @@ -466,11 +466,11 @@ NTSTATUS WINAPI RtlSystemTimeToLocalTime( const LARGE_INTEGER *SystemTime, * * Converts Time to seconds since 1970. * - * PARAMS: - * time [I]: Time to convert. - * res [O]: Pointer to a LONG to recieve the seconds since 1970. + * PARAMS + * time [I] Time to convert. + * res [O] Pointer to a LONG to recieve the seconds since 1970. * - * RETURNS: + * RETURNS * TRUE: Successfull. * FALSE: Failure. */ @@ -489,11 +489,11 @@ BOOLEAN WINAPI RtlTimeToSecondsSince1970( const LARGE_INTEGER *time, PULONG res * * Converts Time to seconds since 1980. * - * PARAMS: - * time [I]: Time to convert. - * res [O]: Pointer to a integer to recieve the time since 1980. + * PARAMS + * time [I] Time to convert. + * res [O] Pointer to a integer to recieve the time since 1980. * - * RETURNS: + * RETURNS * TRUE: Successfull * FALSE: Failure. */ @@ -512,11 +512,11 @@ BOOLEAN WINAPI RtlTimeToSecondsSince1980( const LARGE_INTEGER *time, LPDWORD res * * Converts seconds since 1970 to time. * - * PARAMS: - * time [I]: Seconds since 1970 to convert. - * res [O]: Seconds since 1970 in Time. + * PARAMS + * time [I] Seconds since 1970 to convert. + * res [O] Seconds since 1970 in Time. * - * RETURNS: + * RETURNS * Nothing. */ void WINAPI RtlSecondsSince1970ToTime( DWORD time, LARGE_INTEGER *res ) @@ -531,11 +531,11 @@ void WINAPI RtlSecondsSince1970ToTime( DWORD time, LARGE_INTEGER *res ) * * Converts seconds since 1980 to time. * - * PARAMS: - * time [I]: Seconds since 1980 to convert. - * res [O]: Seconds since 1980 in Time. + * PARAMS + * time [I] Seconds since 1980 to convert. + * res [O] Seconds since 1980 in Time. * - * RETURNS: + * RETURNS * Nothing. */ void WINAPI RtlSecondsSince1980ToTime( DWORD time, LARGE_INTEGER *res ) @@ -548,7 +548,7 @@ void WINAPI RtlSecondsSince1980ToTime( DWORD time, LARGE_INTEGER *res ) /****************************************************************************** * RtlTimeToElapsedTimeFields [NTDLL.@] * - * RETURNS: + * RETURNS * Nothing. */ void WINAPI RtlTimeToElapsedTimeFields( const LARGE_INTEGER *Time, PTIME_FIELDS TimeFields ) @@ -577,10 +577,10 @@ void WINAPI RtlTimeToElapsedTimeFields( const LARGE_INTEGER *Time, PTIME_FIELDS * * Gets the current system time. * - * PARAMS: - * time [O]: The current system time. + * PARAMS + * time [O] The current system time. * - * RETURNS: + * RETURNS * Status. */ NTSTATUS WINAPI NtQuerySystemTime( PLARGE_INTEGER time ) @@ -597,11 +597,11 @@ NTSTATUS WINAPI NtQuerySystemTime( PLARGE_INTEGER time ) * * Helper function calculates delta local time from UTC. * - * PARAMS: - * utc [I]: The current utc time. - * pdaylight [I]: Local daylight. + * PARAMS + * utc [I] The current utc time. + * pdaylight [I] Local daylight. * - * RETURNS: + * RETURNS * The bias for the current timezone. */ static int TIME_GetBias(time_t utc, int *pdaylight) @@ -618,12 +618,12 @@ static int TIME_GetBias(time_t utc, int *pdaylight) * * Helper function that returns the given timezone as a string. * - * PARAMS: - * utc [I]: The current utc time. - * bias [I]: The bias of the current timezone. - * dst [I]: ?? + * PARAMS + * utc [I] The current utc time. + * bias [I] The bias of the current timezone. + * dst [I] ?? * - * RETURNS: + * RETURNS * Timezone name. * * NOTES: @@ -657,10 +657,10 @@ static const WCHAR* TIME_GetTZAsStr (time_t utc, int bias, int dst) * * Returns the timezone. * - * PARAMS: - * tzinfo [O]: Retrieves the timezone info. + * PARAMS + * tzinfo [O] Retrieves the timezone info. * - * RETURNS: + * RETURNS * Status. */ NTSTATUS WINAPI RtlQueryTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo) @@ -687,10 +687,10 @@ NTSTATUS WINAPI RtlQueryTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo) * * Sets the current time zone. * - * PARAMS: - * tzinfo [I]: Timezone information used to set timezone. + * PARAMS + * tzinfo [I] Timezone information used to set timezone. * - * RETURNS: + * RETURNS * Status. * * BUGS: @@ -718,10 +718,10 @@ NTSTATUS WINAPI RtlSetTimeZoneInformation( const TIME_ZONE_INFORMATION *tzinfo ) * Sets the system time. * * PARAM: - * NewTime [I]: The time to set the system time to. - * OldTime [O]: Optional (ie. can be NULL). Old Time. + * NewTime [I] The time to set the system time to. + * OldTime [O] Optional (ie. can be NULL). Old Time. * - * RETURNS: + * RETURNS * Status. */ NTSTATUS WINAPI NtSetSystemTime(const LARGE_INTEGER *NewTime, LARGE_INTEGER *OldTime) diff --git a/dlls/oleaut32/dispatch.c b/dlls/oleaut32/dispatch.c index cfa5461b963..a3ff490e791 100644 --- a/dlls/oleaut32/dispatch.c +++ b/dlls/oleaut32/dispatch.c @@ -44,85 +44,89 @@ static IDispatch * WINAPI StdDispatch_Construct(IUnknown * punkOuter, void * pvT /****************************************************************************** * DispInvoke (OLEAUT32.30) * - * - * Calls method of an object through its IDispatch interface. - * - * NOTES - * - Defer method invocation to ITypeInfo::Invoke() + * Call an object method using the information from its type library. * * RETURNS + * Success: S_OK. + * Failure: Returns DISP_E_EXCEPTION and updates pexcepinfo if an exception occurs. + * DISP_E_BADPARAMCOUNT if the number of parameters is incorrect. + * DISP_E_MEMBERNOTFOUND if the method does not exist. + * puArgErr is updated if a parameter error (see notes) occurs. + * Otherwise, returns the result of calling ITypeInfo_Invoke(). * - * S_OK on success. + * NOTES + * Parameter errors include the following: + *| DISP_E_BADVARTYPE + *| E_INVALIDARG An argument was invalid + *| DISP_E_TYPEMISMATCH, + *| DISP_E_OVERFLOW An argument was valid but could not be coerced + *| DISP_E_PARAMNOTOPTIONAL A non optional parameter was not passed + *| DISP_E_PARAMNOTFOUND A parameter was passed that was not expected by the method + * This call defers to ITypeInfo_Invoke(). */ HRESULT WINAPI DispInvoke( - VOID *_this, /* [in] object instance */ - ITypeInfo *ptinfo, /* [in] object's type info */ - DISPID dispidMember, /* [in] member id */ - USHORT wFlags, /* [in] kind of method call */ - DISPPARAMS *pparams, /* [in] array of arguments */ - VARIANT *pvarResult, /* [out] result of method call */ - EXCEPINFO *pexcepinfo, /* [out] information about exception */ - UINT *puArgErr) /* [out] index of bad argument(if any) */ + VOID *_this, /* [in] Object to call method on */ + ITypeInfo *ptinfo, /* [in] Object type info */ + DISPID dispidMember, /* [in] DISPID of the member (e.g. from GetIDsOfNames()) */ + USHORT wFlags, /* [in] Kind of method call (DISPATCH_ flags from "oaidl.h") */ + DISPPARAMS *pparams, /* [in] Array of method arguments */ + VARIANT *pvarResult, /* [out] Destination for the result of the call */ + EXCEPINFO *pexcepinfo, /* [out] Destination for exception information */ + UINT *puArgErr) /* [out] Destination for bad argument */ { - HRESULT hr = E_FAIL; - /** * TODO: * For each param, call DispGetParam to perform type coercion */ FIXME("Coercion of arguments not implemented\n"); - ITypeInfo_Invoke(ptinfo, _this, dispidMember, wFlags, - pparams, pvarResult, pexcepinfo, puArgErr); - - return (hr); + return ITypeInfo_Invoke(ptinfo, _this, dispidMember, wFlags, + pparams, pvarResult, pexcepinfo, puArgErr); } - /****************************************************************************** * DispGetIDsOfNames (OLEAUT32.29) * - * Convert a set of names to dispids, based on information - * contained in object's type library. - * - * NOTES - * - Defers to ITypeInfo::GetIDsOfNames() + * Convert a set of parameter names to DISPID's for DispInvoke(). * * RETURNS + * Success: S_OK. + * Failure: An HRESULT error code. * - * S_OK on success. + * NOTES + * This call defers to ITypeInfo_GetIDsOfNames(). The ITypeInfo interface passed + * as ptinfo contains the information to map names to DISPID's. */ HRESULT WINAPI DispGetIDsOfNames( - ITypeInfo *ptinfo, /* [in] */ - OLECHAR **rgszNames, /* [in] */ - UINT cNames, /* [in] */ - DISPID *rgdispid) /* [out] */ + ITypeInfo *ptinfo, /* [in] Object's type info */ + OLECHAR **rgszNames, /* [in] Array of names to get DISPID's for */ + UINT cNames, /* [in] Number of names in rgszNames */ + DISPID *rgdispid) /* [out] Destination for converted DISPID's */ { - HRESULT hr = E_FAIL; - - ITypeInfo_GetIDsOfNames(ptinfo, rgszNames, cNames, rgdispid); - return (hr); + return ITypeInfo_GetIDsOfNames(ptinfo, rgszNames, cNames, rgdispid); } /****************************************************************************** * DispGetParam (OLEAUT32.28) * - * Retrive a parameter from a DISPPARAMS structures and coerce it to - * specified variant type + * Retrive a parameter from a DISPPARAMS structure and coerce it to the + * specified variant type. * * NOTES - * Coercion is done using system (0) locale. + * Coercion is done using system (0) locale. * * RETURNS - * - * S_OK on success. + * Success: S_OK. + * Failure: DISP_E_PARAMNOTFOUND, if position is invalid. or + * DISP_E_TYPEMISMATCH, if the coercion failed. puArgErr is + * set to the index of the argument in pdispparams. */ HRESULT WINAPI DispGetParam( - DISPPARAMS *pdispparams, /* [in] */ - UINT position, /* [in] */ - VARTYPE vtTarg, /* [in] */ - VARIANT *pvarResult, /* [out] */ - UINT *puArgErr) /* [out] */ + DISPPARAMS *pdispparams, /* [in] Parameter list */ + UINT position, /* [in] Position of parameter to coerce in pdispparams */ + VARTYPE vtTarg, /* [in] Type of value to coerce to */ + VARIANT *pvarResult, /* [out] Destination for resulting variant */ + UINT *puArgErr) /* [out] Destination for error code */ { /* position is counted backwards */ UINT pos; @@ -150,6 +154,12 @@ HRESULT WINAPI DispGetParam( /****************************************************************************** * CreateStdDispatch [OLEAUT32.32] + * + * Create and return a standard IDispatch object. + * + * RETURNS + * Success: S_OK. ppunkStdDisp contains the new object. + * Failure: An HRESULT error code. */ HRESULT WINAPI CreateStdDispatch( IUnknown* punkOuter, @@ -167,16 +177,61 @@ HRESULT WINAPI CreateStdDispatch( /****************************************************************************** * CreateDispTypeInfo [OLEAUT32.31] + * + * Build type information for an object so it can be called through an + * IDispatch interface. + * + * RETURNS + * Success: S_OK. pptinfo contains the created ITypeInfo object. + * Failure: E_INVALIDARG, if one or more arguments is invalid. + * + * NOTES + * This call allows an objects methods to be accessed through IDispatch, by + * building an ITypeInfo object that IDispatch can use to call through. */ HRESULT WINAPI CreateDispTypeInfo( - INTERFACEDATA *pidata, - LCID lcid, - ITypeInfo **pptinfo) + INTERFACEDATA *pidata, /* [I] Description of the interface to build type info for */ + LCID lcid, /* [I] Locale Id */ + ITypeInfo **pptinfo) /* [O] Destination for created ITypeInfo object */ { FIXME("(%p,%ld,%p),stub\n",pidata,lcid,pptinfo); return 0; } +/****************************************************************************** + * IDispatch {OLEAUT32} + * + * NOTES + * The IDispatch interface provides a single interface to dispatch method calls, + * regardless of whether the object to be called is in or out of process, + * local or remote (e.g. being called over a network). This interface is late-bound + * (linked at run-time), as opposed to early-bound (linked at compile time). + * + * The interface is used by objects that wish to called by scripting + * languages such as VBA, in order to minimise the amount of COM and C/C++ + * knowledge required, or by objects that wish to live out of process from code + * that will call their methods. + * + * Method, property and parameter names can be localised. The details required to + * map names to methods and parameters are collected in a type library, usually + * output by an IDL compiler using the objects IDL description. This information is + * accessable programatically through the ITypeLib interface (for a type library), + * and the ITypeInfo interface (for an object within the type library). Type information + * can also be created at run-time using CreateDispTypeInfo(). + * + * WRAPPERS + * Instead of using IDispatch directly, there are several wrapper functions available + * to simplify the process of calling an objects methods through IDispatch. + * + * A standard implementation of an IDispatch object is created by calling + * CreateStdDispatch(). Numeric Id values for the parameters and methods (DISPID's) + * of an object of interest are retrieved by calling DispGetIDsOfNames(). DispGetParam() + * retrieves information about a particular parameter. Finally the DispInvoke() + * function is responsable for actually calling methods on an object. + * + * METHODS + */ + typedef struct { ICOM_VFIELD(IDispatch); @@ -186,6 +241,11 @@ typedef struct ULONG ref; } StdDispatch; +/****************************************************************************** + * IDispatch_QueryInterface {OLEAUT32} + * + * See IUnknown_QueryInterface. + */ static HRESULT WINAPI StdDispatch_QueryInterface( LPDISPATCH iface, REFIID riid, @@ -207,6 +267,11 @@ static HRESULT WINAPI StdDispatch_QueryInterface( return E_NOINTERFACE; } +/****************************************************************************** + * IDispatch_AddRef {OLEAUT32} + * + * See IUnknown_AddRef. + */ static ULONG WINAPI StdDispatch_AddRef(LPDISPATCH iface) { ICOM_THIS(StdDispatch, iface); @@ -218,6 +283,11 @@ static ULONG WINAPI StdDispatch_AddRef(LPDISPATCH iface) return This->ref; } +/****************************************************************************** + * IDispatch_Release {OLEAUT32} + * + * See IUnknown_Release. + */ static ULONG WINAPI StdDispatch_Release(LPDISPATCH iface) { ICOM_THIS(StdDispatch, iface); @@ -237,25 +307,93 @@ static ULONG WINAPI StdDispatch_Release(LPDISPATCH iface) return ret; } +/****************************************************************************** + * IDispatch_GetTypeInfoCount {OLEAUT32} + * + * Get the count of type information in an IDispatch interface. + * + * PARAMS + * iface [I] IDispatch interface + * pctinfo [O] Destination for the count + * + * RETURNS + * Success: S_OK. pctinfo is updated with the count. This is always 1 if + * the object provides type information, and 0 if it does not. + * Failure: E_NOTIMPL. The object does not provide type information. + * + * NOTES + * See IDispatch() and IDispatch_GetTypeInfo(). + */ static HRESULT WINAPI StdDispatch_GetTypeInfoCount(LPDISPATCH iface, UINT * pctinfo) { + ICOM_THIS(StdDispatch, iface); TRACE("(%p)\n", pctinfo); - *pctinfo = 1; + *pctinfo = This->pTypeInfo ? 1 : 0; return S_OK; } +/****************************************************************************** + * IDispatch_GetTypeInfo {OLEAUT32} + * + * Get type information from an IDispatch interface. + * + * PARAMS + * iface [I] IDispatch interface + * iTInfo [I] Index of type information. + * lcid [I] Locale of the type information to get + * ppTInfo [O] Destination for the ITypeInfo object + * + * RETURNS + * Success: S_OK. ppTInfo is updated with the objects type information + * Failure: DISP_E_BADINDEX, if iTInfo is any value other than 0. + * + * NOTES + * See IDispatch. + */ static HRESULT WINAPI StdDispatch_GetTypeInfo(LPDISPATCH iface, UINT iTInfo, LCID lcid, ITypeInfo** ppTInfo) { ICOM_THIS(StdDispatch, iface); TRACE("(%d, %lx, %p)\n", iTInfo, lcid, ppTInfo); + *ppTInfo = NULL; if (iTInfo != 0) return DISP_E_BADINDEX; - *ppTInfo = This->pTypeInfo; + + if (This->pTypeInfo) + { + *ppTInfo = This->pTypeInfo; + ITypeInfo_AddRef(*ppTInfo); + } return S_OK; } +/****************************************************************************** + * IDispatch_GetIDsOfNames {OLEAUT32} + * + * Convert a methods name and an optional set of parameter names into DISPID's + * for passing to IDispatch_Invoke(). + * + * PARAMS + * iface [I] IDispatch interface + * riid [I] Reserved, set to IID_NULL + * rgszNames [I] Name to convert + * cNames [I] Number of names in rgszNames + * lcid [I] Locale of the type information to convert from + * rgDispId [O] Destination for converted DISPID's. + * + * RETURNS + * Success: S_OK. + * Failure: DISP_E_UNKNOWNNAME, if any of the names is invalid. + * DISP_E_UNKNOWNLCID if lcid is invalid. + * Otherwise, an An HRESULT error code. + * + * NOTES + * This call defers to ITypeInfo_GetIDsOfNames(), using the ITypeInfo object + * contained within the IDispatch object. + * The first member of the names list must be a method name. The names following + * the method name are the parameters for that method. + */ static HRESULT WINAPI StdDispatch_GetIDsOfNames(LPDISPATCH iface, REFIID riid, LPOLESTR * rgszNames, UINT cNames, LCID lcid, DISPID * rgDispId) { ICOM_THIS(StdDispatch, iface); @@ -269,7 +407,32 @@ static HRESULT WINAPI StdDispatch_GetIDsOfNames(LPDISPATCH iface, REFIID riid, L return DispGetIDsOfNames(This->pTypeInfo, rgszNames, cNames, rgDispId); } -static HRESULT WINAPI StdDispatch_Invoke(LPDISPATCH iface, DISPID dispIdMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS * pDispParams, VARIANT * pVarResult, EXCEPINFO * pExcepInfo, UINT * puArgErr) +/****************************************************************************** + * IDispatch_Invoke {OLEAUT32} + * + * Call an object method. + * + * PARAMS + * iface [I] IDispatch interface + * dispIdMember [I] DISPID of the method (from GetIDsOfNames()) + * riid [I] Reserved, set to IID_NULL + * lcid [I] Locale of the type information to convert parameters with + * wFlags, [I] Kind of method call (DISPATCH_ flags from "oaidl.h") + * pDispParams [I] Array of method arguments + * pVarResult [O] Destination for the result of the call + * pExcepInfo [O] Destination for exception information + * puArgErr [O] Destination for bad argument + * + * RETURNS + * Success: S_OK. + * Failure: See DispInvoke() for failure cases. + * + * NOTES + * See DispInvoke() and IDispatch(). + */ +static HRESULT WINAPI StdDispatch_Invoke(LPDISPATCH iface, DISPID dispIdMember, REFIID riid, LCID lcid, + WORD wFlags, DISPPARAMS * pDispParams, VARIANT * pVarResult, + EXCEPINFO * pExcepInfo, UINT * puArgErr) { ICOM_THIS(StdDispatch, iface); TRACE("(%ld, %s, 0x%lx, 0x%x, %p, %p, %p, %p)\n", dispIdMember, debugstr_guid(riid), lcid, wFlags, pDispParams, pVarResult, pExcepInfo, puArgErr); diff --git a/dlls/oleaut32/ole2disp.c b/dlls/oleaut32/ole2disp.c index b06c61664e3..ed49c9f2666 100644 --- a/dlls/oleaut32/ole2disp.c +++ b/dlls/oleaut32/ole2disp.c @@ -71,34 +71,69 @@ static void* BSTR_GetAddr(BSTR16 in) /****************************************************************************** * SysAllocString [OLE2DISP.2] + * + * Create a BSTR16 from an OLESTR16 (16 Bit). + * + * PARAMS + * oleStr [I] Source to create BSTR16 from + * + * RETURNS + * Success: A BSTR16 allocated with SysAllocStringLen16(). + * Failure: NULL, if oleStr is NULL. */ -BSTR16 WINAPI SysAllocString16(LPCOLESTR16 in) +BSTR16 WINAPI SysAllocString16(LPCOLESTR16 oleStr) { BSTR16 out; - if (!in) return 0; + if (!oleStr) return 0; - out = BSTR_AllocBytes(strlen(in)+1); + out = BSTR_AllocBytes(strlen(oleStr)+1); if (!out) return 0; - strcpy(BSTR_GetAddr(out),in); + strcpy(BSTR_GetAddr(out),oleStr); return out; } /****************************************************************************** * SysReallocString [OLE2DISP.3] + * + * Change the length of a previously created BSTR16 (16 Bit). + * + * PARAMS + * pbstr [I] BSTR16 to change the length of + * oleStr [I] New source for pbstr + * + * RETURNS + * Success: 1 + * Failure: 0. + * + * NOTES + * SysAllocStringStringLen16(). */ -INT16 WINAPI SysReAllocString16(LPBSTR16 old,LPCOLESTR16 in) +INT16 WINAPI SysReAllocString16(LPBSTR16 pbstr,LPCOLESTR16 oleStr) { - BSTR16 new=SysAllocString16(in); - BSTR_Free(*old); - *old=new; + BSTR16 new=SysAllocString16(oleStr); + BSTR_Free(*pbstr); + *pbstr=new; return 1; } /****************************************************************************** * SysAllocStringLen [OLE2DISP.4] + * + * Create a BSTR16 from an OLESTR16 of a given character length (16 Bit). + * + * PARAMS + * oleStr [I] Source to create BSTR16 from + * len [I] Length of oleStr in wide characters + * + * RETURNS + * Success: A newly allocated BSTR16 from SysAllocStringByteLen16() + * Failure: NULL, if len is >= 0x80000000, or memory allocation fails. + * + * NOTES + * See SysAllocStringByteLen16(). */ -BSTR16 WINAPI SysAllocStringLen16(const char *in, int len) +BSTR16 WINAPI SysAllocStringLen16(const char *oleStr, int len) { BSTR16 out=BSTR_AllocBytes(len+1); @@ -110,8 +145,8 @@ BSTR16 WINAPI SysAllocStringLen16(const char *in, int len) * Since it is valid to pass a NULL pointer here, we'll initialize the * buffer to nul if it is the case. */ - if (in != 0) - strcpy(BSTR_GetAddr(out),in); + if (oleStr != 0) + strcpy(BSTR_GetAddr(out),oleStr); else memset(BSTR_GetAddr(out), 0, len+1); @@ -120,9 +155,25 @@ BSTR16 WINAPI SysAllocStringLen16(const char *in, int len) /****************************************************************************** * SysReAllocStringLen [OLE2DISP.5] + * + * Change the length of a previously created BSTR16 (16 Bit). + * + * PARAMS + * pbstr [I] BSTR16 to change the length of + * oleStr [I] New source for pbstr + * len [I] Length of oleStr in characters + * + * RETURNS + * Success: 1. The size of pbstr is updated. + * Failure: 0, if len >= 0x8000 or memory allocation fails. + * + * NOTES + * See SysAllocStringByteLen16(). + * *pbstr may be changed by this function. */ int WINAPI SysReAllocStringLen16(BSTR16 *old,const char *in,int len) { + /* FIXME: Check input length */ BSTR16 new=SysAllocStringLen16(in,len); BSTR_Free(*old); *old=new; @@ -131,14 +182,30 @@ int WINAPI SysReAllocStringLen16(BSTR16 *old,const char *in,int len) /****************************************************************************** * SysFreeString [OLE2DISP.6] + * + * Free a BSTR16 (16 Bit). + * + * PARAMS + * str [I] String to free. + * + * RETURNS + * Nothing. */ -void WINAPI SysFreeString16(BSTR16 in) +void WINAPI SysFreeString16(BSTR16 str) { - BSTR_Free(in); + BSTR_Free(str); } /****************************************************************************** * SysStringLen [OLE2DISP.7] + * + * Get the allocated length of a BSTR16 in characters (16 Bit). + * + * PARAMS + * str [I] BSTR16 to find the length of + * + * RETURNS + * The allocated length of str, or 0 if str is NULL. */ int WINAPI SysStringLen16(BSTR16 str) { diff --git a/dlls/oleaut32/typelib16.c b/dlls/oleaut32/typelib16.c index 594de7122ee..9b16d659c29 100644 --- a/dlls/oleaut32/typelib16.c +++ b/dlls/oleaut32/typelib16.c @@ -41,21 +41,41 @@ WINE_DEFAULT_DEBUG_CHANNEL(ole); +/************************************************************************* + * TYPELIB {TYPELIB} + * + * This dll is the 16 bit version of the Typelib API, part the original + * implementation of Ole automation. It and its companion ole2disp.dll were + * superceeded by oleaut32.dll which provides 32 bit implementations of these + * functions and greatly extends the Ole Api. + * + * Winelib developers cannot use these functions directly, they are implemented + * solely for backwards compatibility with existing legacy applications. + * + * SEE ALSO + * oleaut32(), ole2disp(). + */ + /**************************************************************************** * QueryPathOfRegTypeLib [TYPELIB.14] * - * the path is "Classes\Typelib\\.\\win16\" + * Get the registry key of a registered type library. + * * RETURNS - * path of typelib + * Success: S_OK. path is updated with the key name + * Failure: E_FAIL, if guid was not found in the registry + * + * NOTES + * The key takes the form "Classes\Typelib\\.\\win16\" */ HRESULT WINAPI QueryPathOfRegTypeLib16( - REFGUID guid, /* [in] referenced guid */ - WORD wMaj, /* [in] major version */ - WORD wMin, /* [in] minor version */ - LCID lcid, /* [in] locale id */ - LPBSTR16 path /* [out] path of typelib */ -) { + REFGUID guid, /* [in] Guid to get the key name for */ + WORD wMaj, /* [in] Major version */ + WORD wMin, /* [in] Minor version */ + LCID lcid, /* [in] Locale Id */ + LPBSTR16 path) /* [out] Destination for the registry key name */ +{ char xguid[80]; char typelibkey[100],pathname[260]; DWORD plen; @@ -86,18 +106,20 @@ QueryPathOfRegTypeLib16( } /****************************************************************************** - * LoadTypeLib [TYPELIB.3] Loads and registers a type library - * NOTES - * Docs: OLECHAR FAR* szFile - * Docs: iTypeLib FAR* FAR* pptLib + * LoadTypeLib [TYPELIB.3] + * + * Load and register a type library. * * RETURNS - * Success: S_OK - * Failure: Status + * Success: S_OK. pptLib contains the type libraries ITypeLib interface. + * Failure: An HRESULT error code. + * + * NOTES + * Both parameters are FAR pointers. */ HRESULT WINAPI LoadTypeLib16( LPOLESTR szFile, /* [in] Name of file to load from */ - ITypeLib** pptLib) /* [out] Pointer to pointer to loaded type library */ + ITypeLib** pptLib) /* [out] Destination for loaded ITypeLib interface */ { FIXME("(%s,%p): stub\n",debugstr_w((LPWSTR)szFile),pptLib); @@ -110,16 +132,26 @@ HRESULT WINAPI LoadTypeLib16( /**************************************************************************** * OaBuildVersion (TYPELIB.15) * - * known TYPELIB.DLL versions: + * Get the Ole Automation build version. * - * OLE 2.01 no OaBuildVersion() avail 1993 -- --- - * OLE 2.02 1993-94 02 3002 - * OLE 2.03 23 730 - * OLE 2.03 03 3025 - * OLE 2.03 W98 SE orig. file !! 1993-95 10 3024 - * OLE 2.1 NT 1993-95 ?? ??? - * OLE 2.3.1 W95 23 700 - * OLE2 4.0 NT4SP6 1993-98 40 4277 + * PARAMS + * None + * + * RETURNS + * The build version. + * + * NOTES + * Known typelib.dll versions: + *| OLE Ver. Comments Date Build Ver. + *| -------- ------------------------- ---- --------- + *| OLE 2.01 Call not available 1993 N/A + *| OLE 2.02 1993-94 02 3002 + *| OLE 2.03 23 730 + *| OLE 2.03 03 3025 + *| OLE 2.03 W98 SE orig. file !! 1993-95 10 3024 + *| OLE 2.1 NT 1993-95 ?? ??? + *| OLE 2.3.1 W95 23 700 + *| OLE2 4.0 NT4SP6 1993-98 40 4277 */ DWORD WINAPI OaBuildVersion16(void) { diff --git a/dlls/shell32/pidl.c b/dlls/shell32/pidl.c index dc1af4e5ad4..aab3b463887 100644 --- a/dlls/shell32/pidl.c +++ b/dlls/shell32/pidl.c @@ -224,12 +224,6 @@ HRESULT WINAPI ILSaveToStream (IStream * pStream, LPCITEMIDLIST pPidl) return ret; } -/************************************************************************* - * SHILCreateFromPath [SHELL32.28] - * - * NOTES - * wraper for IShellFolder::ParseDisplayName() - */ HRESULT WINAPI SHILCreateFromPathA (LPCSTR path, LPITEMIDLIST * ppidl, DWORD * attributes) { LPSHELLFOLDER sf; WCHAR lpszDisplayName[MAX_PATH]; @@ -248,6 +242,7 @@ HRESULT WINAPI SHILCreateFromPathA (LPCSTR path, LPITEMIDLIST * ppidl, DWORD * a } return ret; } + HRESULT WINAPI SHILCreateFromPathW (LPCWSTR path, LPITEMIDLIST * ppidl, DWORD * attributes) { LPSHELLFOLDER sf; DWORD pchEaten; @@ -262,6 +257,13 @@ HRESULT WINAPI SHILCreateFromPathW (LPCWSTR path, LPITEMIDLIST * ppidl, DWORD * } return ret; } + +/************************************************************************* + * SHILCreateFromPath [SHELL32.28] + * + * NOTES + * Wrapper for IShellFolder_ParseDisplayName(). + */ HRESULT WINAPI SHILCreateFromPathAW (LPCVOID path, LPITEMIDLIST * ppidl, DWORD * attributes) { if ( SHELL_OsIsUnicode()) diff --git a/dlls/shell32/shell.c b/dlls/shell32/shell.c index 57b71dc1f67..2375716b911 100644 --- a/dlls/shell32/shell.c +++ b/dlls/shell32/shell.c @@ -76,7 +76,9 @@ static int SHELL_Attach = 0; * Initialization code for shell.dll. Automatically loads the * 32-bit shell32.dll to allow thunking up to 32-bit code. * - * RETURNS: + * RETURNS + * Success: TRUE. Initialization completed successfully. + * Failure: FALSE. */ BOOL WINAPI SHELL_DllEntryPoint(DWORD Reason, HINSTANCE16 hInst, WORD ds, WORD HeapSize, DWORD res1, WORD res2) diff --git a/dlls/shell32/shellole.c b/dlls/shell32/shellole.c index 874980a5970..f1b4f059949 100644 --- a/dlls/shell32/shellole.c +++ b/dlls/shell32/shellole.c @@ -417,11 +417,19 @@ static ICOM_VTABLE(IMalloc) VT_Shell_IMalloc32 = /************************************************************************* * SHGetMalloc [SHELL32.@] - * returns the interface to shell malloc. + * + * Return the shell IMalloc interface. + * + * PARAMS + * lpmal [O] Destination for IMalloc interface. + * + * RETURNS + * Success: S_OK. lpmal contains the shells IMalloc interface. + * Failure. An HRESULT error code. * * NOTES - * uses OLE32.CoGetMalloc if OLE32.DLL is already loaded. - * if not it uses a internal implementations as fallback. + * This function will use CoGetMalloc() if OLE32.DLL is already loaded. + * If not it uses an internal implementation as a fallback. */ HRESULT WINAPI SHGetMalloc(LPMALLOC *lpmal) { diff --git a/dlls/shell32/shellord.c b/dlls/shell32/shellord.c index d6c336a241b..57ddf7f106a 100644 --- a/dlls/shell32/shellord.c +++ b/dlls/shell32/shellord.c @@ -260,16 +260,21 @@ VOID WINAPI SHGetSettings(LPSHELLFLAGSTATE lpsfs, DWORD dwMask) /************************************************************************* * SHShellFolderView_Message [SHELL32.73] * - * PARAMETERS - * hwndCabinet defines the explorer cabinet window that contains the - * shellview you need to communicate with - * uMsg identifying the SFVM enum to perform - * lParam + * Send a message to an explorer cabinet window. + * + * PARAMS + * hwndCabinet [I] The window containing the shellview to communicate with + * dwMessage [I] The SFVM message to send + * dwParam [I] Message parameter + * + * RETURNS + * fixme. * * NOTES * Message SFVM_REARRANGE = 1 + * * This message gets sent when a column gets clicked to instruct the - * shell view to re-sort the item list. lParam identifies the column + * shell view to re-sort the item list. dwParam identifies the column * that was clicked. */ int WINAPI SHShellFolderView_Message( @@ -284,12 +289,14 @@ int WINAPI SHShellFolderView_Message( /************************************************************************* * RegisterShellHook [SHELL32.181] * + * Register a shell hook. + * * PARAMS - * hwnd [I] window handle - * y [I] flag ???? + * hwnd [I] Window handle + * dwType [I] Type of hook. * * NOTES - * exported by ordinal + * Exported by ordinal */ BOOL WINAPI RegisterShellHook( HWND hWnd, @@ -298,16 +305,11 @@ BOOL WINAPI RegisterShellHook( FIXME("(%p,0x%08lx):stub.\n",hWnd, dwType); return TRUE; } + /************************************************************************* * ShellMessageBoxW [SHELL32.182] * - * Format and output errormessage. - * - * idText resource ID of title or LPSTR - * idTitle resource ID of title or LPSTR - * - * NOTES - * exported by ordinal + * See ShellMessageBoxA. */ int WINAPIV ShellMessageBoxW( HINSTANCE hInstance, @@ -350,6 +352,21 @@ int WINAPIV ShellMessageBoxW( /************************************************************************* * ShellMessageBoxA [SHELL32.183] + * + * Format and output an error message. + * + * PARAMS + * hInstance [I] Instance handle of message creator + * hWnd [I] Window handle of message creator + * lpText [I] Resource Id of title or LPSTR + * lpCaption [I] Resource Id of title or LPSTR + * uType [I] Type of error message + * + * RETURNS + * A return value from MessageBoxA(). + * + * NOTES + * Exported by ordinal */ int WINAPIV ShellMessageBoxA( HINSTANCE hInstance, diff --git a/dlls/shell32/shfldr_fs.c b/dlls/shell32/shfldr_fs.c index a43482c5e38..5e0001721de 100644 --- a/dlls/shell32/shfldr_fs.c +++ b/dlls/shell32/shfldr_fs.c @@ -288,26 +288,29 @@ static ULONG WINAPI IShellFolder_fnRelease (IShellFolder2 * iface) } /************************************************************************** -* IShellFolder_fnParseDisplayName -* PARAMETERS -* HWND hwndOwner, //[in ] Parent window for any message's -* LPBC pbc, //[in ] reserved -* LPOLESTR lpszDisplayName,//[in ] "Unicode" displayname. -* ULONG* pchEaten, //[out] (unicode) characters processed -* LPITEMIDLIST* ppidl, //[out] complex pidl to item -* ULONG* pdwAttributes //[out] items attributes +* IShellFolder_ParseDisplayName {SHELL32} +* +* Parse a display name. +* +* PARAMS +* hwndOwner [in] Parent window for any message's +* pbc [in] Reserved +* lpszDisplayName [in] Unicode displayname. +* pchEaten [out] (unicode) characters processed +* ppidl [out] complex pidl to item +* pdwAttributes [out] items attributes * * NOTES -* every folder tries to parse only its own (the leftmost) pidl and creates a -* subfolder to evaluate the remaining parts -* now we can parse into namespaces implemented by shell extensions +* Every folder tries to parse only its own (the leftmost) pidl and creates a +* subfolder to evaluate the remaining parts. +* Now we can parse into namespaces implemented by shell extensions * -* behaviour on win98: lpszDisplayName=NULL -> chrash +* Behaviour on win98: lpszDisplayName=NULL -> crash * lpszDisplayName="" -> returns mycoputer-pidl * -* FIXME: -* pdwAttributes: not set -* pchEaten: not set like in windows +* FIXME +* pdwAttributes is not set +* pchEaten is not set like in windows */ static HRESULT WINAPI IShellFolder_fnParseDisplayName (IShellFolder2 * iface, diff --git a/dlls/shell32/shlfileop.c b/dlls/shell32/shlfileop.c index 1b740b2b6a6..c7a8819bb17 100644 --- a/dlls/shell32/shlfileop.c +++ b/dlls/shell32/shlfileop.c @@ -179,7 +179,7 @@ DWORD WINAPI SHCreateDirectoryExW(HWND hWnd, LPCWSTR path, LPSECURITY_ATTRIBUTES * * Deletes a file. Also triggers a change notify if one exists. * - * NOTES: + * NOTES * Verified on Win98 / IE 5 (SHELL32 4.72, March 1999 build) to be ANSI. * This is Unicode on NT/2000 */ diff --git a/dlls/shlwapi/path.c b/dlls/shlwapi/path.c index 6f607a1eaff..62c03c303fc 100644 --- a/dlls/shlwapi/path.c +++ b/dlls/shlwapi/path.c @@ -64,11 +64,11 @@ static BOOL (WINAPI *pIsNetDrive)(DWORD); * * RETURNS * Success: TRUE. lpszPath contains the newly created path. - * Failure: FALSE, if either path is NULL, or PathCombineA fails. + * Failure: FALSE, if either path is NULL, or PathCombineA() fails. * * NOTES * lpszAppend must contain at least one backslash ('\') if not NULL. - * Because PathCombineA is used to join the paths, the resulting + * Because PathCombineA() is used to join the paths, the resulting * path is also canonicalized. */ BOOL WINAPI PathAppendA (LPSTR lpszPath, LPCSTR lpszAppend) @@ -114,7 +114,7 @@ BOOL WINAPI PathAppendW(LPWSTR lpszPath, LPCWSTR lpszAppend) * PARAMS * lpszDest [O] Destination for combined path * lpszDir [I] Directory path - * liszFile [I] File path + * lpszFile [I] File path * * RETURNS * Success: The output path @@ -1099,7 +1099,7 @@ BOOL WINAPI SHLWAPI_4(LPWSTR lpszPath,DWORD dwWhich) * dwWhich [I] Type of executable to search for * * RETURNS - * TRUE If the file was found. lpszFile contains the file name. + * TRUE If the file was found. lpszPath contains the file name. * FALSE Otherwise. * * NOTES @@ -1109,7 +1109,7 @@ BOOL WINAPI SHLWAPI_4(LPWSTR lpszPath,DWORD dwWhich) * extensions are not checked. * * Ordinals 3-6 are a classic case of MS exposing limited functionality to - * users (here through PathFindOnPath) and keeping advanced functionality for + * users (here through PathFindOnPathA()) and keeping advanced functionality for * their own developers exclusive use. Monopoly, anyone? */ BOOL WINAPI SHLWAPI_3(LPSTR lpszPath,DWORD dwWhich) @@ -1218,7 +1218,7 @@ static BOOL WINAPI SHLWAPI_PathFindInOtherDirs(LPWSTR lpszFile, DWORD dwWhich) * dwWhich [I] Type of executable to search for * * RETURNS - * Success: TRUE. The path to the executable is stored in sFile. + * Success: TRUE. The path to the executable is stored in lpszFile. * Failure: FALSE. The path to the executable is unchanged. */ BOOL WINAPI SHLWAPI_5(LPSTR lpszFile,LPCSTR *lppszOtherDirs,DWORD dwWhich) @@ -1331,7 +1331,7 @@ BOOL WINAPI PathFindOnPathW(LPWSTR lpszFile, LPCWSTR *lppszOtherDirs) * PARAMS * lpszDest [O] Destination for compacted path * lpszPath [I] Source path - * cchMax [I[ Maximum size of compacted path + * cchMax [I] Maximum size of compacted path * dwFlags [I] Reserved * * RETURNS @@ -1343,8 +1343,9 @@ BOOL WINAPI PathFindOnPathW(LPWSTR lpszFile, LPCWSTR *lppszOtherDirs) * The Win32 version of this function contains a bug: When cchMax == 7, * 8 bytes will be written to lpszDest. This bug is fixed in the Wine * implementation. + * * Some relative paths will be different when cchMax == 5 or 6. This occurs - * because Win32 will insert a \ in the compact filename, even if one is + * because Win32 will insert a "\" in lpszDest, even if one is * not present in the original path. */ BOOL WINAPI PathCompactPathExA(LPSTR lpszDest, LPCSTR lpszPath, @@ -1511,7 +1512,7 @@ BOOL WINAPI PathIsRelativeW (LPCWSTR lpszPath) * lpszPath [I] Path to check * * RETURNS - * TRUE If lpszPath is valid and a root path + * TRUE If lpszPath is valid and a root path, * FALSE Otherwise */ BOOL WINAPI PathIsRootA(LPCSTR lpszPath) @@ -1605,8 +1606,8 @@ BOOL WINAPI PathIsRootW(LPCWSTR lpszPath) * Although this function is prototyped as returning a BOOL, it returns * FILE_ATTRIBUTE_DIRECTORY for success. This means that code such as: * - * if (PathIsDirectoryA("c:\\windows\\") == TRUE) - * ... + *| if (PathIsDirectoryA("c:\\windows\\") == TRUE) + *| ... * * will always fail. */ @@ -1768,7 +1769,7 @@ static BOOL PathMatchSingleMaskW(LPCWSTR name, LPCWSTR mask) * * PARAMS * lpszPath [I] Path to check - * lpszMask [I} Search mask(s) + * lpszMask [I] Search mask(s) * * RETURNS * TRUE If lpszPath is valid and is matched @@ -1779,20 +1780,20 @@ static BOOL PathMatchSingleMaskW(LPCWSTR name, LPCWSTR mask) * pattern "*.*" is treated specially in that it matches all paths (for * backwards compatability with DOS). */ -BOOL WINAPI PathMatchSpecA(LPCSTR name, LPCSTR mask) +BOOL WINAPI PathMatchSpecA(LPCSTR lpszPath, LPCSTR lpszMask) { - TRACE("%s %s\n",name,mask); + TRACE("%s %s\n", lpszPath, lpszMask); - if (!lstrcmpA( mask, "*.*" )) return 1; /* we don't require a period */ + if (!lstrcmpA( lpszMask, "*.*" )) return 1; /* we don't require a period */ - while (*mask) + while (*lpszMask) { - if (PathMatchSingleMaskA(name,mask)) return 1; /* helper function */ - while (*mask && *mask!=';') mask = CharNextA(mask); - if (*mask==';') + if (PathMatchSingleMaskA(lpszPath,lpszMask)) return 1; /* helper function */ + while (*lpszMask && *lpszMask!=';') lpszMask = CharNextA(lpszMask); + if (*lpszMask==';') { - mask++; - while (*mask==' ') mask++; /* masks may be separated by "; " */ + lpszMask++; + while (*lpszMask==' ') lpszMask++; /* masks may be separated by "; " */ } } return 0; @@ -1882,7 +1883,7 @@ BOOL WINAPI PathIsSameRootW(LPCWSTR lpszPath1, LPCWSTR lpszPath2) * lpszPath [I] file to check * * RETURNS - * TRUE If lpszPath is a given registered content type + * TRUE If lpszPath is a given registered content type, * FALSE Otherwise. * * NOTES @@ -1991,7 +1992,7 @@ BOOL WINAPI PathIsFileSpecW(LPCWSTR lpszPath) * lpszPath [i] Path to check * * RETURNS - * TRUE If lpszPath has lpszPrefix as its prefix + * TRUE If lpszPath has lpszPrefix as its prefix, * FALSE If either path is NULL or lpszPrefix is not a prefix */ BOOL WINAPI PathIsPrefixA (LPCSTR lpszPrefix, LPCSTR lpszPath) @@ -2030,7 +2031,7 @@ BOOL WINAPI PathIsPrefixW(LPCWSTR lpszPrefix, LPCWSTR lpszPath) * * RETURNS * TRUE If lpszPath or dwAttrib are a system folder. - * FALSE If GetFileAttributesA fails or neither parameter is a system folder. + * FALSE If GetFileAttributesA() fails or neither parameter is a system folder. */ BOOL WINAPI PathIsSystemFolderA(LPCSTR lpszPath, DWORD dwAttrib) { @@ -2230,7 +2231,7 @@ BOOL WINAPI PathIsUNCServerShareW(LPCWSTR lpszPath) * lpszPath [I] Path to cnonicalize * * RETURNS - * Success: TRUE. lpszBuf contains the output path + * Success: TRUE. lpszBuf contains the output path, * Failure: FALSE, If input path is invalid. lpszBuf is undefined */ BOOL WINAPI PathCanonicalizeA(LPSTR lpszBuf, LPCSTR lpszPath) @@ -2363,7 +2364,7 @@ BOOL WINAPI PathCanonicalizeW(LPWSTR lpszBuf, LPCWSTR lpszPath) * lpszPath [I] Path to find next component in * * RETURNS - * Success: A pointer to the next component, or the end of the string + * Success: A pointer to the next component, or the end of the string, * Failure: NULL, If lpszPath is invalid * * NOTES @@ -2419,15 +2420,15 @@ LPWSTR WINAPI PathFindNextComponentW(LPCWSTR lpszPath) * * PARAMS * lpszPath [O] Path to add extension to - * lpszExtension [I} Extension to add to lpszPath + * lpszExtension [I] Extension to add to lpszPath * * RETURNS - * TRUE If the path was modified + * TRUE If the path was modified, * FALSE If lpszPath or lpszExtension are invalid, lpszPath has an * extension allready, or the new path length is too big. * * FIXME - * What version of shlwapi.dll adds "exe" if pszExtension is NULL? Win2k + * What version of shlwapi.dll adds "exe" if lpszExtension is NULL? Win2k * does not do this, so the behaviour was removed. */ BOOL WINAPI PathAddExtensionA(LPSTR lpszPath, LPCSTR lpszExtension) @@ -2480,7 +2481,7 @@ BOOL WINAPI PathAddExtensionW(LPWSTR lpszPath, LPCWSTR lpszExtension) * lpszPath [O] Path to convert. * * RETURNS - * TRUE If the path was an uppercase DOS path and was converted + * TRUE If the path was an uppercase DOS path and was converted, * FALSE Otherwise. */ BOOL WINAPI PathMakePrettyA(LPSTR lpszPath) @@ -2835,7 +2836,7 @@ end: * ch [I] Character to get the type of * * RETURNS - * A set of GCT_ bit flags (from shlwapi.h) indicating the character type. + * A set of GCT_ bit flags (from "shlwapi.h") indicating the character type. */ UINT WINAPI PathGetCharTypeA(UCHAR ch) { @@ -2909,7 +2910,7 @@ static BOOL SHLWAPI_UseSystemForSystemFolders() * * RETURNS * TRUE If the path was changed to/already was a system folder - * FALSE If the path is invalid or SetFileAttributesA fails + * FALSE If the path is invalid or SetFileAttributesA() fails */ BOOL WINAPI PathMakeSystemFolderA(LPCSTR lpszPath) { @@ -2968,12 +2969,12 @@ BOOL WINAPI PathMakeSystemFolderW(LPCWSTR lpszPath) * Swap the file extension in a path with another extension. * * PARAMS - * pszPath [O] Path to swap the extension in - * pszExt [I] The new extension + * lpszPath [O] Path to swap the extension in + * lpszExt [I] The new extension * * RETURNS - * TRUE if pszPath was modified - * FALSE if pszPath or pszExt is NULL, or the new path is too long + * TRUE if lpszPath was modified, + * FALSE if lpszPath or lpszExt is NULL, or the new path is too long */ BOOL WINAPI PathRenameExtensionA(LPSTR lpszPath, LPCSTR lpszExt) { @@ -3050,7 +3051,7 @@ BOOL WINAPI PathSearchAndQualifyW(LPCWSTR lpszPath, LPWSTR lpszBuf, UINT cchBuf) * * RETURNS * Success: A pointer to the next character after the root. - * Failure: NULL, if lpszPath is invalid, has no root or is a MB string. + * Failure: NULL, if lpszPath is invalid, has no root or is a multibyte string. */ LPSTR WINAPI PathSkipRootA(LPCSTR lpszPath) { @@ -3118,7 +3119,7 @@ LPWSTR WINAPI PathSkipRootW(LPCWSTR lpszPath) * dwFlags [I] Flags controlling the conversion * * RETURNS - * Success: S_OK. lpszPath contains the URL in path format + * Success: S_OK. lpszPath contains the URL in path format, * Failure: An HRESULT error code such as E_INVALIDARG. */ HRESULT WINAPI PathCreateFromUrlA(LPCSTR lpszUrl, LPSTR lpszPath, @@ -3209,6 +3210,7 @@ HRESULT WINAPI PathCreateFromUrlW(LPCWSTR lpszUrl, LPWSTR lpszPath, * * NOTES * lpszTo should be at least MAX_PATH in length. + * * Calling this function with relative paths for lpszFrom or lpszTo may * give erroneous results. * @@ -3216,8 +3218,9 @@ HRESULT WINAPI PathCreateFromUrlW(LPCWSTR lpszUrl, LPWSTR lpszPath, * may be referenced 1 byte beyond the end of the string. As a result random * garbage may be written to the output path, depending on what lies beyond * the last byte of the string. This bug occurs because of the behaviour of - * PathCommonPrefix (see notes for that function), and no workaround seems + * PathCommonPrefix() (see notes for that function), and no workaround seems * possible with Win32. + * * This bug has been fixed here, so for example the relative path from "\\" * to "\\" is correctly determined as "." in this implementation. */ @@ -3322,7 +3325,7 @@ BOOL WINAPI PathRelativePathToW(LPWSTR lpszPath, LPCWSTR lpszFrom, DWORD dwAttrF * RETURNS * Success: TRUE. * Failure: FALSE, if lpszPath is NULL, empty, not a directory, or calling - * SetFileAttributesA fails. + * SetFileAttributesA() fails. */ BOOL WINAPI PathUnmakeSystemFolderA(LPCSTR lpszPath) { @@ -3435,8 +3438,8 @@ VOID WINAPI PathSetDlgItemPathW(HWND hDlg, int id, LPCWSTR lpszPath) * lpszPath [I] Path to check * * RETURNS - * TRUE If path is a UNC share or mapped network drive - * FALSE If path is a local drive or cannot be determined + * TRUE If lpszPath is a UNC share or mapped network drive, or + * FALSE If lpszPath is a local drive or cannot be determined */ BOOL WINAPI PathIsNetworkPathA(LPCSTR lpszPath) { @@ -3486,7 +3489,7 @@ BOOL WINAPI PathIsNetworkPathW(LPCWSTR lpszPath) * lpszPath [I] Path to check * * RETURNS - * TRUE If path is a long file name + * TRUE If path is a long file name, * FALSE If path is a valid DOS 8.3 file name */ BOOL WINAPI PathIsLFNFileSpecA(LPCSTR lpszPath) @@ -3575,7 +3578,7 @@ BOOL WINAPI PathIsLFNFileSpecW(LPCWSTR lpszPath) * lpszPath [I] Directory to check * * RETURNS - * TRUE If the directory exists and contains no files + * TRUE If the directory exists and contains no files, * FALSE Otherwise */ BOOL WINAPI PathIsDirectoryEmptyA(LPCSTR lpszPath) @@ -3645,13 +3648,13 @@ BOOL WINAPI PathIsDirectoryEmptyW(LPCWSTR lpszPath) * dwCount [I] Number of elements in lppszArray * * RETURNS - * Success The index of the position of lpszSuffix in lppszArray - * Failure 0, if any parameters are invalid or lpszSuffix is not found + * Success: The index of the position of lpszSuffix in lppszArray + * Failure: 0, if any parameters are invalid or lpszSuffix is not found * * NOTES * The search is case sensitive. * The match is made against the end of the suffix string, so for example: - * lpszSuffix=fooBAR matches BAR, but lpszSuffix=fooBARfoo does not. + * lpszSuffix="fooBAR" matches "BAR", but lpszSuffix="fooBARfoo" does not. */ int WINAPI PathFindSuffixArrayA(LPCSTR lpszSuffix, LPCSTR *lppszArray, int dwCount) { @@ -3722,7 +3725,7 @@ int WINAPI PathFindSuffixArrayW(LPCWSTR lpszSuffix, LPCWSTR *lppszArray, int dwC * Nothing * * NOTES - * A decorations form is "path[n].ext" where n is an optional decimal number. + * A decorations form is "path[n].ext" where "n" is an optional decimal number. */ VOID WINAPI PathUndecorateA(LPSTR lpszPath) { diff --git a/dlls/shlwapi/reg.c b/dlls/shlwapi/reg.c index b6a7190e507..42077f47d21 100644 --- a/dlls/shlwapi/reg.c +++ b/dlls/shlwapi/reg.c @@ -89,13 +89,17 @@ HKEY REG_GetHKEYFromHUSKEY(HUSKEY hUSKey, BOOL which) * SHRegOpenUSKeyA [SHLWAPI.@] * * Opens a user-specific registry key + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from RegOpenKeyExA(). */ LONG WINAPI SHRegOpenUSKeyA( - LPCSTR Path, - REGSAM AccessType, - HUSKEY hRelativeUSKey, - PHUSKEY phNewUSKey, - BOOL fIgnoreHKCU) + LPCSTR Path, /* [I] Key name to open */ + REGSAM AccessType, /* [I] Access type */ + HUSKEY hRelativeUSKey, /* [I] Relative user key */ + PHUSKEY phNewUSKey, /* [O] Destination for created key */ + BOOL fIgnoreHKCU) /* [I] TRUE=Don't check HKEY_CURRENT_USER */ { HKEY openHKCUkey=0; HKEY openHKLMkey=0; @@ -155,7 +159,7 @@ LONG WINAPI SHRegOpenUSKeyA( /************************************************************************* * SHRegOpenUSKeyW [SHLWAPI.@] * - * Opens a user-specific registry key + * See SHRegOpenUSKeyA. */ LONG WINAPI SHRegOpenUSKeyW( LPCWSTR Path, @@ -221,10 +225,14 @@ LONG WINAPI SHRegOpenUSKeyW( /************************************************************************* * SHRegCloseUSKey [SHLWAPI.@] * - * Closes a user-specific registry key + * Close a user-specific registry key + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from RegCloseKey(). */ LONG WINAPI SHRegCloseUSKey( - HUSKEY hUSKey) + HUSKEY hUSKey) /* [I] Key to close */ { LPInternal_HUSKEY mihk = (LPInternal_HUSKEY)hUSKey; LONG ret = ERROR_SUCCESS; @@ -239,16 +247,22 @@ LONG WINAPI SHRegCloseUSKey( /************************************************************************* * SHRegQueryUSValueA [SHLWAPI.@] + * + * Query a user-specific registry value. + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from RegQueryValueExA(). */ LONG WINAPI SHRegQueryUSValueA( - HUSKEY hUSKey, /* [in] */ - LPCSTR pszValue, - LPDWORD pdwType, - LPVOID pvData, - LPDWORD pcbData, - BOOL fIgnoreHKCU, - LPVOID pvDefaultData, - DWORD dwDefaultDataSize) + HUSKEY hUSKey, /* [I] Key to query */ + LPCSTR pszValue, /* [I] Value name under hUSKey */ + LPDWORD pdwType, /* [O] Destination for value type */ + LPVOID pvData, /* [O] Destination for value data */ + LPDWORD pcbData, /* [O] Destination for value length */ + BOOL fIgnoreHKCU, /* [I] TRUE=Don't check HKEY_CURRENT_USER */ + LPVOID pvDefaultData, /* [I] Default data if pszValue does not exist */ + DWORD dwDefaultDataSize) /* [I] Length of pvDefaultData */ { LONG ret = ~ERROR_SUCCESS; LONG i, maxmove; @@ -288,9 +302,11 @@ LONG WINAPI SHRegQueryUSValueA( /************************************************************************* * SHRegQueryUSValueW [SHLWAPI.@] + * + * See SHRegQueryUSValueA. */ LONG WINAPI SHRegQueryUSValueW( - HUSKEY hUSKey, /* [in] */ + HUSKEY hUSKey, LPCWSTR pszValue, LPDWORD pdwType, LPVOID pvData, @@ -337,18 +353,24 @@ LONG WINAPI SHRegQueryUSValueW( /************************************************************************* * SHRegGetUSValueA [SHLWAPI.@] * - * Gets a user-specific registry value - * Will open the key, query the value, and close the key + * Get a user-specific registry value. + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from SHRegOpenUSKeyA() or SHRegQueryUSValueA(). + * + * NOTES + * This function opens pSubKey, queries the value, and then closes the key. */ LONG WINAPI SHRegGetUSValueA( - LPCSTR pSubKey, - LPCSTR pValue, - LPDWORD pwType, - LPVOID pvData, - LPDWORD pcbData, - BOOL flagIgnoreHKCU, - LPVOID pDefaultData, - DWORD wDefaultDataSize) + LPCSTR pSubKey, /* [I] Key name to open */ + LPCSTR pValue, /* [I] Value name to open */ + LPDWORD pwType, /* [O] Destination for the type of the value */ + LPVOID pvData, /* [O] Destination for the value */ + LPDWORD pcbData, /* [I] Destination for the length of the value **/ + BOOL flagIgnoreHKCU, /* [I] TRUE=Don't check HKEY_CURRENT_USER */ + LPVOID pDefaultData, /* [I] Default value if it doesn't exist */ + DWORD wDefaultDataSize) /* [I] Length of pDefaultData */ { HUSKEY myhuskey; LONG ret; @@ -371,8 +393,7 @@ LONG WINAPI SHRegGetUSValueA( /************************************************************************* * SHRegGetUSValueW [SHLWAPI.@] * - * Gets a user-specific registry value - * Will open the key, query the value, and close the key + * See SHRegGetUSValueA. */ LONG WINAPI SHRegGetUSValueW( LPCWSTR pSubKey, @@ -464,12 +485,25 @@ LONG WINAPI SHRegSetUSValueW( /************************************************************************* * SHRegGetBoolUSValueA [SHLWAPI.@] + * + * Get a user-specific registry boolean value. + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from SHRegOpenUSKeyA() or SHRegQueryUSValueA(). + * + * NOTES + * This function opens pszSubKey, queries the value, and then closes the key. + * + * Boolean values are one of the following: + * True: YES,TRUE,non-zero + * False: NO,FALSE,0 */ BOOL WINAPI SHRegGetBoolUSValueA( - LPCSTR pszSubKey, - LPCSTR pszValue, - BOOL fIgnoreHKCU, - BOOL fDefault) + LPCSTR pszSubKey, /* [I] Key name to open */ + LPCSTR pszValue, /* [I] Value name to open */ + BOOL fIgnoreHKCU, /* [I] TRUE=Don't check HKEY_CURRENT_USER */ + BOOL fDefault) /* [I] Default value to use if pszValue is not present */ { LONG retvalue; DWORD type, datalen, work; @@ -519,6 +553,8 @@ BOOL WINAPI SHRegGetBoolUSValueA( /************************************************************************* * SHRegGetBoolUSValueW [SHLWAPI.@] + * + * See SHRegGetBoolUSValueA. */ BOOL WINAPI SHRegGetBoolUSValueW( LPCWSTR pszSubKey, @@ -578,14 +614,20 @@ BOOL WINAPI SHRegGetBoolUSValueW( /************************************************************************* * SHRegQueryInfoUSKeyA [SHLWAPI.@] + * + * Get information about a user-specific registry key. + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from RegQueryInfoKeyA(). */ LONG WINAPI SHRegQueryInfoUSKeyA( - HUSKEY hUSKey, /* [in] */ - LPDWORD pcSubKeys, - LPDWORD pcchMaxSubKeyLen, - LPDWORD pcValues, - LPDWORD pcchMaxValueNameLen, - SHREGENUM_FLAGS enumRegFlags) + HUSKEY hUSKey, /* [I] Key to query */ + LPDWORD pcSubKeys, /* [O] Destination for number of sub keys */ + LPDWORD pcchMaxSubKeyLen, /* [O] Destination for the length of the biggest sub key name */ + LPDWORD pcValues, /* [O] Destination for number of values */ + LPDWORD pcchMaxValueNameLen,/* [O] Destination for the length of the biggest value */ + SHREGENUM_FLAGS enumRegFlags) /* [in] SHREGENUM_ flags from "shlwapi.h" */ { HKEY dokey; LONG ret; @@ -617,9 +659,11 @@ LONG WINAPI SHRegQueryInfoUSKeyA( /************************************************************************* * SHRegQueryInfoUSKeyW [SHLWAPI.@] + * + * See SHRegQueryInfoUSKeyA. */ LONG WINAPI SHRegQueryInfoUSKeyW( - HUSKEY hUSKey, /* [in] */ + HUSKEY hUSKey, LPDWORD pcSubKeys, LPDWORD pcchMaxSubKeyLen, LPDWORD pcValues, @@ -656,13 +700,19 @@ LONG WINAPI SHRegQueryInfoUSKeyW( /************************************************************************* * SHRegEnumUSKeyA [SHLWAPI.@] + * + * Enumerate a user-specific registry key. + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: An error code from RegEnumKeyExA(). */ LONG WINAPI SHRegEnumUSKeyA( - HUSKEY hUSKey, /* [in] */ - DWORD dwIndex, /* [in] */ - LPSTR pszName, /* [out] */ - LPDWORD pcchValueNameLen, /* [in/out] */ - SHREGENUM_FLAGS enumRegFlags) /* [in] */ + HUSKEY hUSKey, /* [in] Key to enumerate */ + DWORD dwIndex, /* [in] Index within hUSKey */ + LPSTR pszName, /* [out] Name of the enumerated value */ + LPDWORD pcchValueNameLen, /* [in/out] Length of pszName */ + SHREGENUM_FLAGS enumRegFlags) /* [in] SHREGENUM_ flags from "shlwapi.h" */ { HKEY dokey; @@ -689,13 +739,15 @@ LONG WINAPI SHRegEnumUSKeyA( /************************************************************************* * SHRegEnumUSKeyW [SHLWAPI.@] + * + * See SHRegEnumUSKeyA. */ LONG WINAPI SHRegEnumUSKeyW( - HUSKEY hUSKey, /* [in] */ - DWORD dwIndex, /* [in] */ - LPWSTR pszName, /* [out] */ - LPDWORD pcchValueNameLen, /* [in/out] */ - SHREGENUM_FLAGS enumRegFlags) /* [in] */ + HUSKEY hUSKey, + DWORD dwIndex, + LPWSTR pszName, + LPDWORD pcchValueNameLen, + SHREGENUM_FLAGS enumRegFlags) { HKEY dokey; @@ -722,6 +774,8 @@ LONG WINAPI SHRegEnumUSKeyW( /************************************************************************* * SHRegWriteUSValueA [SHLWAPI.@] + * + * */ LONG WINAPI SHRegWriteUSValueA(HUSKEY hUSKey, LPCSTR pszValue, DWORD dwType, LPVOID pvData, DWORD cbData, DWORD dwFlags) @@ -750,6 +804,8 @@ LONG WINAPI SHRegWriteUSValueA(HUSKEY hUSKey, LPCSTR pszValue, DWORD dwType, /************************************************************************* * SHRegWriteUSValueW [SHLWAPI.@] + * + * See SHRegWriteUSValueA. */ LONG WINAPI SHRegWriteUSValueW(HUSKEY hUSKey, LPCWSTR pszValue, DWORD dwType, LPVOID pvData, DWORD cbData, DWORD dwFlags) @@ -790,7 +846,7 @@ LONG WINAPI SHRegWriteUSValueW(HUSKEY hUSKey, LPCWSTR pszValue, DWORD dwType, * * RETURNS * Success: ERROR_SUCCESS. lpszPath contains the path. - * Failure: An error code from RegOpenKeyExA or SHQueryValueExA. + * Failure: An error code from RegOpenKeyExA() or SHQueryValueExA(). */ DWORD WINAPI SHRegGetPathA(HKEY hKey, LPCSTR lpszSubKey, LPCSTR lpszValue, LPSTR lpszPath, DWORD dwFlags) @@ -830,7 +886,7 @@ DWORD WINAPI SHRegGetPathW(HKEY hKey, LPCWSTR lpszSubKey, LPCWSTR lpszValue, * lpszSubKey [I] Name of sub key containing path to set * lpszValue [I] Name of value containing path to set * lpszPath [O] Path to write - * dwFlags [I] Reserved + * dwFlags [I] Reserved, must be 0. * * RETURNS * Success: ERROR_SUCCESS. @@ -888,7 +944,7 @@ DWORD WINAPI SHRegSetPathW(HKEY hKey, LPCWSTR lpszSubKey, LPCWSTR lpszValue, * * RETURNS * Success: ERROR_SUCCESS. Output parameters contain the details read. - * Failure: An error code from RegOpenKeyExA or SHQueryValueExA. + * Failure: An error code from RegOpenKeyExA() or SHQueryValueExA(). */ DWORD WINAPI SHGetValueA(HKEY hKey, LPCSTR lpszSubKey, LPCSTR lpszValue, LPDWORD pwType, LPVOID pvData, LPDWORD pcbData) @@ -954,11 +1010,11 @@ DWORD WINAPI SHGetValueW(HKEY hKey, LPCWSTR lpszSubKey, LPCWSTR lpszValue, * * RETURNS * Success: ERROR_SUCCESS. The value is set with the data given. - * Failure: An error code from RegCreateKeyExA or RegSetValueExA + * Failure: An error code from RegCreateKeyExA() or RegSetValueExA() * * NOTES - * If the sub key does not exist, it is created before the value is set. If - * The sub key is NULL or an empty string, then the value is added directly + * If lpszSubKey does not exist, it is created before the value is set. If + * lpszSubKey is NULL or an empty string, then the value is added directly * to hKey instead. */ DWORD WINAPI SHSetValueA(HKEY hKey, LPCSTR lpszSubKey, LPCSTR lpszValue, @@ -1017,7 +1073,7 @@ DWORD WINAPI SHSetValueW(HKEY hKey, LPCWSTR lpszSubKey, LPCWSTR lpszValue, /************************************************************************* * SHQueryInfoKeyA [SHLWAPI.@] * - * Get information about a registry key. See RegQueryInfoKeyA. + * Get information about a registry key. See RegQueryInfoKeyA(). */ LONG WINAPI SHQueryInfoKeyA(HKEY hKey, LPDWORD pwSubKeys, LPDWORD pwSubKeyMax, LPDWORD pwValues, LPDWORD pwValueMax) @@ -1056,11 +1112,11 @@ LONG WINAPI SHQueryInfoKeyW(HKEY hKey, LPDWORD pwSubKeys, LPDWORD pwSubKeyMax, * pcbData [O] Optional pointer updated with the values size * * RETURNS - * Success: ERROR_SUCCESS. Any non-NULL output parameters are updated with + * Success: ERROR_SUCCESS. Any non NULL output parameters are updated with * information about the value. * Failure: ERROR_OUTOFMEMORY if memory allocation fails, or the type of the * data is REG_EXPAND_SZ and pcbData is NULL. Otherwise an error - * code from RegQueryValueExA or ExpandEnvironmentStringsA. + * code from RegQueryValueExA() or ExpandEnvironmentStringsA(). * * NOTES * Either pwType, pvData or pcbData may be NULL if the caller doesn't want @@ -1070,16 +1126,16 @@ LONG WINAPI SHQueryInfoKeyW(HKEY hKey, LPDWORD pwSubKeys, LPDWORD pwSubKeyMax, * value returned will be truncated if it is of type REG_SZ and bigger than * the buffer given to store it. * - * REG_EXPAND_SZ - * case 1: the unexpanded string is smaller than the expanded one - * subcase 1: the buffer is to small to hold the unexpanded string: + * REG_EXPAND_SZ: + * case-1: the unexpanded string is smaller than the expanded one + * subcase-1: the buffer is to small to hold the unexpanded string: * function fails and returns the size of the unexpanded string. * - * subcase 2: buffer is to small to hold the expanded string: + * subcase-2: buffer is to small to hold the expanded string: * the function return success (!!) and the result is truncated - * *** This is clearly a error in the native implemantation. *** + * *** This is clearly a error in the native implementation. *** * - * case 2: the unexpanded string is bigger than the expanded one + * case-2: the unexpanded string is bigger than the expanded one * The buffer must have enough space to hold the unexpanded * string even if the result is smaller. * @@ -1207,8 +1263,8 @@ DWORD WINAPI SHQueryValueExW(HKEY hKey, LPCWSTR lpszValue, * * RETURNS * Success: ERROR_SUCCESS. The key is deleted. - * Failure: An error code from RegOpenKeyExA, RegQueryInfoKeyA, - * RegEnumKeyExA or RegDeleteKeyA. + * Failure: An error code from RegOpenKeyExA(), RegQueryInfoKeyA(), + * RegEnumKeyExA() or RegDeleteKeyA(). */ DWORD WINAPI SHDeleteKeyA(HKEY hKey, LPCSTR lpszSubKey) { @@ -1318,8 +1374,8 @@ DWORD WINAPI SHDeleteKeyW(HKEY hKey, LPCWSTR lpszSubKey) * RETURNS * Success: ERROR_SUCCESS. The key is deleted. * Failure: If the key is not empty, returns ERROR_KEY_HAS_CHILDREN. Otherwise - * returns an error code from RegOpenKeyExA, RegQueryInfoKeyA or - * RegDeleteKeyA. + * returns an error code from RegOpenKeyExA(), RegQueryInfoKeyA() or + * RegDeleteKeyA(). */ DWORD WINAPI SHDeleteEmptyKeyA(HKEY hKey, LPCSTR lpszSubKey) { @@ -1385,7 +1441,7 @@ DWORD WINAPI SHDeleteEmptyKeyW(HKEY hKey, LPCWSTR lpszSubKey) * * RETURNS * Success: ERROR_SUCCESS. The key has been deleted if it was an orphan. - * Failure: An error from RegOpenKeyExA, RegQueryValueExA, or RegDeleteKeyA. + * Failure: An error from RegOpenKeyExA(), RegQueryValueExA(), or RegDeleteKeyA(). */ DWORD WINAPI SHDeleteOrphanKeyA(HKEY hKey, LPCSTR lpszSubKey) { @@ -1452,7 +1508,7 @@ DWORD WINAPI SHDeleteOrphanKeyW(HKEY hKey, LPCWSTR lpszSubKey) * * RETURNS * Success: ERROR_SUCCESS. The value is deleted. - * Failure: An error code from RegOpenKeyExA or RegDeleteValueA. + * Failure: An error code from RegOpenKeyExA() or RegDeleteValueA(). */ DWORD WINAPI SHDeleteValueA(HKEY hKey, LPCSTR lpszSubKey, LPCSTR lpszValue) { @@ -1504,7 +1560,7 @@ DWORD WINAPI SHDeleteValueW(HKEY hKey, LPCWSTR lpszSubKey, LPCWSTR lpszValue) * * RETURN * Success: ERROR_SUCCESS. lpszSubKey and pwLen are updated. - * Failure: An error code from RegEnumKeyExA. + * Failure: An error code from RegEnumKeyExA(). */ LONG WINAPI SHEnumKeyExA(HKEY hKey, DWORD dwIndex, LPSTR lpszSubKey, LPDWORD pwLen) @@ -1543,7 +1599,7 @@ LONG WINAPI SHEnumKeyExW(HKEY hKey, DWORD dwIndex, LPWSTR lpszSubKey, * * RETURNS * Success: ERROR_SUCCESS. Output parameters are updated. - * Failure: An error code from RegEnumValueA. + * Failure: An error code from RegEnumValueA(). */ LONG WINAPI SHEnumValueA(HKEY hKey, DWORD dwIndex, LPSTR lpszValue, LPDWORD pwLen, LPDWORD pwType, @@ -1575,7 +1631,20 @@ LONG WINAPI SHEnumValueW(HKEY hKey, DWORD dwIndex, LPWSTR lpszValue, /************************************************************************* * @ [SHLWAPI.205] * - * Wrapper for SHGetValueA in case machine is in safe mode. + * Get a value from the registry. + * + * PARAMS + * hKey [I] Handle to registry key + * pSubKey [I] Name of sub key containing value to get + * pValue [I] Name of value to get + * pwType [O] Destination for the values type + * pvData [O] Destination for the values data + * pbData [O] Destination for the values size + * + * RETURNS + * Success: ERROR_SUCCESS. Output parameters contain the details read. + * Failure: An error code from RegOpenKeyExA() or SHQueryValueExA(), + * or ERROR_INVALID_FUNCTION in the machine is in safe mode. */ DWORD WINAPI SHLWAPI_205(HKEY hkey, LPCSTR pSubKey, LPCSTR pValue, LPDWORD pwType, LPVOID pvData, LPDWORD pbData) @@ -1843,6 +1912,14 @@ BOOL WINAPI SHLWAPI_327(LPCWSTR lpszType) /************************************************************************* * SHRegDuplicateHKey [SHLWAPI.@] + * + * Create a duplicate of a registry handle. + * + * PARAMS + * hKey [I] key to duplicate. + * + * RETURNS + * A new handle pointing to the same key as hKey. */ HKEY WINAPI SHRegDuplicateHKey(HKEY hKey) { @@ -1871,7 +1948,8 @@ HKEY WINAPI SHRegDuplicateHKey(HKEY hKey) * * NOTES * If hKeyDst is a key under hKeySrc, this function will misbehave - * (It will loop until out of stack, or the registry is full). + * (It will loop until out of stack, or the registry is full). This + * bug is present in Win32 also. */ DWORD WINAPI SHCopyKeyA(HKEY hKeyDst, LPCSTR lpszSubKey, HKEY hKeySrc, DWORD dwReserved) { diff --git a/dlls/shlwapi/regstream.c b/dlls/shlwapi/regstream.c index 4c36bb75b49..0fe4112e480 100644 --- a/dlls/shlwapi/regstream.c +++ b/dlls/shlwapi/regstream.c @@ -469,14 +469,14 @@ IStream * WINAPI SHOpenRegStreamW(HKEY hkey, LPCWSTR pszSubkey, /************************************************************************* * @ [SHLWAPI.12] * - * Create a stream on a block of memory. + * Create an IStream object on a block of memory. * * PARAMS - * lpbData [I] Memory block to create the stream on + * lpbData [I] Memory block to create the IStream object on * dwDataLen [I] Length of data block * * RETURNS - * Success: A pointer to the stream object. + * Success: A pointer to the IStream object. * Failure: NULL, if any parameters are invalid or an error occurs. * * NOTES @@ -508,16 +508,16 @@ IStream * WINAPI SHLWAPI_12(LPBYTE lpbData, DWORD dwDataLen) /************************************************************************* * SHCreateStreamWrapper [SHLWAPI.@] * - * Create a stream on a block of memory. + * Create an IStream object on a block of memory. * * PARAMS - * lpbData [I] Memory block to create the stream on + * lpbData [I] Memory block to create the IStream object on * dwDataLen [I] Length of data block * dwReserved [I] Reserved, Must be 0. - * lppStream [O] Destination for stream object + * lppStream [O] Destination for IStream object * * RETURNS - * Success: S_OK. lppStream contains the new stream object. + * Success: S_OK. lppStream contains the new IStream object. * Failure: E_INVALIDARG, if any parameters are invalid, * E_OUTOFMEMORY if memory allocation fails. * diff --git a/dlls/shlwapi/shlwapi_main.c b/dlls/shlwapi/shlwapi_main.c index e0f6eece174..9041fb1a624 100644 --- a/dlls/shlwapi/shlwapi_main.c +++ b/dlls/shlwapi/shlwapi_main.c @@ -39,6 +39,20 @@ HMODULE SHLWAPI_hversion = 0; DWORD SHLWAPI_ThreadRef_index = -1; +/************************************************************************* + * SHLWAPI {SHLWAPI} + * + * The Shell Light-Weight Api dll provides a large number of utility functions + * which are commonly required by Win32 programs. Originally distributed with + * Internet Explorer as a free download, it became a core part of Windows when + * Internet Explorer was 'integrated' into the O/S with the release of Win98. + * + * All functions exported by ordinal are undocumented by MS. The vast majority + * of these are wrappers for Unicode functions that may not exist on early 16 + * bit platforms. The remainder perform various small tasks and presumably were + * added to facilitate code reuse amongst the MS developers. + */ + /************************************************************************* * SHLWAPI DllMain * @@ -71,35 +85,40 @@ BOOL WINAPI DllMain(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID fImpLoad) /*********************************************************************** * DllGetVersion [SHLWAPI.@] * - * Retrieves version information of the 'SHLWAPI.DLL' + * Retrieve "shlwapi.dll" version information. * * PARAMS * pdvi [O] pointer to version information structure. * * RETURNS - * Success: S_OK - * Failure: E_INVALIDARG + * Success: S_OK. pdvi is updated with the version information + * Failure: E_INVALIDARG, if pdvi->cbSize is not set correctly. * * NOTES - * Returns version of a SHLWAPI.dll from IE5.01. + * You may pass either a DLLVERSIONINFO of DLLVERSIONINFO2 structure + * as pdvi, provided that the size is set correctly. + * Returns version as shlwapi.dll from IE5.01. */ - HRESULT WINAPI SHLWAPI_DllGetVersion (DLLVERSIONINFO *pdvi) { - if (pdvi->cbSize != sizeof(DLLVERSIONINFO)) - { - WARN("wrong DLLVERSIONINFO size from app\n"); - return E_INVALIDARG; - } + DLLVERSIONINFO2 *pdvi2 = (DLLVERSIONINFO2*)pdvi; - pdvi->dwMajorVersion = 5; - pdvi->dwMinorVersion = 0; - pdvi->dwBuildNumber = 2314; - pdvi->dwPlatformID = 1000; + TRACE("(%p)\n",pdvi); - TRACE("%lu.%lu.%lu.%lu\n", - pdvi->dwMajorVersion, pdvi->dwMinorVersion, - pdvi->dwBuildNumber, pdvi->dwPlatformID); - - return S_OK; + switch (pdvi2->info1.cbSize) + { + case sizeof(DLLVERSIONINFO2): + pdvi2->dwFlags = 0; + pdvi2->ullVersion = MAKEDLLVERULL(5, 0, 2314, 0); + /* Fall through */ + case sizeof(DLLVERSIONINFO): + pdvi2->info1.dwMajorVersion = 5; + pdvi2->info1.dwMinorVersion = 0; + pdvi2->info1.dwBuildNumber = 2314; + pdvi2->info1.dwPlatformID = 1000; + return S_OK; + } + if (pdvi) + WARN("pdvi->cbSize = %ld, unhandled\n", pdvi2->info1.cbSize); + return E_INVALIDARG; } diff --git a/dlls/shlwapi/string.c b/dlls/shlwapi/string.c index 420ea00c94f..7b7d4a5f4cc 100644 --- a/dlls/shlwapi/string.c +++ b/dlls/shlwapi/string.c @@ -113,7 +113,7 @@ static BOOL WINAPI SHLWAPI_ChrCmpA(WORD ch1, WORD ch2) } /************************************************************************* - * ChrCmpIA [SHLWAPI.385] + * ChrCmpIA (SHLWAPI.385) * * Compare two characters, ignoring case. * @@ -367,9 +367,9 @@ INT WINAPI StrCmpNW(LPCWSTR lpszStr, LPCWSTR lpszComp, INT iLen) * The Win32 version of this function is _completely_ broken for cases * where iLen is greater than the length of lpszComp. Examples: * - * StrCmpNIA("foo.gif", "foo", 5) is -1 under Win32; Should return 1. - * StrCmpNIA("\", "\\", 3) is 0 under Win32; Should return -1. - * StrCmpNIA("\", "\..\foo\", 3) is 1 under Win32; Should return -1. + *| StrCmpNIA("foo.gif", "foo", 5) is -1 under Win32; Should return 1. + *| StrCmpNIA("\", "\\", 3) is 0 under Win32; Should return -1. + *| StrCmpNIA("\", "\..\foo\", 3) is 1 under Win32; Should return -1. * * This implementation behaves correctly, since it is unlikely any * applications actually rely on this function being broken. @@ -893,8 +893,8 @@ BOOL WINAPI StrToIntExW(LPCWSTR lpszStr, DWORD dwFlags, LPINT lpiRet) * Failure: NULL, if memory cannot be allocated * * NOTES - * The string memory is allocated with LocalAlloc, and so should be released - * by calling LocalFree. + * The string memory is allocated with LocalAlloc(), and so should be released + * by calling LocalFree(). */ LPSTR WINAPI StrDupA(LPCSTR lpszStr) { @@ -1342,7 +1342,7 @@ LPWSTR WINAPI StrCatBuffW(LPWSTR lpszStr, LPCWSTR lpszCat, INT cchMax) * RETURNS * Success: S_OK. lpszDest contains up to dwLen characters of the string. * If lpStrRet is of type STRRET_WSTR, its memory is freed with - * CoTaskMemFree and its type set to STRRET_CSTRA. + * CoTaskMemFree() and its type set to STRRET_CSTRA. * Failure: E_FAIL, if any parameters are invalid. */ HRESULT WINAPI StrRetToBufA (LPSTRRET src, const ITEMIDLIST *pidl, LPSTR dest, DWORD len) @@ -1716,7 +1716,7 @@ static HRESULT WINAPI _SHStrDupAA(LPCSTR src, LPSTR * dest) int len = 0; if (src) { - len = lstrlenA(src) + 1; + len = lstrlenA(src) + 1; *dest = CoTaskMemAlloc(len); } else { *dest = NULL; @@ -1736,7 +1736,7 @@ static HRESULT WINAPI _SHStrDupAA(LPCSTR src, LPSTR * dest) /************************************************************************* * SHStrDupA * - * Return a Unicode copy of a string, in memory allocated by CoTaskMemAlloc. + * Return a Unicode copy of a string, in memory allocated by CoTaskMemAlloc(). * * PARAMS * lpszStr [I] String to copy @@ -1753,7 +1753,7 @@ HRESULT WINAPI SHStrDupA(LPCSTR src, LPWSTR * dest) int len = 0; if (src) { - len = MultiByteToWideChar(0,0,src,-1,0,0) * sizeof(WCHAR); + len = MultiByteToWideChar(0,0,src,-1,0,0)* sizeof(WCHAR); *dest = CoTaskMemAlloc(len); } else { *dest = NULL; @@ -1902,17 +1902,19 @@ static int SHLWAPI_WriteTimeClass(LPWSTR lpszOut, DWORD dwValue, * NOTES * This implementation mimics the Win32 behaviour of always writing a leading * space before the time interval begins. + * * iDigits is used to provide approximate times if accuracy is not important. * This number of digits will be written of the first non-zero time class * (hours/minutes/seconds). If this does not complete the time classification, * the remaining digits are changed to zeros (i.e. The time is _not_ rounded). * If there are digits remaining following the writing of a time class, the * next time class will be written. + * * For example, given dwMS represents 138 hours,43 minutes and 15 seconds, the * following will result from the given values of iDigits: * - * iDigits 1 2 3 4 5 ... - * lpszStr "100 hr" "130 hr" "138 hr" "138 hr 40 min" "138 hr 43 min" ... + *| iDigits 1 2 3 4 5 ... + *| lpszStr "100 hr" "130 hr" "138 hr" "138 hr 40 min" "138 hr 43 min" ... */ INT WINAPI StrFromTimeIntervalA(LPSTR lpszStr, UINT cchMax, DWORD dwMS, int iDigits) @@ -2186,7 +2188,7 @@ typedef struct tagSHLWAPI_BYTEFORMATS * lpszDest. * * NOTES - * There is no StrFormatByteSize64W function, it is called StrFormatByteSizeW. + * There is no StrFormatByteSize64W function, it is called StrFormatByteSizeW(). */ LPSTR WINAPI StrFormatByteSize64A(LONGLONG llBytes, LPSTR lpszDest, UINT cchMax) { @@ -2293,8 +2295,8 @@ LPWSTR WINAPI StrFormatByteSizeW(LONGLONG llBytes, LPWSTR lpszDest, * lpszDest. * * NOTES - * The ASCII and Unicode versions of this function accept a different - * integer size for dwBytes. See StrFormatByteSize64A. + * The Ascii and Unicode versions of this function accept a different + * integer type for dwBytes. See StrFormatByteSize64A(). */ LPSTR WINAPI StrFormatByteSizeA(DWORD dwBytes, LPSTR lpszDest, UINT cchMax) { diff --git a/dlls/shlwapi/thread.c b/dlls/shlwapi/thread.c index c13106683a2..2c0f2eece91 100644 --- a/dlls/shlwapi/thread.c +++ b/dlls/shlwapi/thread.c @@ -104,7 +104,7 @@ WINAPI _CreateAllAccessSecurityAttributes( * Get an interface to the shell explorer. * * PARAMS - * lpUnknown [O] pointer to recieve interface. + * lppUnknown [O] pointer to recieve IUnknown interface. * * RETURNS * Success: S_OK. lppUnknown contains the explorer interface. @@ -141,8 +141,8 @@ typedef struct tagSHLWAPI_THREAD_INFO * lppUnknown [O] Destination to receive object reference * * RETURNS - * Success: S_OK. lppUnk is set to the object reference. - * Failure: E_NOINTERFACE, if an error occurs or lppUnk is invalid. + * Success: S_OK. lppUnknown is set to the object reference. + * Failure: E_NOINTERFACE, if an error occurs or lppUnknown is NULL. */ HRESULT WINAPI SHGetThreadRef(IUnknown **lppUnknown) { @@ -166,11 +166,11 @@ HRESULT WINAPI SHGetThreadRef(IUnknown **lppUnknown) * Store a per-thread object reference. * * PARAMS - * lpUnk [I] Object reference to store + * lpUnknown [I] Object reference to store * * RETURNS - * Success: S_OK. lpUnk is stored and can be retrieved by SHGetThreadRef() - * Failure: E_NOINTERFACE, if an error occurs or lpUnk is invalid. + * Success: S_OK. lpUnknown is stored and can be retrieved by SHGetThreadRef() + * Failure: E_NOINTERFACE, if an error occurs or lpUnknown is NULL. */ HRESULT WINAPI SHSetThreadRef(IUnknown *lpUnknown) { @@ -254,9 +254,7 @@ static DWORD WINAPI SHLWAPI_ThreadWrapper(PVOID pTi) } /************************************************************************* - * @ [SHLWAPI.16] - * - * SHCreateThread + * SHCreateThread [SHLWAPI.16] * * Create a new thread. * diff --git a/dlls/shlwapi/url.c b/dlls/shlwapi/url.c index 416dc5924b1..8a1bcef8e2f 100644 --- a/dlls/shlwapi/url.c +++ b/dlls/shlwapi/url.c @@ -259,8 +259,15 @@ static BOOL URL_JustLocation(LPCWSTR str) /************************************************************************* * @ [SHLWAPI.1] * - * Identifies the Internet "scheme" in the passed string. ASCII based. - * Also determines start and length of item after the ':' + * Parse a Url into its constituent parts. + * + * PARAMS + * x [I] Url to parse + * y [O] Undocumented structure holding the parsed information + * + * RETURNS + * Success: S_OK. y contains the parsed Url details. + * Failure: An HRESULT error code. */ DWORD WINAPI SHLWAPI_1 (LPCSTR x, UNKNOWN_SHLWAPI_1 *y) { @@ -314,8 +321,7 @@ DWORD WINAPI SHLWAPI_1 (LPCSTR x, UNKNOWN_SHLWAPI_1 *y) /************************************************************************* * @ [SHLWAPI.2] * - * Identifies the Internet "scheme" in the passed string. UNICODE based. - * Also determines start and length of item after the ':' + * Unicode version of SHLWAPI_1. */ DWORD WINAPI SHLWAPI_2 (LPCWSTR x, UNKNOWN_SHLWAPI_2 *y) { @@ -375,7 +381,27 @@ DWORD WINAPI SHLWAPI_2 (LPCWSTR x, UNKNOWN_SHLWAPI_2 *y) /************************************************************************* * UrlCanonicalizeA [SHLWAPI.@] * - * Uses the W version to do job. + * Canonicalize a Url. + * + * PARAMS + * pszUrl [I] Url to cCanonicalize + * pszCanonicalized [O] Destination for converted Url. + * pcchCanonicalized [I/O] Length of pszUrl, destination for length of pszCanonicalized + * dwFlags [I] Flags controlling the conversion. + * + * RETURNS + * Success: S_OK. The pszCanonicalized contains the converted Url. + * Failure: E_POINTER, if *pcchCanonicalized is too small. + * + * MSDN is wrong (at 10/30/01 - go figure). This should support the + * following flags: GLA + *| URL_DONT_ESCAPE_EXTRA_INFO 0x02000000 + *| URL_ESCAPE_SPACES_ONLY 0x04000000 + *| URL_ESCAPE_PERCENT 0x00001000 + *| URL_ESCAPE_UNSAFE 0x10000000 + *| URL_UNESCAPE 0x10000000 + *| URL_DONT_SIMPLIFY 0x08000000 + *| URL_ESCAPE_SEGMENT_ONLY 0x00002000 */ HRESULT WINAPI UrlCanonicalizeA(LPCSTR pszUrl, LPSTR pszCanonicalized, LPDWORD pcchCanonicalized, DWORD dwFlags) @@ -416,16 +442,7 @@ HRESULT WINAPI UrlCanonicalizeA(LPCSTR pszUrl, LPSTR pszCanonicalized, /************************************************************************* * UrlCanonicalizeW [SHLWAPI.@] * - * - * MSDN is wrong (at 10/30/01 - go figure). This should support the - * following flags: GLA - * URL_DONT_ESCAPE_EXTRA_INFO 0x02000000 - * URL_ESCAPE_SPACES_ONLY 0x04000000 - * URL_ESCAPE_PERCENT 0x00001000 - * URL_ESCAPE_UNSAFE 0x10000000 - * URL_UNESCAPE 0x10000000 - * URL_DONT_SIMPLIFY 0x08000000 - * URL_ESCAPE_SEGMENT_ONLY 0x00002000 + * See UrlCanonicalizeA. */ HRESULT WINAPI UrlCanonicalizeW(LPCWSTR pszUrl, LPWSTR pszCanonicalized, LPDWORD pcchCanonicalized, DWORD dwFlags) @@ -886,6 +903,7 @@ HRESULT WINAPI UrlCombineW(LPCWSTR pszBase, LPCWSTR pszRelative, * * Converts unsafe characters into their escape sequences. * + * NOTES * The converted string is returned in pszEscaped if the buffer size * (which should be supplied in pcchEscaped) is large enough, in this * case the function returns S_OK and pcchEscaped contains the length @@ -900,10 +918,10 @@ HRESULT WINAPI UrlCombineW(LPCWSTR pszBase, LPCWSTR pszRelative, * * BUGS: * Have now implemented the following flags: - * URL_ESCAPE_SPACES_ONLY - * URL_DONT_ESCAPE_EXTRA_INFO - * URL_ESCAPE_SEGMENT_ONLY - * URL_ESCAPE_PERCENT + *| URL_ESCAPE_SPACES_ONLY + *| URL_DONT_ESCAPE_EXTRA_INFO + *| URL_ESCAPE_SEGMENT_ONLY + *| URL_ESCAPE_PERCENT * Initial testing seems to indicate that this is now working like * native shlwapi version 5. Note that these functions did not work * well (or at all) in shlwapi version 4. @@ -980,7 +998,7 @@ HRESULT WINAPI UrlEscapeA( /************************************************************************* * UrlEscapeW [SHLWAPI.@] * - * See UrlEscapeA for list of assumptions, bugs, and FIXMEs + * See UrlEscapeA. */ HRESULT WINAPI UrlEscapeW( LPCWSTR pszUrl, @@ -1072,17 +1090,20 @@ HRESULT WINAPI UrlEscapeW( * * Converts escape sequences back to ordinary characters. * - * If URL_ESCAPE_INPLACE is set in dwFlags then pszUnescaped and - * pcchUnescaped are ignored and the converted string is returned in - * pszUrl, otherwise the string is returned in pszUnescaped. - * pcchUnescaped should contain the size of pszUnescaped on calling - * and will contain the length the the returned string on return if - * the buffer is big enough else it will contain the buffer size - * required (including room for the '\0'). The function returns S_OK - * on success or E_POINTER if the buffer is not large enough. If the - * URL_DONT_ESCAPE_EXTRA_INFO flag is set then the conversion stops at - * the first occurrence of either '?' or '#'. + * PARAMS + * pszUrl [I/O] Url to convert + * pszUnescaped [O] Destination for converted Url + * pcchUnescaped [I/O] Size of output string + * dwFlags [I] URL_ESCAPE_ Flags from "shlwapi.h" * + * RETURNS + * Success: S_OK. The converted value is in pszUnescaped, or in pszUrl if + * dwFlags includes URL_ESCAPE_INPLACE. + * Failure: E_POINTER if the converted Url is bigger than pcchUnescaped. In + * this case pcchUnescaped is set to the size required. + * NOTES + * If dwFlags includes URL_DONT_ESCAPE_EXTRA_INFO, the conversion stops at + * the first occurrence of either '?' or '#'. */ HRESULT WINAPI UrlUnescapeA( LPCSTR pszUrl, @@ -1146,7 +1167,7 @@ HRESULT WINAPI UrlUnescapeA( /************************************************************************* * UrlUnescapeW [SHLWAPI.@] * - * See UrlUnescapeA for list of assumptions, bugs, and FIXMEs + * See UrlUnescapeA. */ HRESULT WINAPI UrlUnescapeW( LPCWSTR pszUrl, @@ -1210,21 +1231,31 @@ HRESULT WINAPI UrlUnescapeW( /************************************************************************* * UrlGetLocationA [SHLWAPI.@] * - * Bugs/Features: + * Get the location from a Url. + * + * PARAMS + * pszUrl [I] Url to get the location from + * + * RETURNS + * A pointer to the start of the location in pszUrl, or NULL if there is + * no location. + * + * NOTES * MSDN (as of 2001-11-01) says that: * "The location is the segment of the URL starting with a ? * or # character." * Neither V4 nor V5 of shlwapi.dll implement the '?' and always return * a NULL. + * * MSDN further states that: * "If a file URL has a query string, the returned string is * the query string." * In all test cases if the scheme starts with "fi" then a NULL is * returned. V5 gives the following results: - * NULL file://aa/b/cd#hohoh - * #hohoh http://aa/b/cd#hohoh - * NULL fi://aa/b/cd#hohoh - * #hohoh ff://aa/b/cd#hohoh + *| NULL file://aa/b/cd#hohoh + *| #hohoh http://aa/b/cd#hohoh + *| NULL fi://aa/b/cd#hohoh + *| #hohoh ff://aa/b/cd#hohoh */ LPCSTR WINAPI UrlGetLocationA( LPCSTR pszUrl) @@ -1246,7 +1277,7 @@ LPCSTR WINAPI UrlGetLocationA( /************************************************************************* * UrlGetLocationW [SHLWAPI.@] * - * See UrlGetLocationA for list of assumptions, bugs, and FIXMEs + * See UrlGetLocationA. */ LPCWSTR WINAPI UrlGetLocationW( LPCWSTR pszUrl) @@ -1319,6 +1350,16 @@ INT WINAPI UrlCompareW( * HashData [SHLWAPI.@] * * Hash an input block into a variable sized digest. + * + * PARAMS + * lpSrc [I] Input block + * nSrcLen [I] Length of lpSrc + * lpDest [I] Output for hash digest + * nDestLen [I] Length of lpDest + * + * RETURNS + * Success: TRUE. lpDest is filled with the computed hash value. + * Failure: FALSE, if any argument is invalid. */ BOOL WINAPI HashData(const unsigned char *lpSrc, INT nSrcLen, unsigned char *lpDest, INT nDestLen) @@ -1351,7 +1392,16 @@ BOOL WINAPI HashData(const unsigned char *lpSrc, INT nSrcLen, /************************************************************************* * UrlHashA [SHLWAPI.@] * - * Hash an ASCII URL. + * Produce a Hash from a Url. + * + * PARAMS + * pszUrl [I] Url to hash + * lpDest [O] Destinationh for hash + * nDestLen [I] Length of lpDest + * + * RETURNS + * Success: S_OK. lpDest is filled with the computed hash value. + * Failure: E_INVALIDARG, if any argument is invalid. */ HRESULT WINAPI UrlHashA(LPCSTR pszUrl, unsigned char *lpDest, INT nDestLen) { @@ -1420,7 +1470,7 @@ HRESULT WINAPI UrlApplySchemeA(LPCSTR pszIn, LPSTR pszOut, LPDWORD pcchOut, DWOR return ret; } -HRESULT URL_GuessScheme(LPCWSTR pszIn, LPWSTR pszOut, LPDWORD pcchOut) +static HRESULT URL_GuessScheme(LPCWSTR pszIn, LPWSTR pszOut, LPDWORD pcchOut) { HKEY newkey; BOOL j; @@ -1564,6 +1614,16 @@ HRESULT WINAPI UrlApplySchemeW(LPCWSTR pszIn, LPWSTR pszOut, LPDWORD pcchOut, DW /************************************************************************* * UrlIsA [SHLWAPI.@] + * + * Determine if a Url is of a certain class. + * + * PARAMS + * pszUrl [I] Url to check + * Urlis [I] URLIS_ constant from "shlwapi.h" + * + * RETURNS + * TRUE if pszUrl belongs to the class type in Urlis. + * FALSE Otherwise. */ BOOL WINAPI UrlIsA(LPCSTR pszUrl, URLIS Urlis) { @@ -1595,6 +1655,8 @@ BOOL WINAPI UrlIsA(LPCSTR pszUrl, URLIS Urlis) /************************************************************************* * UrlIsW [SHLWAPI.@] + * + * See UrlIsA. */ BOOL WINAPI UrlIsW(LPCWSTR pszUrl, URLIS Urlis) { @@ -1642,6 +1704,18 @@ BOOL WINAPI UrlIsNoHistoryW(LPCWSTR pszUrl) /************************************************************************* * UrlIsOpaqueA [SHLWAPI.@] + * + * Determine if a Url is opaque. + * + * PARAMS + * pszUrl [I] Url to check + * + * RETURNS + * TRUE if pszUrl is opaque, + * FALSE Otherwise. + * + * NOTES + * An opaque Url is one that does not start with "://". */ BOOL WINAPI UrlIsOpaqueA(LPCSTR pszUrl) { @@ -1650,6 +1724,8 @@ BOOL WINAPI UrlIsOpaqueA(LPCSTR pszUrl) /************************************************************************* * UrlIsOpaqueW [SHLWAPI.@] + * + * See UrlIsOpaqueA. */ BOOL WINAPI UrlIsOpaqueW(LPCWSTR pszUrl) { @@ -1662,7 +1738,7 @@ BOOL WINAPI UrlIsOpaqueW(LPCWSTR pszUrl) * * Characters tested based on RFC 1738 */ -LPCWSTR URL_ScanID(LPCWSTR start, LPDWORD size, WINE_URL_SCAN_TYPE type) +static LPCWSTR URL_ScanID(LPCWSTR start, LPDWORD size, WINE_URL_SCAN_TYPE type) { static DWORD alwayszero = 0; BOOL cont = TRUE; @@ -1757,7 +1833,7 @@ LPCWSTR URL_ScanID(LPCWSTR start, LPDWORD size, WINE_URL_SCAN_TYPE type) /************************************************************************* * Attempt to parse URL into pieces. */ -LONG URL_ParseUrl(LPCWSTR pszUrl, WINE_PARSE_URL *pl) +static LONG URL_ParseUrl(LPCWSTR pszUrl, WINE_PARSE_URL *pl) { LPCWSTR work; @@ -1968,6 +2044,8 @@ BOOL WINAPI PathIsURLA(LPCSTR lpstrPath) /************************************************************************* * PathIsURLW [SHLWAPI.@] + * + * See PathIsURLA. */ BOOL WINAPI PathIsURLW(LPCWSTR lpstrPath) { @@ -1984,6 +2062,18 @@ BOOL WINAPI PathIsURLW(LPCWSTR lpstrPath) /************************************************************************* * UrlCreateFromPathA [SHLWAPI.@] + * + * Create a Url from a file path. + * + * PARAMS + * pszPath [I] Path to convert + * pszUrl [O] Destination for the converted Url + * pcchUrl [I/O] Length of pszUrl + * dwReserved [I] Reserved, must be 0 + * + * RETURNS + * Success: S_OK. pszUrl contains the converted path. + * Failure: An HRESULT error code. */ HRESULT WINAPI UrlCreateFromPathA(LPCSTR pszPath, LPSTR pszUrl, LPDWORD pcchUrl, DWORD dwReserved) { @@ -2088,7 +2178,9 @@ HRESULT WINAPI UrlCreateFromPathA(LPCSTR pszPath, LPSTR pszUrl, LPDWORD pcchUrl, } /************************************************************************* - * UrlCreateFromPathA [SHLWAPI.@] + * UrlCreateFromPathW [SHLWAPI.@] + * + * See UrlCreateFromPathA. */ HRESULT WINAPI UrlCreateFromPathW(LPCWSTR pszPath, LPWSTR pszUrl, LPDWORD pcchUrl, DWORD dwReserved) { diff --git a/dlls/shlwapi/wsprintf.c b/dlls/shlwapi/wsprintf.c index b99e4955da4..0c9d05b337a 100644 --- a/dlls/shlwapi/wsprintf.c +++ b/dlls/shlwapi/wsprintf.c @@ -271,6 +271,17 @@ static UINT WPRINTF_GetLen( WPRINTF_FORMAT *format, WPRINTF_DATA *arg, /*********************************************************************** * wvnsprintfA (SHLWAPI.@) + * + * Print formatted output to a string, up to a maximum number of chars. + * + * PARAMS + * lpOut [O] Destination for output string + * cchLimitIn [I] Maximum number of characters to write + * lpFmt [I] Format string + * + * RETURNS + * Success: The number of characters written. + * Failure: -1. */ INT WINAPI wvnsprintfA( LPSTR buffer, UINT maxlen, LPCSTR spec, va_list args ) { @@ -374,6 +385,8 @@ INT WINAPI wvnsprintfA( LPSTR buffer, UINT maxlen, LPCSTR spec, va_list args ) /*********************************************************************** * wvnsprintfW (SHLWAPI.@) + * + * See wvnsprintfA. */ INT WINAPI wvnsprintfW( LPWSTR buffer, UINT maxlen, LPCWSTR spec, va_list args ) { @@ -476,6 +489,17 @@ INT WINAPI wvnsprintfW( LPWSTR buffer, UINT maxlen, LPCWSTR spec, va_list args ) /************************************************************************* * wnsprintfA (SHLWAPI.@) + * + * Print formatted output to a string, up to a maximum number of chars. + * + * PARAMS + * lpOut [O] Destination for output string + * cchLimitIn [I] Maximum number of characters to write + * lpFmt [I] Format string + * + * RETURNS + * Success: The number of characters written. + * Failure: -1. */ int WINAPIV wnsprintfA(LPSTR lpOut, int cchLimitIn, LPCSTR lpFmt, ...) { @@ -491,6 +515,8 @@ int WINAPIV wnsprintfA(LPSTR lpOut, int cchLimitIn, LPCSTR lpFmt, ...) /************************************************************************* * wnsprintfW (SHLWAPI.@) + * + * See wnsprintfA. */ int WINAPIV wnsprintfW(LPWSTR lpOut, int cchLimitIn, LPCWSTR lpFmt, ...) { diff --git a/dlls/urlmon/umon.c b/dlls/urlmon/umon.c index ec90386a6b5..5e76e6ef80a 100644 --- a/dlls/urlmon/umon.c +++ b/dlls/urlmon/umon.c @@ -1,13 +1,9 @@ /* * UrlMon * - * Copyright 1999 Corel Corporation - * - * Ulrich Czekalla - * + * Copyright 1999 Ulrich Czekalla for Corel Corporation * Copyright 2002 Huw D M Davies for CodeWeavers * - * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either @@ -806,8 +802,10 @@ static HRESULT WINAPI URLMonikerImpl_IBinding_Suspend(IBinding* iface) /*********************************************************************** * CreateAsyncBindCtxEx (URLMON.@) * - * not implemented + * Create an asynchronous bind context. * + * FIXME + * Not implemented. */ HRESULT WINAPI CreateAsyncBindCtxEx(IBindCtx *ibind, DWORD options, IBindStatusCallback *callback, IEnumFORMATETC *format, IBindCtx** pbind, @@ -821,13 +819,17 @@ HRESULT WINAPI CreateAsyncBindCtxEx(IBindCtx *ibind, DWORD options, /*********************************************************************** * CreateURLMoniker (URLMON.@) * - * Create a url moniker + * Create a url moniker. + * + * PARAMS + * pmkContext [I] Context + * szURL [I] Url to create the moniker for + * ppmk [O] Destination for created moniker. * * RETURNS - * S_OK success - * E_OUTOFMEMORY out of memory - * MK_E_SYNTAX not a valid url - * + * Success: S_OK. ppmk contains the created IMoniker object. + * Failure: MK_E_SYNTAX if szURL is not a valid url, or + * E_OUTOFMEMORY if memory allocation fails. */ HRESULT WINAPI CreateURLMoniker(IMoniker *pmkContext, LPCWSTR szURL, IMoniker **ppmk) { @@ -855,13 +857,18 @@ HRESULT WINAPI CreateURLMoniker(IMoniker *pmkContext, LPCWSTR szURL, IMoniker ** /*********************************************************************** * CoInternetGetSession (URLMON.@) * - * Creates a session and returns a pointer to an InternetSession interface. + * Create a new internet session and return an IInternetSession interface + * representing it. + * + * PARAMS + * dwSessionMode [I] Mode for the internet session + * ppIInternetSession [O] Destination for creates IInternetSession object + * dwReserved [I] Reserved, must be 0. * * RETURNS - * S_OK success - * E_OUTOFMEMORY out of memory - * E_INVALIDARG invalid argument - * + * Success: S_OK. ppIInternetSession contains the IInternetSession interface. + * Failure: E_INVALIDARG, if any argument is invalid, or + * E_OUTOFMEMORY if memory allocation fails. */ HRESULT WINAPI CoInternetGetSession(DWORD dwSessionMode, /*IInternetSession*/void **ppIInternetSession, DWORD dwReserved) { @@ -916,13 +923,18 @@ HRESULT WINAPI FindMimeFromData(LPBC pBC, LPCWSTR pwzUrl, LPVOID pBuffer, /*********************************************************************** * RegisterBindStatusCallback (URLMON.@) * - * Register a bind status callback + * Register a bind status callback. + * + * PARAMS + * pbc [I] Binding context + * pbsc [I] Callback to register + * ppbscPrevious [O] Destination for previous callback + * dwReserved [I] Reserved, must be 0. * * RETURNS - * S_OK success - * E_INVALIDARG invalid argument(s) - * E_OUTOFMEMORY out of memory - * + * Success: S_OK. + * Failure: E_INVALIDARG, if any argument is invalid, or + * E_OUTOFMEMORY if memory allocation fails. */ HRESULT WINAPI RegisterBindStatusCallback( IBindCtx *pbc, @@ -952,13 +964,15 @@ HRESULT WINAPI RegisterBindStatusCallback( /*********************************************************************** * RevokeBindStatusCallback (URLMON.@) * - * Unregister a bind status callback + * Unregister a bind status callback. + * + * pbc [I] Binding context + * pbsc [I] Callback to unregister * * RETURNS - * S_OK success - * E_INVALIDARG invalid argument(s) - * E_FAIL pbsc wasn't registered with pbc - * + * Success: S_OK. + * Failure: E_INVALIDARG, if any argument is invalid, or + * E_FAIL if pbsc wasn't registered with pbc. */ HRESULT WINAPI RevokeBindStatusCallback( IBindCtx *pbc, @@ -988,10 +1002,15 @@ HRESULT WINAPI RevokeBindStatusCallback( /*********************************************************************** * ReleaseBindInfo (URLMON.@) * - * Releases the resources used by the specified BINDINFO structure + * Release the resources used by the specified BINDINFO structure. * + * PARAMS + * pbindinfo [I] BINDINFO to release. + * + * RETURNS + * Nothing. */ void WINAPI ReleaseBindInfo(BINDINFO* pbindinfo) { - FIXME("stub\n"); + FIXME("(%p)stub!\n", pbindinfo); } diff --git a/dlls/wsock32/service.c b/dlls/wsock32/service.c index 5cc30105efe..496d560c98c 100644 --- a/dlls/wsock32/service.c +++ b/dlls/wsock32/service.c @@ -33,15 +33,15 @@ WINE_DEFAULT_DEBUG_CHANNEL(winsock); /****************************************************************************** * GetTypeByNameA [WSOCK32.1113] * - * Retrieves a service type GUID for a network service specified by name + * Retrieve a service type GUID for a network service specified by name. * * PARAMETERS - * lpServiceName -- Pointer to a zero-terminated ASCII string that uniquely represents the name of the service - * lpServiceType -- Pointer to a variable to receive a GUID that specifies the type of network service + * lpServiceName [I] NUL-terminated ASCII string that uniquely represents the name of the service + * lpServiceType [O] Destination for the service type GUID * * RETURNS - * Zero on success, SOCKET_ERROR on failure. - * GetLastError can return ERROR_SERVICE_DOES_NOT_EXIST + * Success: 0. lpServiceType contains the requested GUID + * Failure: SOCKET_ERROR. GetLastError() can return ERROR_SERVICE_DOES_NOT_EXIST * * NOTES * Obsolete Microsoft-specific extension to Winsock 1.1. @@ -64,22 +64,7 @@ INT WINAPI GetTypeByNameA(LPSTR lpServiceName, LPGUID lpServiceType) /****************************************************************************** * GetTypeByNameW [WSOCK32.1114] * - * Retrieves a service type GUID for a network service specified by name - * - * PARAMETERS - * lpServiceName -- Pointer to a zero-terminated Unicode string that uniquely represents the name of the service - * lpServiceType -- Pointer to a variable to receive a GUID that specifies the type of network service - * - * RETURNS - * Zero on success, SOCKET_ERROR on failure. - * GetLastError can return ERROR_SERVICE_DOES_NOT_EXIST - * - * NOTES - * Obsolete Microsoft-specific extension to Winsock 1.1. - * Protocol-independent name resolution provides equivalent functionality in Winsock 2. - * - * BUGS - * Unimplemented + * See GetTypeByNameA. */ INT WINAPI GetTypeByNameW(LPWSTR lpServiceName, LPGUID lpServiceType) { @@ -94,22 +79,22 @@ INT WINAPI GetTypeByNameW(LPWSTR lpServiceName, LPGUID lpServiceType) /****************************************************************************** * SetServiceA [WSOCK32.1117] * - * Registers or unregisters a network service with one or more name spaces + * Register or unregister a network service with one or more namespaces. * * PARAMETERS - * dwNameSpace -- Name space or set of name spaces within which the function will operate - * dwOperation -- Specifies the operation that the function will perform - * dwFlags -- Set of bit flags that modify the function's operation - * lpServiceInfo -- Pointer to a ASCII SERVICE_INFO structure - * lpServiceAsyncInfo -- Reserved for future use. Must be NULL. - * lpdwStatusFlags -- Set of bit flags that receive function status information + * dwNameSpace [I] Name space or set of name spaces within which the function will operate + * dwOperation [I] Operation to perform + * dwFlags [I] Flags to modify the function's operation + * lpServiceInfo [I] Pointer to a ASCII SERVICE_INFO structure + * lpServiceAsyncInfo [I] Reserved for future use. Must be NULL. + * lpdwStatusFlags [O] Destination for function status information * * RETURNS - * SOCKET_ERROR on failure. - * GetLastError can return ERROR_ALREADY_REGISTERED + * Success: 0. + * Failure: SOCKET_ERROR. GetLastError() can return ERROR_ALREADY_REGISTERED * * NOTES - * Obsolete Microsoft-specific extension to Winsock 1.1 + * Obsolete Microsoft-specific extension to Winsock 1.1, * Protocol-independent name resolution provides equivalent functionality in Winsock 2. * * BUGS @@ -130,26 +115,7 @@ INT WINAPI SetServiceA(DWORD dwNameSpace, DWORD dwOperation, DWORD dwFlags, LPSE /****************************************************************************** * SetServiceW [WSOCK32.1118] * - * Registers or unregisters a network service with one or more name spaces - * - * PARAMETERS - * dwNameSpace -- Name space or set of name spaces within which the function will operate - * dwOperation -- Specifies the operation that the function will perform - * dwFlags -- Set of bit flags that modify the function's operation - * lpServiceInfo -- Pointer to a Unicode SERVICE_INFO structure - * lpServiceAsyncInfo -- Reserved for future use. Must be NULL. - * lpdwStatusFlags -- Set of bit flags that receive function status information - * - * RETURNS - * SOCKET_ERROR on failure. - * GetLastError can return ERROR_ALREADY_REGISTERED - * - * NOTES - * Obsolete Microsoft-specific extension to Winsock 1.1 - * Protocol-independent name resolution provides equivalent functionality in Winsock 2. - * - * BUGS - * Unimplemented. + * See SetServiceA. */ INT WINAPI SetServiceW(DWORD dwNameSpace, DWORD dwOperation, DWORD dwFlags, LPSERVICE_INFOW lpServiceInfo, LPSERVICE_ASYNC_INFO lpServiceAsyncInfo, LPDWORD lpdwStatusFlags) diff --git a/ole/ole2nls.c b/ole/ole2nls.c index f921f07db33..d5aff910904 100644 --- a/ole/ole2nls.c +++ b/ole/ole2nls.c @@ -583,36 +583,30 @@ static int identity(int c) * * Convert a string, or generate a sort key from it. * - * If (mapflags & LCMAP_SORTKEY), the function will generate - * a sort key for the source string. Else, it will convert it - * accordingly to the flags LCMAP_UPPERCASE, LCMAP_LOWERCASE,... - * * RETURNS - * Error : 0. - * Success : length of the result string. + * Success: The length of the string written to dststr. + * Failure: 0. * * NOTES - * If called with scrlen = -1, the function will compute the length - * of the 0-terminated string strsrc by itself. - * - * If called with dstlen = 0, returns the buffer length that - * would be required. - * - * NORM_IGNOREWIDTH means to compare ASCII and wide characters + * -If mapflags includes LCMAP_SORTKEY, the function will generate a + * sort key for srcstr. Otherwise, srcstr is converted according to + * mapflags. + * -If scrlen is -1, the function will compute the length of strsrc + * (which must be NUL terminated) itself. + * -If dstlen is 0, The return value is the buffer length that is needed. + * -NORM_IGNOREWIDTH means to compare ASCII and wide characters * as if they are equal. * In the only code page implemented so far, there may not be - * wide characters in strings passed to LCMapStringA, + * wide characters in strings passed to this function, * so there is nothing to be done for this flag. */ INT WINAPI LCMapStringA( - LCID lcid, /* [in] locale identifier created with MAKELCID; - LOCALE_SYSTEM_DEFAULT and LOCALE_USER_DEFAULT are - predefined values. */ - DWORD mapflags, /* [in] flags */ - LPCSTR srcstr, /* [in] source buffer */ - INT srclen, /* [in] source length */ - LPSTR dststr, /* [out] destination buffer */ - INT dstlen) /* [in] destination buffer length */ + LCID lcid, /* [in] Locale Id */ + DWORD mapflags, /* [in] Flags */ + LPCSTR srcstr, /* [in] Source buffer */ + INT srclen, /* [in] Length of srcstr */ + LPSTR dststr, /* [out] Destination buffer */ + INT dstlen) /* [in] Length of dststr */ { int i; @@ -844,11 +838,7 @@ INT WINAPI LCMapStringA( /************************************************************************* * LCMapStringW [KERNEL32.@] * - * Convert a string, or generate a sort key from it. - * - * NOTE - * - * See LCMapStringA for documentation + * See LCMapStringA. */ INT WINAPI LCMapStringW( LCID lcid,DWORD mapflags,LPCWSTR srcstr,INT srclen,LPWSTR dststr, diff --git a/windows/dce.c b/windows/dce.c index 2db3ea47795..eda3f793a3a 100644 --- a/windows/dce.c +++ b/windows/dce.c @@ -523,12 +523,15 @@ END: /*********************************************************************** * GetDC (USER32.@) + * + * Get a device context. + * * RETURNS - * :Handle to DC - * NULL: Failure + * Success: Handle to the device context + * Failure: NULL. */ HDC WINAPI GetDC( - HWND hwnd /* [in] handle of window */ + HWND hwnd /* [in] handle of window - may be NULL */ ) { if (!hwnd) return GetDCEx( 0, 0, DCX_CACHE | DCX_WINDOW ); @@ -548,12 +551,14 @@ HDC WINAPI GetWindowDC( HWND hwnd ) /*********************************************************************** * ReleaseDC (USER32.@) * + * Release a device context. + * * RETURNS - * 1: Success - * 0: Failure + * Success: Non-zero. Resources used by hdc are released. + * Failure: 0. */ INT WINAPI ReleaseDC( - HWND hwnd /* [in] Handle of window - ignored */, + HWND hwnd, /* [in] Handle of window - ignored */ HDC hdc /* [in] Handle of device context */ ) { DCE * dce;