Error Handling

This post is the summarize of Ch1 "Error Handling" of Windows via C/C++, Fifth Edition Jeffrey Richter (Wintellect) Christophe Nasarre book.

Microsoft Windows is a complex operating system. It offers so many features and does so much that it's impossible for any one person to fully understand the entire system.This book teaches the reader about various Windows features and how to access them via the C and C++ programming languages. Although this book does not cover some Windows concepts such as the Component Object Model (COM). COM is built on top of basic building blocks such as processes, threads, memory management, DLLs, thread local storage, Unicode, and so on. If you know these basic building blocks, understanding COM is just a matter of understanding how the building blocks are used. 

64-Bit Windows:

 Machines based on these 64-bit CPU architectures are fast gaining acceptance. Microsoft has stated that Windows Server 2008 will be the last 32-bit version of Windows ever! For developers, now is the time to focus on making sure your applications run correctly on 64-bit Windows.

 The biggest advantage your application gets from a 64-bit address space is the ability to easily manipulate large amounts of data, because your process is no longer constrained to a 2-GB usable address space. Even if your application doesn't need all this address space, Windows itself takes advantage of the significantly larger address space (about 8 terabytes), allowing it to run faster.

Here is a quick look at what you need to know about 64-bit Windows:

• The 64-bit Windows kernel is a port of the 32-bit Windows kernel. This means that all the details and intricacies that you've learned about 32-bit Windows still apply in the 64-bit world.
• Because the kernels use the same code and underlying concepts, the Windows API is identical on both platforms. This means that you do not have to redesign or reimplement your application to work on 64-bit Windows. You can simply make slight modifications to your source code and then rebuild.
• For backward compatibility, 64-bit Windows can execute 32-bit applications. However. Because it is so easy to port 32-bit code, there are already device drivers, tools, and applications available for 64-bit Windows.
• There is little new for you to learn. You'll be happy to know that most data types remain 32 bits wide. These include ints, DWORDs, LONGs, BOOLs, and so on. In fact, you mostly just need to worry about pointers and handles, since they are now 64-bit values.

Common Return Types for Windows Functions:

• VOID: This function cannot possibly fail. Very few Windows functions have a return type of VOID.
• BOOL:  If the function fails, the return value is 0; otherwise, the return value is non-zero. Avoid testing the return value to see if it is TRUE: it is always best to test this return value to see if it is different from FALSE.
• HANDLE:  If the function fails, the return value is usually NULL; otherwise, the HANDLE identifies an object that you can manipulate. Be careful with this one because some functions return a handle value of INVALID_HANDLE_VALUE, which is defined as -1. The Platform SDK documentation for the function will clearly state whether the function returns NULL or INVALID_HANDLE_VALUE to indicate failure.
• PVOID:  If the function fails, the return value is NULL; otherwise, PVOID identifies the memory address of a data block.
• LONG/DWORD: This is a tough one. Functions that return counts usually return a LONG or DWORD. If for some reason the function can't count the thing you want counted, the function usually returns 0 or -1 (depending on the function). If you are calling a function that returns a LONG/DWORD, please read the Platform SDK documentation carefully to ensure that you are properly checking for potential errors.

DWORD GetLastError(); This function simply returns the thread's 32-bit error code set by the last function call.

Now that you have the 32-bit error code number, you need to translate that number into something more useful. The WinError.h header file contains the list of Microsoft-defined error codes. I'll reproduce some of it here so that you can see what it looks like:

// MessageId: ERROR_SUCCESS

//

// MessageText:

//

// The operation completed successfully.

//

#define ERROR_SUCCESS                 0L

#define NO_ERROR                      0L         // dderror

#define SEC_E_OK                      ((HRESULT)0x00000000L)

//

// MessageId: ERROR_FILE_NOT_FOUND

//

// MessageText:

//

// The system cannot find the file specified.

//

#define ERROR_FILE_NOT_FOUND          2L

When a Windows function fails, you should call GetLastError right away because the value is very likely to be overwritten if you call another Windows function. Notice that a Windows function that succeeds might overwrite this value with ERROR_SUCCESS.

Some Windows functions can succeed for several reasons. For example, attempting to create a named event kernel object can succeed either because you actually create the object or because an event kernel object with the same name already exists. So when certain functions succeed, you can determine additional information by calling GetLastError. For  an example where ERROR_ALREADY_EXISTS is returned when a named event already exists.

Defining Your Own Error Codes:

Let's say you're writing a function that you expect others to call. Your function might fail for one reason or another and you need to indicate that failure back to your caller.

To indicate failure, simply set the thread's last error code and then have your function return FALSE, INVALID_HANDLE_VALUE, NULL, or whatever is appropriate. To set the thread's last error code, you simply call VOID SetLastError(DWORD dwErrCode); passing into the function whatever 32-bit number you think is appropriate. I try to use codes that already exist in WinError.h as long as the code maps well to the error I'm trying to report. If you don't think that any of the codes in WinError.h accurately reflect the error, you can create your own code.

The error code is a 32-bit number that is divided into the fields shown in Table bellow.