You Can Do This Too

[Previous] [Next]

OK, I've shown you how Windows functions indicate errors to their callers. Microsoft also makes this mechanism available to you for use in your own functions. 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 up into the fields shown in the following table.

Bits:	31-30	29	28	27-16	15-0
Contents	Severity	Microsoft/ customer	Reserved	Facility code	Exception code
Meaning	0 = Success 1 = Informational 2 = Warning 3 = Error	0 = Microsoft- defined code 1 = customer- defined code	Must be 0	Microsoft-defined	Microsoft/customer-defined

These fields are discussed in detail in Chapter 24. For now, the only important field you need to be aware of is in bit 29. Microsoft promises that all error codes they produce will have a 0 in this bit. If you create your own error codes, you must put a 1 in this bit. This way, you're guaranteed that your error code will never conflict with a Microsoft-defined error code that currently exists or is created in the future.