HRESULTs

Many, if not most of the GI calls in SkyGI return HRESULTs. What is an HRESULT exactly? It couldn't be more simple. It's just a typedef'd long. HRESULTs just make code a little bit easier to understand. Instead of return 0 on success and 1 on failure, HRESULT returning functions return S_OK and S_FALSE respectively.

Let's look at possible HRESULTs:

Success Codes:
These will be returned when a function succeeds, or actually, when the 
function doesn't go down in flames.  Note the 'S' prefix means 
'success.'
S_OK: No error.  Function call succeeded.
S_FALSE: No error, but the call failed.

Error Codes:
These will be returned when the function call does go down in flames.  
Some have names that make their meanings completely obvious.  Others... 
well, no one but Robert himself know what they mean.  Note, the 'E' 
prefix means 'error.'
E_UNEXPECTED
E_NOTIMPL
E_ACCESSDENIED
E_HANDLE
E_OUTOFMEMORY
E_INVALIDARG
E_NOINTERFACE
E_POINTER
E_ABORT
E_FAIL
E_FAIL_DEBUG_TXT
E_PIPE
E_AGAIN

Disk and filesystem Error Codes:
E_DISK_SPACE
E_DISK_READ_ERROR
E_DISK_WRITE_ERROR
E_IO_ERROR
E_FILE_NOT_FOUND
E_FILE_TOO_MANY_OPEN_FILES
E_FILE_NO_DIRECTORY
E_FILE_IS_DIRECTORY
E_FILE_EOF
E_WOULD_BLOCK
E_FILE_IS_PIPE
E_PIPE_ERROR
E_TIMEOUT
E_FILE_EXISTS

Network Error Codes:
E_NETIF_OPEN
E_NETIF_CLOSE
E_LIBNET_DEVICE_UNKNOWN
E_LIBNET_DHCP_FAILED
E_LIBNET_PPP_OPEN_SERIAL
E_NETIF_BUFFER
E_NO_ROUTE
E_BUSY
E_INTERRUPTED

ISS Error Codes:
E_ISS_BUSY
E_ISS_UNKNOWN_FILE_FORMAT
E_ISS_NOT_SUPPORTED
E_ISS_END_OF_FILE

If these HRESULTs are not enough for your program, Robert was even so kind as to include a "MAKE_HRESULT" macro. The macro is as follows:

#define MAKE_HRESULT(sev, fac, code) \
    ((HRESULT) (((unsigned long)(sev)<<31) | ((unsigned long)(fac)<<16) | ((unsigned long)(code))) )

The parameters' have the following meanings:
sev - Severity code
fac - The facility code
code - The facility's status code

All HRESULTs' severity codes are '800' so I'd suggest keeping with tradition and making your custom HRESULTs also begin with an '800.' The facility codes determine what type of function returned the error. Some Predefined HRESULTs groups have the following severity codes:

Success: 000
Disk: 800
Filesystem: 900
ISS: 200

These facility codes are not enforced. Robert doesn't seem to keep up with them himself. Network HRESULTs many times have the same facility number as disk errors. Not to worry though, these numbers are completely arbitrary.

Finally, the facility's status code is whatever you'd like it to be. One word of advice when creating custom HRESULTs is to make sure your HRESULT is unique so that when you think your function is returning S_OK, your program doesn't interpret it as E_COMPUTER_ON_FIRE.