Win32 File API GetLastError function

Download EaseFilter Monitor, Control and Encryption Filter Driver SDK Setup File
Download EaseFilter Monitor, Control and Encryption Filter Driver SDK Zip File

Retrieves the calling thread's last-error code value. The last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other's last-error code.

Visual Basic:  Applications should call err.LastDllError instead of GetLastError.

Syntax

  
DWORD WINAPI GetLastError(void);
  
          

Parameters

This function has no parameters.

Return value

The return value is the calling thread's last-error code.

The Return Value section of the documentation for each function that sets the last-error code notes the conditions under which the function sets the last-error code. Most functions that set the thread's last-error code set it when they fail. However, some functions also set the last-error code when they succeed. If the function is not documented to set the last-error code, the value returned by this function is simply the most recent last-error code to have been set; some functions set the last-error code to 0 on success and others do not.

Remarks

Functions executed by the calling thread set this value by calling the SetLastError function. You should call the GetLastError function immediately when a function's return value indicates that such a call will return useful data. That is because some functions call SetLastError with a zero when they succeed, wiping out the error code set by the most recently failed function.

To obtain an error string for system error codes, use the FormatMessage function. For a complete list of error codes provided by the operating system, see System Error Codes.

The error codes returned by a function are not part of the Windows API specification and can vary by operating system or device driver. For this reason, we cannot provide the complete list of error codes that can be returned by each function. There are also many functions whose documentation does not include even a partial list of error codes that can be returned.

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no system error code has this bit set. If you are defining an error code for your application, set this bit to one. That indicates that the error code has been defined by an application, and ensures that your error code does not conflict with any error codes defined by the system.

To convert a system error into an HRESULT value, use the HRESULT_FROM_WIN32 macro.

Examples

The following example includes an error-handling function that prints the error message and terminates the process. The lpszFunction parameter is the name of the function that set the last-error code.

#include <windows.h>  
#include <strsafe.h>    
void ErrorExit(LPTSTR lpszFunction)   
{       // Retrieve the system error message for the last-error code        
		LPVOID lpMsgBuf;      
        LPVOID lpDisplayBuf;      
        DWORD dw = GetLastError();  
       
        FormatMessage(          
        			FORMAT_MESSAGE_ALLOCATE_BUFFER |           
                    FORMAT_MESSAGE_FROM_SYSTEM |          
                    FORMAT_MESSAGE_IGNORE_INSERTS,         
                    NULL,          
                    dw,          
                    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),          
                    (LPTSTR) &lpMsgBuf,          
                    0, NULL );        
                   
              // Display the error message and exit the process        
             
            lpDisplayBuf = (LPVOID)LocalAlloc(LMEM_ZEROINIT,           
            (lstrlen((LPCTSTR)lpMsgBuf) + lstrlen((LPCTSTR)lpszFunction) + 40) * sizeof(TCHAR));      
            StringCchPrintf((LPTSTR)lpDisplayBuf,           
            LocalSize(lpDisplayBuf) / sizeof(TCHAR),          
            TEXT("%s failed with error %d: %s"),           
            lpszFunction, dw, lpMsgBuf);       
            MessageBox(NULL, (LPCTSTR)lpDisplayBuf, TEXT("Error"), MB_OK);        
            LocalFree(lpMsgBuf);      
            LocalFree(lpDisplayBuf);      
            ExitProcess(dw);  
  }    
                    
void main()  
{      
// Generate an error       
 if(!GetProcessId(NULL))         
   ErrorExit(TEXT("GetProcessId"));  
}