Documentation fixes.
diff --git a/dlls/advapi32/registry.c b/dlls/advapi32/registry.c index 9af8dbb..6965aeb 100644 --- a/dlls/advapi32/registry.c +++ b/dlls/advapi32/registry.c
@@ -145,21 +145,7 @@ /****************************************************************************** * RegCreateKeyExW [ADVAPI32.@] * - * PARAMS - * hkey [I] Handle of an open key - * name [I] Address of subkey name - * reserved [I] Reserved - must be 0 - * class [I] Address of class string - * options [I] Special options flag - * access [I] Desired security access - * sa [I] Address of key security structure - * retkey [O] Address of buffer for opened handle - * dispos [O] Receives REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY - * - * NOTES - * in case of failing retkey remains untouched - * - * FIXME MAXIMUM_ALLOWED in access mask not supported by server + * See RegCreateKeyExA. */ DWORD WINAPI RegCreateKeyExW( HKEY hkey, LPCWSTR name, DWORD reserved, LPCWSTR class, DWORD options, REGSAM access, SECURITY_ATTRIBUTES *sa, @@ -189,7 +175,25 @@ /****************************************************************************** * RegCreateKeyExA [ADVAPI32.@] * - * FIXME MAXIMUM_ALLOWED in access mask not supported by server + * Open a registry key, creating it if it doesn't exist. + * + * PARAMS + * hkey [I] Handle of the parent registry key + * name [I] Name of the new key to open or create + * reserved [I] Reserved, pass 0 + * class [I] The object type of the new key + * options [I] Flags controlling the key creation (REG_OPTION_* flags from "winnt.h") + * access [I] Access level desired + * sa [I] Security attributes for the key + * retkey [O] Destination for the resulting handle + * dispos [O] Receives REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY + * + * RETURNS + * Success: ERROR_SUCCESS. + * Failure: A standard Win32 error code. retkey remains untouched. + * + * FIXME + * MAXIMUM_ALLOWED in access mask not supported by server */ DWORD WINAPI RegCreateKeyExA( HKEY hkey, LPCSTR name, DWORD reserved, LPCSTR class, DWORD options, REGSAM access, SECURITY_ATTRIBUTES *sa, @@ -253,23 +257,7 @@ /****************************************************************************** * RegOpenKeyExW [ADVAPI32.@] * - * Opens the specified key - * - * Unlike RegCreateKeyEx, this does not create the key if it does not exist. - * - * PARAMS - * hkey [I] Handle of open key - * name [I] Name of subkey to open - * reserved [I] Reserved - must be zero - * access [I] Security access mask - * retkey [O] Handle to open key - * - * RETURNS - * Success: ERROR_SUCCESS - * Failure: Error code - * - * NOTES - * in case of failing is retkey = 0 + * See RegOpenKeyExA. */ DWORD WINAPI RegOpenKeyExW( HKEY hkey, LPCWSTR name, DWORD reserved, REGSAM access, PHKEY retkey ) { @@ -291,6 +279,23 @@ /****************************************************************************** * RegOpenKeyExA [ADVAPI32.@] + * + * Open a registry key. + * + * PARAMS + * hkey [I] Handle of open key + * name [I] Name of subkey to open + * reserved [I] Reserved - must be zero + * access [I] Security access mask + * retkey [O] Handle to open key + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: A standard Win32 error code. retkey is set to 0. + * + * NOTES + * - Unlike RegCreateKeyExA(), this function will not create the key if it + * does not exist. */ DWORD WINAPI RegOpenKeyExA( HKEY hkey, LPCSTR name, DWORD reserved, REGSAM access, PHKEY retkey ) { @@ -322,17 +327,7 @@ /****************************************************************************** * RegOpenKeyW [ADVAPI32.@] * - * PARAMS - * hkey [I] Handle of open key - * name [I] Address of name of subkey to open - * retkey [O] Handle to open key - * - * RETURNS - * Success: ERROR_SUCCESS - * Failure: Error code - * - * NOTES - * in case of failing is retkey = 0 + * See RegOpenKeyA. */ DWORD WINAPI RegOpenKeyW( HKEY hkey, LPCWSTR name, PHKEY retkey ) { @@ -342,6 +337,17 @@ /****************************************************************************** * RegOpenKeyA [ADVAPI32.@] + * + * Open a registry key. + * + * PARAMS + * hkey [I] Handle of parent key to open the new key under + * name [I] Name of the key under hkey to open + * retkey [O] Destination for the resulting Handle + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: A standard Win32 error code. retkey is set to 0. */ DWORD WINAPI RegOpenKeyA( HKEY hkey, LPCSTR name, PHKEY retkey ) { @@ -755,7 +761,7 @@ /****************************************************************************** * RegCloseKey [ADVAPI32.@] * - * Releases the handle of the specified key + * Close an open registry key. * * PARAMS * hkey [I] Handle of key to close @@ -774,13 +780,7 @@ /****************************************************************************** * RegDeleteKeyW [ADVAPI32.@] * - * PARAMS - * hkey [I] Handle to open key - * name [I] Name of subkey to delete - * - * RETURNS - * Success: ERROR_SUCCESS - * Failure: Error code + * See RegDeleteKeyA. */ DWORD WINAPI RegDeleteKeyW( HKEY hkey, LPCWSTR name ) { @@ -815,6 +815,16 @@ /****************************************************************************** * RegDeleteKeyA [ADVAPI32.@] + * + * Delete a registry key. + * + * PARAMS + * hkey [I] Handle to parent key containing the key to delete + * name [I] Name of the key user hkey to delete + * + * RETURNS + * Success: ERROR_SUCCESS + * Failure: Error code */ DWORD WINAPI RegDeleteKeyA( HKEY hkey, LPCSTR name ) { @@ -851,15 +861,15 @@ /****************************************************************************** * RegSetValueExW [ADVAPI32.@] * - * Sets the data and type of a value under a register key + * Set the data and contents of a registry value. * * PARAMS * hkey [I] Handle of key to set value for * name [I] Name of value to set - * reserved [I] Reserved - must be zero - * type [I] Flag for value type - * data [I] Address of value data - * count [I] Size of value data + * reserved [I] Reserved, must be zero + * type [I] Type of the value being set + * data [I] The new contents of the value to set + * count [I] Size of data * * RETURNS * Success: ERROR_SUCCESS @@ -985,22 +995,7 @@ /****************************************************************************** * RegQueryValueExW [ADVAPI32.@] * - * Retrieves type and data for a specified name associated with an open key - * - * PARAMS - * hkey [I] Handle of key to query - * name [I] Name of value to query - * reserved [I] Reserved - must be NULL - * type [O] Address of buffer for value type. If NULL, the type - * is not required. - * data [O] Address of data buffer. If NULL, the actual data is - * not required. - * count [I/O] Address of data buffer size - * - * RETURNS - * ERROR_SUCCESS: Success - * ERROR_MORE_DATA: !!! if the specified buffer is not big enough to hold the data - * buffer is left untouched. The MS-documentation is wrong (js) !!! + * See RegQueryValueExA. */ DWORD WINAPI RegQueryValueExW( HKEY hkey, LPCWSTR name, LPDWORD reserved, LPDWORD type, LPBYTE data, LPDWORD count ) @@ -1068,8 +1063,25 @@ /****************************************************************************** * RegQueryValueExA [ADVAPI32.@] * - * NOTES: - * the documentation is wrong: if the buffer is too small it remains untouched + * Get the type and contents of a specified value under with a key. + * + * PARAMS + * hkey [I] Handle of the key to query + * name [I] Name of value under hkey to query + * reserved [I] Reserved - must be NULL + * type [O] Destination for the value type, or NULL if not required + * data [O] Destination for the values contents, or NULL if not required + * count [I/O] Size of data, updated with the number of bytes returned + * + * RETURNS + * Success: ERROR_SUCCESS. *count is updated with the number of bytes copied to data. + * Failure: ERROR_INVALID_HANDLE, if hkey is invalid. + * ERROR_INVALID_PARAMETER, if any other parameter is invalid. + * ERROR_MORE_DATA, if on input *count is too small to hold the contents. + * + * NOTES + * MSDN states that if data is too small it is partially filled. In reality + * it remains untouched. */ DWORD WINAPI RegQueryValueExA( HKEY hkey, LPCSTR name, LPDWORD reserved, LPDWORD type, LPBYTE data, LPDWORD count ) @@ -1781,7 +1793,8 @@ /****************************************************************************** * RegGetKeySecurity [ADVAPI32.@] - * Retrieves a copy of security descriptor protecting the registry key + * + * Get a copy of the security descriptor for a given registry key. * * PARAMS * hkey [I] Open handle of key to set @@ -1817,17 +1830,15 @@ /****************************************************************************** * RegFlushKey [ADVAPI32.@] - * Immediately writes key to registry. - * Only returns after data has been written to disk. - * - * FIXME: does it really wait until data is written ? + * + * Immediately write a registry key to registry. * * PARAMS - * hkey [I] Handle of key to write + * hkey [I] Handle of key to write * * RETURNS - * Success: ERROR_SUCCESS - * Failure: Error code + * Success: ERROR_SUCCESS + * Failure: Error code */ DWORD WINAPI RegFlushKey( HKEY hkey ) { @@ -1940,18 +1951,19 @@ /****************************************************************************** * RegOpenUserClassesRoot [ADVAPI32.@] - * Opens the HKEY_CLASSES_ROOT key for the user represented by the token + * + * Open the HKEY_CLASSES_ROOT key for a user. * * PARAMS - * hToken [I] Handle of token representing user - * dwOptions [I] Reserved + * hToken [I] Handle of token representing the user + * dwOptions [I] Reserved, nust be 0 * samDesired [I] Desired access rights - * phkResult [O] Address of buffer for opened handle + * phkResult [O] Destination for the resulting key handle * - * NOTES: + * NOTES * On Windows 2000 and upwards the HKEY_CLASSES_ROOT key is a view of the - * HKEY_LOCAL_MACHINE\Software\Classes and the - * HKEY_CURRENT_USER\Software\Classes keys merged together. + * "HKEY_LOCAL_MACHINE\Software\Classes" and the + * "HKEY_CURRENT_USER\Software\Classes" keys merged together. */ LONG WINAPI RegOpenUserClassesRoot( HANDLE hToken,
diff --git a/dlls/advapi32/security.c b/dlls/advapi32/security.c index 1804788..880016a 100644 --- a/dlls/advapi32/security.c +++ b/dlls/advapi32/security.c
@@ -903,10 +903,10 @@ * PARAMS * lpSystemName [I] Name of the system * lpName [I] Name of the privilege - * pLuid [O] Destination for the resulting LUID + * lpLuid [O] Destination for the resulting LUID * * RETURNS - * Success: TRUE. pLuid contains the requested LUID. + * Success: TRUE. lpLuid contains the requested LUID. * Failure: FALSE. */ BOOL WINAPI
diff --git a/dlls/advapi32/service.c b/dlls/advapi32/service.c index be68678..82701e4 100644 --- a/dlls/advapi32/service.c +++ b/dlls/advapi32/service.c
@@ -240,10 +240,20 @@ /****************************************************************************** * OpenSCManagerA [ADVAPI32.@] + * + * Establish a connection to the service control manager and open its database. + * + * PARAMS + * lpMachineName [I] Pointer to machine name string + * lpDatabaseName [I] Pointer to database name string + * dwDesiredAccess [I] Type of access + * + * RETURNS + * Success: A Handle to the service control manager database + * Failure: NULL */ -SC_HANDLE WINAPI -OpenSCManagerA( LPCSTR lpMachineName, LPCSTR lpDatabaseName, - DWORD dwDesiredAccess ) +SC_HANDLE WINAPI OpenSCManagerA( LPCSTR lpMachineName, LPCSTR lpDatabaseName, + DWORD dwDesiredAccess ) { UNICODE_STRING lpMachineNameW; UNICODE_STRING lpDatabaseNameW; @@ -259,23 +269,11 @@ /****************************************************************************** * OpenSCManagerW [ADVAPI32.@] - * Establishes a connection to the service control manager and opens database * - * NOTES - * This should return a SC_HANDLE - * - * PARAMS - * lpMachineName [I] Pointer to machine name string - * lpDatabaseName [I] Pointer to database name string - * dwDesiredAccess [I] Type of access - * - * RETURNS - * Success: Handle to service control manager database - * Failure: NULL + * See OpenSCManagerA. */ -SC_HANDLE WINAPI -OpenSCManagerW( LPCWSTR lpMachineName, LPCWSTR lpDatabaseName, - DWORD dwDesiredAccess ) +SC_HANDLE WINAPI OpenSCManagerW( LPCWSTR lpMachineName, LPCWSTR lpDatabaseName, + DWORD dwDesiredAccess ) { HKEY hReg, hKey = NULL; LONG r; @@ -319,18 +317,20 @@ /****************************************************************************** * ControlService [ADVAPI32.@] - * Sends a control code to a Win32-based service. + * + * Send a control code to a service. * * PARAMS - * hService [] - * dwControl [] - * lpServiceStatus [] + * hService [I] Handle of the service control manager database + * dwControl [I] Control code to send (SERVICE_CONTROL_* flags from "winsvc.h") + * lpServiceStatus [O] Destination for the status of the service, if available * - * RETURNS STD + * RETURNS + * Success: TRUE. + * Failure: FALSE. */ -BOOL WINAPI -ControlService( SC_HANDLE hService, DWORD dwControl, - LPSERVICE_STATUS lpServiceStatus ) +BOOL WINAPI ControlService( SC_HANDLE hService, DWORD dwControl, + LPSERVICE_STATUS lpServiceStatus ) { FIXME("(%p,%ld,%p): stub\n",hService,dwControl,lpServiceStatus); return TRUE; @@ -339,12 +339,15 @@ /****************************************************************************** * CloseServiceHandle [ADVAPI32.@] - * Close handle to service or service control manager + * + * Close a handle to a service or the service control manager database. * * PARAMS * hSCObject [I] Handle to service or service control manager database * - * RETURNS STD + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CloseServiceHandle( SC_HANDLE hSCObject ) @@ -359,10 +362,20 @@ /****************************************************************************** * OpenServiceA [ADVAPI32.@] + * + * Open a handle to a service. + * + * PARAMS + * hSCManager [I] Handle of the service control manager database + * lpServiceName [I] Name of the service to open + * dwDesiredAccess [I] Access required to the service + * + * RETURNS + * Success: Handle to the service + * Failure: NULL */ -SC_HANDLE WINAPI -OpenServiceA( SC_HANDLE hSCManager, LPCSTR lpServiceName, - DWORD dwDesiredAccess ) +SC_HANDLE WINAPI OpenServiceA( SC_HANDLE hSCManager, LPCSTR lpServiceName, + DWORD dwDesiredAccess ) { UNICODE_STRING lpServiceNameW; SC_HANDLE ret; @@ -379,20 +392,11 @@ /****************************************************************************** * OpenServiceW [ADVAPI32.@] - * Opens a handle to an existing service * - * PARAMS - * hSCManager [] - * lpServiceName [] - * dwDesiredAccess [] - * - * RETURNS - * Success: Handle to the service - * Failure: NULL + * See OpenServiceA. */ -SC_HANDLE WINAPI -OpenServiceW(SC_HANDLE hSCManager, LPCWSTR lpServiceName, - DWORD dwDesiredAccess) +SC_HANDLE WINAPI OpenServiceW( SC_HANDLE hSCManager, LPCWSTR lpServiceName, + DWORD dwDesiredAccess) { HKEY hKey; long r; @@ -593,14 +597,16 @@ /****************************************************************************** * DeleteService [ADVAPI32.@] * + * Delete a service from the service control manager database. + * * PARAMS - * hService [I] Handle to service + * hService [I] Handle of the service to delete * - * RETURNS STD - * + * RETURNS + * Success: TRUE + * Failure: FALSE */ -BOOL WINAPI -DeleteService( SC_HANDLE hService ) +BOOL WINAPI DeleteService( SC_HANDLE hService ) { WCHAR valname[MAX_PATH+1]; INT index = 0; @@ -667,6 +673,25 @@ /****************************************************************************** * StartServiceA [ADVAPI32.@] * + * Start a service + * + * PARAMS + * hService [I] Handle of service + * dwNumServiceArgs [I] Number of arguments + * lpServiceArgVectors [I] Address of array of argument strings + * + * NOTES + * - NT implements this function using an obscure RPC call. + * - You might need to do a "setenv SystemRoot \\WINNT" in your .cshrc + * to get things like "%SystemRoot%\\System32\\service.exe" to load. + * - This will only work for shared address space. How should the service + * args be transferred when address spaces are separated? + * - Can only start one service at a time. + * - Has no concept of privilege. + * + * RETURNS + * Success: TRUE. + * Failure: FALSE */ BOOL WINAPI StartServiceA( SC_HANDLE hService, DWORD dwNumServiceArgs, @@ -705,29 +730,8 @@ /****************************************************************************** * StartServiceW [ADVAPI32.@] - * Starts a service - * - * PARAMS - * hService [I] Handle of service - * dwNumServiceArgs [I] Number of arguments - * lpServiceArgVectors [I] Address of array of argument string pointers - * - * NOTES - * - * NT implements this function using an obscure RPC call... - * - * Might need to do a "setenv SystemRoot \\WINNT" in your .cshrc - * to get things like %SystemRoot%\\System32\\service.exe to load. - * - * Will only work for shared address space. How should the service - * args be transferred when address spaces are separated? - * - * Can only start one service at a time. - * - * Has no concept of privilege. - * - * RETURNS STD - * + * + * See StartServiceA. */ BOOL WINAPI StartServiceW( SC_HANDLE hService, DWORD dwNumServiceArgs, @@ -857,13 +861,19 @@ /****************************************************************************** * QueryServiceStatusEx [ADVAPI32.@] * + * Get information about a service. + * * PARAMS - * hService [handle to service] - * InfoLevel [information level] - * lpBuffer [buffer] - * cbBufSize [size of buffer] - * pcbBytesNeeded [bytes needed] -*/ + * hService [I] Handle to service to get information about + * InfoLevel [I] Level of information to get + * lpBuffer [O] Destination for requested information + * cbBufSize [I] Size of lpBuffer in bytes + * pcbBytesNeeded [O] Destination for number of bytes needed, if cbBufSize is too small + * + * RETURNS + * Success: TRUE + * FAILURE: FALSE + */ BOOL WINAPI QueryServiceStatusEx(SC_HANDLE hService, SC_STATUS_TYPE InfoLevel, LPBYTE lpBuffer, DWORD cbBufSize, LPDWORD pcbBytesNeeded)