From 03131aae91ac3eef9310cad9ac447396f60c0ca5 Mon Sep 17 00:00:00 2001 From: Andrew Johnston Date: Tue, 19 Dec 2000 23:33:03 +0000 Subject: [PATCH] Documentation update. --- dlls/kernel/comm.c | 317 +++++++++++++++++++++++++++++++++++------ dlls/kernel/debugger.c | 71 +++++++-- dlls/kernel/time.c | 118 +++++++++++---- 3 files changed, 426 insertions(+), 80 deletions(-) diff --git a/dlls/kernel/comm.c b/dlls/kernel/comm.c index 8f4935b2218..34a28f0397d 100644 --- a/dlls/kernel/comm.c +++ b/dlls/kernel/comm.c @@ -1489,17 +1489,37 @@ BOOL16 WINAPI EnableCommNotification16( INT16 cid, HWND16 hwnd, /************************************************************************** * BuildCommDCBA (KERNEL32.14) + * + * Updates a device control block data structure with values from an + * ascii device control string. The device control string has two forms + * normal and extended, it must be exclusively in one or the other form. + * + * RETURNS + * + * True on success, false on an malformed control string. */ -BOOL WINAPI BuildCommDCBA(LPCSTR device,LPDCB lpdcb) +BOOL WINAPI BuildCommDCBA( + LPCSTR device, /* The ascii device control string used to update the DCB. */ + LPDCB lpdcb /* The device control block to be updated. */) { return BuildCommDCBAndTimeoutsA(device,lpdcb,NULL); } /************************************************************************** * BuildCommDCBAndTimeoutsA (KERNEL32.15) + * + * Updates a device control block data structure with values from an + * ascii device control string. Taking time out values from a time outs + * struct if desired by the control string. + * + * RETURNS + * + * True on success, false bad handles etc */ -BOOL WINAPI BuildCommDCBAndTimeoutsA(LPCSTR device, LPDCB lpdcb, - LPCOMMTIMEOUTS lptimeouts) +BOOL WINAPI BuildCommDCBAndTimeoutsA( + LPCSTR device, /* The ascii device control string. */ + LPDCB lpdcb, /* The device control block to be updated. */ + LPCOMMTIMEOUTS lptimeouts /* The time outs to use if asked to set them by the control string. */) { int port; char *ptr,*temp; @@ -1621,24 +1641,47 @@ BOOL WINAPI BuildCommDCBAndTimeoutsA(LPCSTR device, LPDCB lpdcb, /************************************************************************** * BuildCommDCBAndTimeoutsW (KERNEL32.16) + * + * Updates a device control block data structure with values from an + * unicode device control string. Taking time out values from a time outs + * struct if desired by the control string. + * + * RETURNS + * + * True on success, false bad handles etc. */ -BOOL WINAPI BuildCommDCBAndTimeoutsW( LPCWSTR devid, LPDCB lpdcb, - LPCOMMTIMEOUTS lptimeouts ) +BOOL WINAPI BuildCommDCBAndTimeoutsW( + LPCWSTR devid, /* The unicode device control string. */ + LPDCB lpdcb, /* The device control block to be updated. */ + LPCOMMTIMEOUTS lptimeouts /* The time outs to use if asked to set them by the control string. */) { + BOOL ret = FALSE; LPSTR devidA; - BOOL ret; TRACE("(%p,%p,%p)\n",devid,lpdcb,lptimeouts); devidA = HEAP_strdupWtoA( GetProcessHeap(), 0, devid ); + if (devidA) + { ret=BuildCommDCBAndTimeoutsA(devidA,lpdcb,lptimeouts); HeapFree( GetProcessHeap(), 0, devidA ); + } return ret; } /************************************************************************** * BuildCommDCBW (KERNEL32.17) + * + * Updates a device control block structure with values from an + * unicode device control string. The device control string has two forms + * normal and extended, it must be exclusively in one or the other form. + * + * RETURNS + * + * True on success, false on an malformed control string. */ -BOOL WINAPI BuildCommDCBW(LPCWSTR devid,LPDCB lpdcb) +BOOL WINAPI BuildCommDCBW( + LPCWSTR devid, /* The unicode device control string. */ + LPDCB lpdcb /* The device control block to be updated. */) { return BuildCommDCBAndTimeoutsW(devid,lpdcb,NULL); } @@ -1648,8 +1691,20 @@ int commerror=0; /***************************************************************************** * SetCommBreak (KERNEL32.449) + * + * Halts the transmission of characters to a communications device. + * + * RETURNS + * + * True on success, and false if the communications device could not be found, + * the control is not supported. + * + * BUGS + * + * Only TIOCSBRK and TIOCCBRK are supported. */ -BOOL WINAPI SetCommBreak(HANDLE handle) +BOOL WINAPI SetCommBreak( + HANDLE handle /* The communictions device to suspend. */) { #if defined(TIOCSBRK) && defined(TIOCCBRK) /* check if available for compilation */ int fd,result; @@ -1677,8 +1732,19 @@ BOOL WINAPI SetCommBreak(HANDLE handle) /***************************************************************************** * ClearCommBreak (KERNEL32.20) + * + * Resumes character transmission from a communication device. + * + * RETURNS + * + * True on success and false if the communications device could not be found. + * + * BUGS + * + * Only TIOCSBRK and TIOCCBRK are supported. */ -BOOL WINAPI ClearCommBreak(HANDLE handle) +BOOL WINAPI ClearCommBreak( + HANDLE handle /* The halted communication device whose character transmission is to be resumed. */) { #if defined(TIOCSBRK) && defined(TIOCCBRK) /* check if available for compilation */ int fd,result; @@ -1706,8 +1772,18 @@ BOOL WINAPI ClearCommBreak(HANDLE handle) /***************************************************************************** * EscapeCommFunction (KERNEL32.214) + * + * Directs a communication device to perform an extended function. + * + * RETURNS + * + * True or requested data on successful completion of the command, + * false if the device is not present cannot execute the command + * or the command failed. */ -BOOL WINAPI EscapeCommFunction(HANDLE handle,UINT nFunction) +BOOL WINAPI EscapeCommFunction( + HANDLE handle, /* The communication device to perform the extended function. */ + UINT nFunction /* The extended function to be performed. */) { int fd,direct=FALSE,result=FALSE; struct termios port; @@ -1814,8 +1890,17 @@ BOOL WINAPI EscapeCommFunction(HANDLE handle,UINT nFunction) /******************************************************************** * PurgeComm (KERNEL32.557) + * + * Terminates pending operations and/or discards buffers on a + * communication resource. + * + * RETURNS + * + * True on success and false if the communications handle is bad. */ -BOOL WINAPI PurgeComm( HANDLE handle, DWORD flags) +BOOL WINAPI PurgeComm( + HANDLE handle, /* The communication resource to be purged. */ + DWORD flags /* Flags for clear pending/buffer on input/output. */) { int fd; @@ -1847,8 +1932,18 @@ BOOL WINAPI PurgeComm( HANDLE handle, DWORD flags) /***************************************************************************** * ClearCommError (KERNEL32.21) + * + * Enables further I/O operations on a communications resource after + * supplying error and current status information. + * + * RETURNS + * + * True on success, false if the communication resource handle is bad. */ -BOOL WINAPI ClearCommError(HANDLE handle,LPDWORD errors,LPCOMSTAT lpStat) +BOOL WINAPI ClearCommError( + HANDLE handle, /* The communication resource with the error. */ + LPDWORD errors, /* Flags indicating error the resource experienced. */ + LPCOMSTAT lpStat /* The status of the communication resource. */) { int fd; @@ -1896,8 +1991,22 @@ BOOL WINAPI ClearCommError(HANDLE handle,LPDWORD errors,LPCOMSTAT lpStat) /***************************************************************************** * SetupComm (KERNEL32.676) + * + * Called after CreateFile to hint to the communication resource to use + * specified sizes for input and output buffers rather than the default values. + * + * RETURNS + * + * True if successful, false if the communications resource handle is bad. + * + * BUGS + * + * Stub. */ -BOOL WINAPI SetupComm( HANDLE handle, DWORD insize, DWORD outsize) +BOOL WINAPI SetupComm( + HANDLE handle, /* The just created communication resource handle. */ + DWORD insize, /* The suggested size of the communication resources input buffer in bytes. */ + DWORD outsize /* The suggested size of the communication resources output buffer in bytes. */) { int fd; @@ -1913,8 +2022,17 @@ BOOL WINAPI SetupComm( HANDLE handle, DWORD insize, DWORD outsize) /***************************************************************************** * GetCommMask (KERNEL32.156) + * + * Obtain the events associated with a communication device that will cause a call + * WaitCommEvent to return. + * + * RETURNS + * + * True on success, fail on bad device handle etc. */ -BOOL WINAPI GetCommMask(HANDLE handle,LPDWORD evtmask) +BOOL WINAPI GetCommMask( + HANDLE handle, /* The communications device. */ + LPDWORD evtmask /* The events which cause WaitCommEvent to return. */) { BOOL ret; @@ -1935,8 +2053,18 @@ BOOL WINAPI GetCommMask(HANDLE handle,LPDWORD evtmask) /***************************************************************************** * SetCommMask (KERNEL32.451) + * + * There be some things we need to hear about yon there communications device. + * (Set which events associated with a communication device should cause + * a call WaitCommEvent to return.) + * + * RETURNS + * + * True on success, false on bad handle etc. */ -BOOL WINAPI SetCommMask(HANDLE handle,DWORD evtmask) +BOOL WINAPI SetCommMask( + HANDLE handle, /* The communications device. */ + DWORD evtmask /* The events that to be monitored. */) { BOOL ret; @@ -1956,12 +2084,21 @@ BOOL WINAPI SetCommMask(HANDLE handle,DWORD evtmask) /***************************************************************************** * SetCommState (KERNEL32.452) + * + * Re-initializes all hardware and control settings of a communications device, + * with values from a device control block without effecting the input and output + * queues. + * + * RETURNS + * + * True on success, false on failure eg if the XonChar is equal to the XoffChar. */ -BOOL WINAPI SetCommState(HANDLE handle,LPDCB lpdcb) +BOOL WINAPI SetCommState( + HANDLE handle, /* The communications device. */ + LPDCB lpdcb /* The device control block. */) { struct termios port; - int fd; - int bytesize, stopbits; + int fd, bytesize, stopbits; TRACE("handle %d, ptr %p\n", handle, lpdcb); TRACE("bytesize %d baudrate %ld fParity %d Parity %d stopbits %d\n", @@ -2257,8 +2394,20 @@ BOOL WINAPI SetCommState(HANDLE handle,LPDCB lpdcb) /***************************************************************************** * GetCommState (KERNEL32.159) + * + * Fills in a device control block with information from a communications device. + * + * RETURNS + * + * True on success, false if the communication device handle is bad etc + * + * BUGS + * + * XonChar and XoffChar are not set. */ -BOOL WINAPI GetCommState(HANDLE handle, LPDCB lpdcb) +BOOL WINAPI GetCommState( + HANDLE handle, /* The communications device. */ + LPDCB lpdcb /* The device control block. */) { struct termios port; int fd,speed; @@ -2449,8 +2598,22 @@ BOOL WINAPI GetCommState(HANDLE handle, LPDCB lpdcb) /***************************************************************************** * TransmitCommChar (KERNEL32.535) + * + * Transmits a single character in front of any pending characters in the + * output buffer. Usually used to send an interrupt character to a host. + * + * RETURNS + * + * True if the call succeeded, false if the previous command character to the + * same device has not been sent yet the handle is bad etc. + * + * BUGS + * + * Stub. */ -BOOL WINAPI TransmitCommChar(HANDLE hComm,CHAR chTransmit) +BOOL WINAPI TransmitCommChar( + HANDLE hComm, /* The communication device in need of a command character. */ + CHAR chTransmit /* The character to transmit. */) { FIXME("(%x,'%c'), use win32 handle!\n",hComm,chTransmit); return TRUE; @@ -2458,8 +2621,17 @@ BOOL WINAPI TransmitCommChar(HANDLE hComm,CHAR chTransmit) /***************************************************************************** * GetCommTimeouts (KERNEL32.160) + * + * Obtains the request time out values for the communications device. + * + * RETURNS + * + * True on success, false if communications device handle is bad + * or the target structure is null. */ -BOOL WINAPI GetCommTimeouts(HANDLE hComm,LPCOMMTIMEOUTS lptimeouts) +BOOL WINAPI GetCommTimeouts( + HANDLE hComm, /* The communications device. */ + LPCOMMTIMEOUTS lptimeouts /* The struct of request time outs. */) { BOOL ret; @@ -2499,6 +2671,10 @@ BOOL WINAPI GetCommTimeouts(HANDLE hComm,LPCOMMTIMEOUTS lptimeouts) * - used in ReadFile to calculate GetOverlappedResult's timeout * WriteTotalTimeoutMultiplier, WriteTotalTimeoutConstant * - used in WriteFile to calculate GetOverlappedResult's timeout + * + * RETURNS + * + * True if the time outs were set, false otherwise. */ BOOL WINAPI SetCommTimeouts( HANDLE hComm, /* [in] handle of COMM device */ @@ -2554,8 +2730,17 @@ BOOL WINAPI SetCommTimeouts( /*********************************************************************** * GetCommModemStatus (KERNEL32.285) + * + * Obtains the four control register bits if supported by the hardware. + * + * RETURNS + * + * True if the communications handle was good and for hardware that + * control register access, false otherwise. */ -BOOL WINAPI GetCommModemStatus(HANDLE hFile,LPDWORD lpModemStat ) +BOOL WINAPI GetCommModemStatus( + HANDLE hFile, /* The communications device. */ + LPDWORD lpModemStat /* The control register bits. */) { int fd,mstat, result=FALSE; @@ -2844,10 +3029,18 @@ BOOL WINAPI CommConfigDialogW( * * TRUE on success, FALSE on failure * If successful, lpCommConfig contains the comm port configuration. + * + * BUGS + * + * The signature is missing a the parameter for the size of the COMMCONFIG + * structure/buffer it should be + * BOOL WINAPI GetCommConfig(HANDLE hFile,LPCOMMCONFIG lpCommConfig,LPDWORD lpdwSize) */ BOOL WINAPI GetCommConfig( - HANDLE hFile, - LPCOMMCONFIG lpCommConfig + HANDLE hFile, /* The communications device. */ + LPCOMMCONFIG lpCommConfig /* The communications configuration of the device (if it fits). */ + /* LPDWORD lpdwSize Initially the size of the configuration buffer/structure, + afterwards the number of bytes copied to the buffer or the needed size of the buffer. */ ) { BOOL r; @@ -2870,26 +3063,34 @@ BOOL WINAPI GetCommConfig( /*********************************************************************** * SetCommConfig (KERNEL32.617) * + * Sets the configuration of the commications device. + * + * RETURNS + * + * True on success, false if the handle was bad is not a communications device. */ BOOL WINAPI SetCommConfig( - HANDLE hFile, - LPCOMMCONFIG lpCommConfig + HANDLE hFile, /* The communications device. */ + LPCOMMCONFIG lpCommConfig /* The desired configuration. */ ) { - BOOL r; - TRACE("(%x %p)\n",hFile,lpCommConfig); - - r = SetCommState(hFile,&lpCommConfig->dcb); - return r; + return SetCommState(hFile,&lpCommConfig->dcb); } /*********************************************************************** * SetDefaultCommConfigA (KERNEL32.638) + * + * Initializes the default configuration for the specified communication + * device. (ascii) + * + * RETURNS + * + * True if the device was found and the defaults set, false otherwise */ BOOL WINAPI SetDefaultCommConfigA( - LPCSTR lpszDevice, - LPCOMMCONFIG lpCommConfig, - DWORD dwSize + LPCSTR lpszDevice, /* The ascii name of the device targeted for configuration. */ + LPCOMMCONFIG lpCommConfig, /* The default configuration for the device. */ + DWORD dwSize /* The number of bytes in the configuration structure. */ ) { FARPROC lpfnSetDefaultCommConfig; HMODULE hConfigModule; @@ -2917,11 +3118,16 @@ BOOL WINAPI SetDefaultCommConfigA( /*********************************************************************** * SetDefaultCommConfigW (KERNEL32.639) * + * Initializes the default configuration for the specified + * communication device. (unicode) + * + * RETURNS + * */ BOOL WINAPI SetDefaultCommConfigW( - LPCWSTR lpszDevice, - LPCOMMCONFIG lpCommConfig, - DWORD dwSize + LPCWSTR lpszDevice, /* The unicode name of the device targeted for configuration. */ + LPCOMMCONFIG lpCommConfig, /* The default configuration for the device. */ + DWORD dwSize /* The number of bytes in the configuration structure. */ ) { BOOL r; LPSTR lpDeviceA; @@ -2939,10 +3145,20 @@ BOOL WINAPI SetDefaultCommConfigW( /*********************************************************************** * GetDefaultCommConfigA (KERNEL32.313) + * + * Acquires the default configuration of the specified communication device. (unicode) + * + * RETURNS + * + * True on successful reading of the default configuration, + * if the device is not found or the buffer is too small. */ -BOOL WINAPI GetDefaultCommConfigA(LPCSTR lpszName,LPCOMMCONFIG lpCC, - LPDWORD lpdwSize) -{ +BOOL WINAPI GetDefaultCommConfigA( + LPCSTR lpszName, /* The ascii name of the device targeted for configuration. */ + LPCOMMCONFIG lpCC, /* The default configuration for the device. */ + LPDWORD lpdwSize ) /* Initially the size of the default configuration buffer, + afterwards the number of bytes copied to the buffer or the needed size of the buffer. */ +{ LPDCB lpdcb = &(lpCC->dcb); char temp[40]; @@ -2976,17 +3192,30 @@ BOOL WINAPI GetDefaultCommConfigA(LPCSTR lpszName,LPCOMMCONFIG lpCC, /************************************************************************** * GetDefaultCommConfigW (KERNEL32.314) + * + * Acquires the default configuration of the specified communication device. (unicode) + * + * RETURNS + * + * True on successful reading of the default configuration, + * if the device is not found or the buffer is too small. */ -BOOL WINAPI GetDefaultCommConfigW( LPCWSTR lpszName,LPCOMMCONFIG lpCC, - LPDWORD lpdwSize) -{ +BOOL WINAPI GetDefaultCommConfigW( + LPCWSTR lpszName, /* The unicode name of the device targeted for configuration. */ + LPCOMMCONFIG lpCC, /* The default configuration for the device. */ + LPDWORD lpdwSize /* Initially the size of the default configuration buffer, + afterwards the number of bytes copied to the buffer or the needed size of the buffer. */ +) { + BOOL ret = FALSE; LPSTR lpszNameA; - BOOL ret; TRACE("(%p,%p,%ld)\n",lpszName,lpCC,*lpdwSize); lpszNameA = HEAP_strdupWtoA( GetProcessHeap(), 0, lpszName ); + if (lpszNameA) + { ret=GetDefaultCommConfigA(lpszNameA,lpCC,lpdwSize); HeapFree( GetProcessHeap(), 0, lpszNameA ); + } return ret; } diff --git a/dlls/kernel/debugger.c b/dlls/kernel/debugger.c index 39b7fc9c815..77c4d221065 100644 --- a/dlls/kernel/debugger.c +++ b/dlls/kernel/debugger.c @@ -19,15 +19,16 @@ DEFAULT_DEBUG_CHANNEL(debugstr); /****************************************************************************** * WaitForDebugEvent (KERNEL32.720) * - * Waits for a debugging event to occur in a process being debugged + * Waits for a debugging event to occur in a process being debugged before + * filling out the debug event structure. * - * PARAMS - * event [I] Address of structure for event information - * timeout [I] Number of milliseconds to wait for event + * RETURNS * - * RETURNS STD + * Returns true if a debug event occurred and false if the call timed out. */ -BOOL WINAPI WaitForDebugEvent( LPDEBUG_EVENT event, DWORD timeout ) +BOOL WINAPI WaitForDebugEvent( + LPDEBUG_EVENT event, /* Address of structure for event information. */ + DWORD timeout /* Number of milliseconds to wait for event. */) { BOOL ret; SERVER_START_REQ @@ -111,8 +112,18 @@ BOOL WINAPI WaitForDebugEvent( LPDEBUG_EVENT event, DWORD timeout ) /********************************************************************** * ContinueDebugEvent (KERNEL32.146) + * + * Enables a thread that previously produced a debug event to continue. + * + * RETURNS + * + * True if the debugger is listed as the processes owner and the process + * and thread are valid. */ -BOOL WINAPI ContinueDebugEvent( DWORD pid, DWORD tid, DWORD status ) +BOOL WINAPI ContinueDebugEvent( + DWORD pid, /* The id of the process to continue. */ + DWORD tid, /* The id of the thread to continue. */ + DWORD status /* The rule to apply to unhandled exeptions. */) { BOOL ret; SERVER_START_REQ @@ -130,8 +141,15 @@ BOOL WINAPI ContinueDebugEvent( DWORD pid, DWORD tid, DWORD status ) /********************************************************************** * DebugActiveProcess (KERNEL32.180) + * + * Attempts to attach the dugger to a process. + * + * RETURNS + * + * True if the debugger was attached to process. */ -BOOL WINAPI DebugActiveProcess( DWORD pid ) +BOOL WINAPI DebugActiveProcess( + DWORD pid /* The process to be debugged. */) { BOOL ret; SERVER_START_REQ @@ -147,8 +165,12 @@ BOOL WINAPI DebugActiveProcess( DWORD pid ) /*********************************************************************** * OutputDebugStringA (KERNEL32.548) + * + * Output by an application of a unicode string to a debugger (if attached) + * and program log. */ -void WINAPI OutputDebugStringA( LPCSTR str ) +void WINAPI OutputDebugStringA( + LPCSTR str /* The message to be logged and given to the debugger. */) { SERVER_START_REQ { @@ -165,8 +187,12 @@ void WINAPI OutputDebugStringA( LPCSTR str ) /*********************************************************************** * OutputDebugStringW (KERNEL32.549) + * + * Output by an appliccation of a unicode string to a debugger (if attached) + * and program log. */ -void WINAPI OutputDebugStringW( LPCWSTR str ) +void WINAPI OutputDebugStringW( + LPCWSTR str /* The message to be logged and given to the debugger. */) { SERVER_START_REQ { @@ -183,8 +209,12 @@ void WINAPI OutputDebugStringW( LPCWSTR str ) /*********************************************************************** * OutputDebugString16 (KERNEL.115) + * + * Output by a 16 bit application of an ascii string to a debugger (if attached) + * and program log. */ -void WINAPI OutputDebugString16( LPCSTR str ) +void WINAPI OutputDebugString16( + LPCSTR str /* The message to be logged and given to the debugger.*/) { OutputDebugStringA( str ); } @@ -192,6 +222,9 @@ void WINAPI OutputDebugString16( LPCSTR str ) /*********************************************************************** * DebugBreak (KERNEL32.181) + * + * Raises an exception so that a debugger (if attached) + * can take some action. */ void WINAPI DebugBreak(void) { @@ -201,8 +234,16 @@ void WINAPI DebugBreak(void) /*********************************************************************** * DebugBreak16 (KERNEL.203) + * + * Raises an expection in a 16 bit application so that a debugger (if attached) + * can take some action. + * + * BUGS + * + * Only 386 compatible processors implemented. */ -void WINAPI DebugBreak16( CONTEXT86 *context ) +void WINAPI DebugBreak16( + CONTEXT86 *context /* A pointer to the 386 compatible processor state. */) { #ifdef __i386__ EXCEPTION_RECORD rec; @@ -219,6 +260,12 @@ void WINAPI DebugBreak16( CONTEXT86 *context ) /*********************************************************************** * IsDebuggerPresent (KERNEL32) + * + * Allows a process to determine if there is a debugger attached. + * + * RETURNS + * + * True if there is a debugger attached. */ BOOL WINAPI IsDebuggerPresent(void) { diff --git a/dlls/kernel/time.c b/dlls/kernel/time.c index 8bfdd2114e6..933e74bf901 100644 --- a/dlls/kernel/time.c +++ b/dlls/kernel/time.c @@ -33,10 +33,15 @@ static int TIME_GetBias( time_t utc, int *pdaylight) /*********************************************************************** * SetLocalTime (KERNEL32.655) * - * FIXME: correct ? Is the timezone param of settimeofday() needed ? - * I don't have any docu about SetLocal/SystemTime(), argl... + * Sets 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. */ -BOOL WINAPI SetLocalTime(const SYSTEMTIME *systime) +BOOL WINAPI SetLocalTime( const SYSTEMTIME *systime /* The desired local time. */ ) { struct timeval tv; struct tm t; @@ -80,10 +85,22 @@ BOOL WINAPI SetLocalTime(const SYSTEMTIME *systime) /*********************************************************************** * GetSystemTimeAdjustment (KERNEL32.407) * + * 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. + * + * RETURNS + * + * Always returns true. + * + * BUGS + * + * Only the special case of disabled time adjustments is supported. + * (also the signature is wrong it should have a return type of BOOL) */ -DWORD WINAPI GetSystemTimeAdjustment( LPDWORD lpTimeAdjustment, - LPDWORD lpTimeIncrement, - LPBOOL lpTimeAdjustmentDisabled ) +DWORD WINAPI GetSystemTimeAdjustment( + LPDWORD lpTimeAdjustment, /* The clock adjustment per interupt in 100's of nanoseconds. */ + LPDWORD lpTimeIncrement, /* The time between clock interupts in 100's of nanoseconds. */ + LPBOOL lpTimeAdjustmentDisabled /* The clock synchonisation has been disabled. */ ) { *lpTimeAdjustment = 0; *lpTimeIncrement = 0; @@ -94,8 +111,16 @@ DWORD WINAPI GetSystemTimeAdjustment( LPDWORD lpTimeAdjustment, /*********************************************************************** * SetSystemTime (KERNEL32.507) + * + * Sets the system time (utc). + * + * RETURNS + * + * True if the time was set, false if the time was invalid or the + * necessary permissions were not held. */ -BOOL WINAPI SetSystemTime(const SYSTEMTIME *systime) +BOOL WINAPI SetSystemTime( + const SYSTEMTIME *systime /* The desired system time. */) { struct timeval tv; struct timezone tz; @@ -147,8 +172,16 @@ BOOL WINAPI SetSystemTime(const SYSTEMTIME *systime) /*********************************************************************** * GetTimeZoneInformation (KERNEL32.302) + * + * Fills in the a time zone information structure with values based on + * the current local time. + * + * RETURNS + * + * The daylight savings time standard or TIME_ZONE_ID_INVALID if the call failed. */ -DWORD WINAPI GetTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo) +DWORD WINAPI GetTimeZoneInformation( + LPTIME_ZONE_INFORMATION tzinfo /* The time zone structure to be filled in. */) { time_t gmt; int bias, daylight; @@ -168,8 +201,19 @@ DWORD WINAPI GetTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo) /*********************************************************************** * SetTimeZoneInformation (KERNEL32.515) + * + * Set the local time zone with values based on the time zone structure. + * + * RETURNS + * + * True on successful setting of the time zone. + * + * BUGS + * + * Use the obsolete unix timezone structure and tz_dsttime member. */ -BOOL WINAPI SetTimeZoneInformation(const LPTIME_ZONE_INFORMATION tzinfo) +BOOL WINAPI SetTimeZoneInformation( + const LPTIME_ZONE_INFORMATION tzinfo /* The new time zone. */) { struct timezone tz; @@ -185,11 +229,21 @@ BOOL WINAPI SetTimeZoneInformation(const LPTIME_ZONE_INFORMATION tzinfo) /*********************************************************************** * SystemTimeToTzSpecificLocalTime (KERNEL32.683) + * + * Converts the system time (utc) to the local time in the specified time zone. + * + * RETURNS + * + * Returns true when the local time was calculated. + * + * BUGS + * + * Does not handle daylight savings time adjustments correctly. */ BOOL WINAPI SystemTimeToTzSpecificLocalTime( - LPTIME_ZONE_INFORMATION lpTimeZoneInformation, - LPSYSTEMTIME lpUniversalTime, - LPSYSTEMTIME lpLocalTime) + LPTIME_ZONE_INFORMATION lpTimeZoneInformation, /* The desired time zone. */ + LPSYSTEMTIME lpUniversalTime, /* The utc time to base local time on. */ + LPSYSTEMTIME lpLocalTime /* The local time in the time zone. */) { FIXME(":stub\n"); SetLastError(ERROR_CALL_NOT_IMPLEMENTED); @@ -199,18 +253,21 @@ BOOL WINAPI SystemTimeToTzSpecificLocalTime( /*********************************************************************** * GetSystemTimeAsFileTime (KERNEL32) + * + * Fills in a file time structure with the current time in UTC format. */ -VOID WINAPI GetSystemTimeAsFileTime( LPFILETIME time ) +VOID WINAPI GetSystemTimeAsFileTime( + LPFILETIME time /* The file time struct to be filled with the system time. */) { NtQuerySystemTime( (LARGE_INTEGER *)time ); } /********************************************************************* - * TIME_ClockTimeToFileTime - * (olorin@fandra.org, 20-Sep-1998) - * Converts clock_t into FILETIME. - * Used by GetProcessTime. + * TIME_ClockTimeToFileTime (olorin@fandra.org, 20-Sep-1998) + * + * Used by GetProcessTimes to convert clock_t into FILETIME. + * * Differences to UnixTimeToFileTime: * 1) Divided by CLK_TCK * 2) Time is relative. There is no 'starting date', so there is @@ -225,14 +282,27 @@ static void TIME_ClockTimeToFileTime(clock_t unix_time, LPFILETIME filetime) /********************************************************************* * GetProcessTimes [KERNEL32.262] * - * FIXME: lpCreationTime, lpExitTime are NOT INITIALIZED. - * olorin@fandra.org: Would be nice to substract the cpu time, - * used by Wine at startup. - * Also, there is a need to separate times - * used by different applications. + * Returns the user and kernel execution times of a process, + * along with the creation and exit times if known. + * + * olorin@fandra.org: + * 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. */ -BOOL WINAPI GetProcessTimes( HANDLE hprocess,LPFILETIME lpCreationTime,LPFILETIME lpExitTime, - LPFILETIME lpKernelTime, LPFILETIME lpUserTime ) +BOOL WINAPI GetProcessTimes( + HANDLE hprocess, /* The process to be queried (obtained from PROCESS_QUERY_INFORMATION). */ + LPFILETIME lpCreationTime, /* The creation time of the process. */ + LPFILETIME lpExitTime, /* The exit time of the process if exited. */ + LPFILETIME lpKernelTime, /* The time spent in kernal routines in 100's of nanoseconds. */ + LPFILETIME lpUserTime /* The time spent in user routines in 100's of nanoseconds. */) { struct tms tms;