From ec350525e3cb8cc4f3cc83dd8c7d67ba2bdb2336 Mon Sep 17 00:00:00 2001 From: Markus Amsler Date: Sat, 12 Nov 2005 19:12:03 +0000 Subject: [PATCH] Improve c2man Documented-Total count. Changes: - add missing description - add missing returns section --- dlls/advapi32/crypt.c | 4 ++++ dlls/advapi32/crypt_sha.c | 21 ++++++++++++++++++++ dlls/advapi32/eventlog.c | 23 ++++++++++++++++++++++ dlls/advapi32/registry.c | 41 ++++++++++++++++++++++++++++++++++----- dlls/advapi32/security.c | 6 ++++++ 5 files changed, 90 insertions(+), 5 deletions(-) diff --git a/dlls/advapi32/crypt.c b/dlls/advapi32/crypt.c index cdb1516def3..36ebcd11310 100644 --- a/dlls/advapi32/crypt.c +++ b/dlls/advapi32/crypt.c @@ -1533,6 +1533,8 @@ BOOL WINAPI CryptHashData (HCRYPTHASH hHash, const BYTE *pbData, DWORD dwDataLen /****************************************************************************** * CryptHashSessionKey (ADVAPI32.@) * + * Compute the cryptographic hash of a session key object. + * * PARAMS * hHash [I] Handle to the hash object. * hKey [I] Handle to the key to be hashed. @@ -1563,6 +1565,8 @@ BOOL WINAPI CryptHashSessionKey (HCRYPTHASH hHash, HCRYPTKEY hKey, DWORD dwFlags /****************************************************************************** * CryptImportKey (ADVAPI32.@) * + * Transfer a cryptographic key from a key BLOB into a cryptographic service provider (CSP). + * * PARAMS * hProv [I] Handle of a CSP. * pbData [I] Contains the key to be imported. diff --git a/dlls/advapi32/crypt_sha.c b/dlls/advapi32/crypt_sha.c index 59043c86456..f0244c4eb30 100644 --- a/dlls/advapi32/crypt_sha.c +++ b/dlls/advapi32/crypt_sha.c @@ -101,6 +101,12 @@ void SHA1Transform(ULONG State[5], UCHAR Buffer[64]) * A_SHAInit [ADVAPI32.@] * * Initialize a SHA context structure. + * + * PARAMS + * Context [O] SHA context + * + * RETURNS + * Nothing */ VOID WINAPI A_SHAInit(PSHA_CTX Context) @@ -119,6 +125,14 @@ A_SHAInit(PSHA_CTX Context) * A_SHAUpdate [ADVAPI32.@] * * Update a SHA context with a hashed data from supplied buffer. + * + * PARAMS + * Context [O] SHA context + * Buffer [I] hashed data + * BufferSize [I] hashed data size + * + * RETURNS + * Nothing */ VOID WINAPI A_SHAUpdate(PSHA_CTX Context, PCHAR Buffer, UINT BufferSize) @@ -155,6 +169,13 @@ A_SHAUpdate(PSHA_CTX Context, PCHAR Buffer, UINT BufferSize) * A_SHAFinal [ADVAPI32.@] * * Finalize SHA context and return the resulting hash. + * + * PARAMS + * Context [I/O] SHA context + * Result [O] resulting hash + * + * RETURNS + * Nothing */ VOID WINAPI A_SHAFinal(PSHA_CTX Context, PULONG Result) diff --git a/dlls/advapi32/eventlog.c b/dlls/advapi32/eventlog.c index ae1b149260f..87ba1fe97de 100644 --- a/dlls/advapi32/eventlog.c +++ b/dlls/advapi32/eventlog.c @@ -442,6 +442,25 @@ BOOL WINAPI ReportEventW( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD dw /****************************************************************************** * RegisterTraceGuidsW [ADVAPI32.@] * + * Register an event trace provider and the event trace classes that it uses + * to generate events. + * + * PARAMS + * RequestAddress [I] ControlCallback function + * RequestContext [I] Optional provider-defined context + * ControlGuid [I] GUID of the registering provider + * GuidCount [I] Number of elements in the TraceGuidReg array + * TraceGuidReg [I/O] Array of TRACE_GUID_REGISTRATION structures + * MofImagePath [I] not supported, set to NULL + * MofResourceNmae [I] not supported, set to NULL + * RegistrationHandle [O] Provider's registration handle + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: System error code + * + * FIXME + * Stub. */ ULONG WINAPI RegisterTraceGuidsW( WMIDPREQUEST RequestAddress, PVOID RequestContext, LPCGUID ControlGuid, ULONG GuidCount, @@ -457,6 +476,10 @@ ULONG WINAPI RegisterTraceGuidsW( WMIDPREQUEST RequestAddress, /****************************************************************************** * RegisterTraceGuidsA [ADVAPI32.@] * + * See RegisterTraceGuidsW. + * + * FIXME + * Stub. */ ULONG WINAPI RegisterTraceGuidsA( WMIDPREQUEST RequestAddress, PVOID RequestContext, LPCGUID ControlGuid, ULONG GuidCount, diff --git a/dlls/advapi32/registry.c b/dlls/advapi32/registry.c index 96e25cce2e2..dcbcb027b9a 100644 --- a/dlls/advapi32/registry.c +++ b/dlls/advapi32/registry.c @@ -380,11 +380,23 @@ DWORD WINAPI RegOpenKeyA( HKEY hkey, LPCSTR name, PHKEY retkey ) /****************************************************************************** * RegOpenCurrentUser [ADVAPI32.@] - * - * FIXME: This function is supposed to retrieve a handle to the - * HKEY_CURRENT_USER for the user the current thread is impersonating. - * Since Wine does not currently allow threads to impersonate other users, - * this stub should work fine. + * + * Get a handle to the HKEY_CURRENT_USER key for the user + * the current thread is impersonating. + * + * PARAMS + * access [I] Desired access rights to the key + * retkey [O] Handle to the opened key + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: nonzero error code from Winerror.h + * + * FIXME + * This function is supposed to retrieve a handle to the + * HKEY_CURRENT_USER for the user the current thread is impersonating. + * Since Wine does not currently allow threads to impersonate other users, + * this stub should work fine. */ DWORD WINAPI RegOpenCurrentUser( REGSAM access, PHKEY retkey ) { @@ -396,6 +408,8 @@ DWORD WINAPI RegOpenCurrentUser( REGSAM access, PHKEY retkey ) /****************************************************************************** * RegEnumKeyExW [ADVAPI32.@] * + * Enumerate subkeys of the specified open registry key. + * * PARAMS * hkey [I] Handle to key to enumerate * index [I] Index of subkey to enumerate @@ -1837,6 +1851,9 @@ DWORD WINAPI RegDeleteValueA( HKEY hkey, LPCSTR name ) /****************************************************************************** * RegLoadKeyW [ADVAPI32.@] * + * Create a subkey under HKEY_USERS or HKEY_LOCAL_MACHINE and store + * registration information from a specified file into that subkey. + * * PARAMS * hkey [I] Handle of open key * subkey [I] Address of name of subkey @@ -1900,6 +1917,8 @@ LONG WINAPI RegLoadKeyA( HKEY hkey, LPCSTR subkey, LPCSTR filename ) /****************************************************************************** * RegSaveKeyW [ADVAPI32.@] * + * Save a key and all of its subkeys and values to a new file in the standard format. + * * PARAMS * hkey [I] Handle of key where save begins * lpFile [I] Address of filename to save to @@ -1981,6 +2000,8 @@ LONG WINAPI RegSaveKeyA( HKEY hkey, LPCSTR file, LPSECURITY_ATTRIBUTES sa ) /****************************************************************************** * RegRestoreKeyW [ADVAPI32.@] * + * Read the registry information from a file and copy it over a key. + * * PARAMS * hkey [I] Handle of key where restore begins * lpFile [I] Address of filename containing saved tree @@ -2026,6 +2047,8 @@ LONG WINAPI RegRestoreKeyA( HKEY hkey, LPCSTR lpFile, DWORD dwFlags ) /****************************************************************************** * RegUnLoadKeyW [ADVAPI32.@] * + * Unload a registry key and its subkeys from the registry. + * * PARAMS * hkey [I] Handle of open key * lpSubKey [I] Address of name of subkey to unload @@ -2073,6 +2096,8 @@ LONG WINAPI RegUnLoadKeyA( HKEY hkey, LPCSTR lpSubKey ) /****************************************************************************** * RegReplaceKeyW [ADVAPI32.@] * + * Replace the file backing a registry key and all its subkeys with another file. + * * PARAMS * hkey [I] Handle of open key * lpSubKey [I] Address of name of subkey @@ -2119,6 +2144,8 @@ LONG WINAPI RegReplaceKeyA( HKEY hkey, LPCSTR lpSubKey, LPCSTR lpNewFile, /****************************************************************************** * RegSetKeySecurity [ADVAPI32.@] * + * Set the security of an open registry key. + * * PARAMS * hkey [I] Open handle of key to set * SecurityInfo [I] Descriptor contents @@ -2212,6 +2239,8 @@ DWORD WINAPI RegFlushKey( HKEY hkey ) /****************************************************************************** * RegConnectRegistryW [ADVAPI32.@] * + * Establishe a connection to a predefined registry key on another computer. + * * PARAMS * lpMachineName [I] Address of name of remote computer * hHey [I] Predefined registry handle @@ -2276,6 +2305,8 @@ LONG WINAPI RegConnectRegistryA( LPCSTR machine, HKEY hkey, PHKEY reskey ) /****************************************************************************** * RegNotifyChangeKeyValue [ADVAPI32.@] * + * Notify the caller about changes to the attributes or contents of a registry key. + * * PARAMS * hkey [I] Handle of key to watch * fWatchSubTree [I] Flag for subkey notification diff --git a/dlls/advapi32/security.c b/dlls/advapi32/security.c index 6d88b02694d..a676054ab9e 100644 --- a/dlls/advapi32/security.c +++ b/dlls/advapi32/security.c @@ -274,6 +274,8 @@ CheckTokenMembership( HANDLE TokenHandle, PSID SidToCheck, /****************************************************************************** * GetTokenInformation [ADVAPI32.@] * + * Get a type of information about an access token. + * * PARAMS * token [I] Handle from OpenProcessToken() or OpenThreadToken() * tokeninfoclass [I] A TOKEN_INFORMATION_CLASS from "winnt.h" @@ -629,6 +631,10 @@ GetLengthSid (PSID pSid) * pOldSD [I] * lpdwBufferLength [I/O] * pNewSD [O] + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: nonzero error code from Winerror.h */ DWORD WINAPI BuildSecurityDescriptorA( IN PTRUSTEE_A pOwner,